This article is a continuation of the Series on RT-Thread STM32 Tutorials and carries the discussion on RT-Thread RTOS and implementation with STM32. The aim of this series is to provide easy and practical examples that anyone can understand. In our last post, we have seen Threads in the RT-Thread RTOS. In this post, we will see the RT-Thread RTOS Timer Management.
You can see the video explanation of Getting started with the RT-Thread RTOS.
Table of Contents
Prerequisites
This is the continuation of the below tutorials. If you don’t read it, please read that also before this.
- RT-Thread RTOS Introduction
- Getting started with RT-Thread RTOS – Part 1
- Thread management of RT-Thread RTOS
Tools and Components Required
- STM32F411 Dev Board (You can use any STM32F4 controller)
- RT-Thread Studio
Timer
A timer (sometimes referred to as a counter) is a special piece of hardware inside many microcontrollers. Timers play an essential role in embedded systems, and In any MCU timer is one of the most essential features. Without a timer all time critical operations won’t work.
Clock tick
The smallest time unit in the operating system is the clock tick (OS Tick). It is simply 1 clock cycle. The microcontroller and all its peripherals run with respect to a continuous square wave. In every clock cycle, it increments the clock ticks by running one line of assembly code. A clock tick is a specific periodic interrupt. This interrupt can be regarded as the system heartbeat. In FreeRTOS, they call it as SysTicks.
Any operating system needs to provide a clock tick for the system to handle all time-related events, such as thread latency, thread time slice rotation scheduling, timer timeout, etc.
In RT-Thread, the length of the clock tick can be adjusted using the RT_TICK_PER_SECOND, which is equal to 1/RT_TICK_PER_SECOND seconds.
Timer operation modes
Timers can operate in 2 modes
- One-time mode (One Shot mode) and
- Periodic mode
One-time mode
In One-time mode, we can set the timer to go off after a particular time duration, say 10 ms. Once started, the timer counts down and once it runs out it notifies the core and the timer gets disabled. This action is very similar to using a stopwatch in countdown mode.
Periodic mode
In periodic mode, once the timer runs out, it notifies the core, then instead of getting disabled, it automatically reloads the initial value and starts counting down again. Basically, all this mode does extra compared to the One-time mode is just the auto-restart!
Types of timers in RT-Thread
Two types of timers are available in the RT-Thread.
- Hardware Timer
- Software Timer
Hardware timer
It is the timing function provided by the chip itself. The hardware timer can be used by configuring the timer module into timer mode and setting the time. The hardware timer is accurate to nanosecond precision and it executes in an interrupt context. So, the execution time should be as short as possible, and the execution should not cause the current context to suspend and wait.
Software timer
It is a type of system interface provided by the operating system. It is built on the basis of the hardware timer to enable the system to provide a timer service with no constraint on numbers. This executes in thread context.
RT-Thread Timer APIs
Get Clock Tick
The below API is used to get the current clock tick in the RT-Thread.
rt_tick_t rt_tick_get(void);
The function returns the Current clock tick value.
Timer Management System Initialize
The timer management system needs to be initialized at the system startup. This can be done through the following function interface:
void rt_system_timer_init(void);
If you need to use the soft timer, then use the below function interface.
void rt_system_timer_thread_init(void);
Create the timer
There are two ways we can create the timer.
- Dynamic creation
- Static creation
You can use the below API to create the timer Dynamically.
rt_timer_t rt_timer_create(const char* name,
void (*timeout)(void* parameter),
void* parameter,
rt_tick_t time,
rt_uint8_t flag);
| Parameters | Description |
|---|---|
| name | Name of the timer |
| void (timeout) (void parameter) | Timer timeout function pointer (this function is called when the timer expires) |
| parameter | Entry parameter of the timer timeout function (when the timer expires, calling the timeout callback function will pass this parameter as the entry parameter to the timeout function) |
| time | Timeout of the timer, the unit is the clock tick |
| flag | Parameters when the timer is created. The supported values include one-shot timing, periodic timing, hardware timer, software timer, etc. (You can use multiple values with “OR”) |
| Return | —— |
| RT_NULL | Creation failed (usually returning RT_NULL due to insufficient system memory) |
| Timer Handle | Timer was created successfully. |
You can use the below API for static timer creation.
void rt_timer_init(rt_timer_t timer,
const char* name,
void (*timeout)(void* parameter),
void* parameter,
rt_tick_t time, rt_uint8_t flag);
| Parameters | Description |
|---|---|
| timer | Timer handle, pointing to the to-be-initialized timer control block |
| name | Name of the timer |
| void (timeout) (void parameter) | Timer timeout function pointer (this function is called when the timer expires) |
| parameter | Entry parameter of the timer timeout function (when the timer expires, the call timeout callback function will pass this parameter as the entry parameter to the timeout function) |
| time | Timeout of the timer, the unit is a clock tick |
| flag | Parameters of when the timer is created. The supported values include one-shot timing, periodic timing, hardware timer, and software timer (multiple values can be taken with OR). For details, see Creating a Timer. |
Delete the timer
If you have created the timer using the dynamic method, then you can use the below function to delete the timer.
rt_err_t rt_timer_delete(rt_timer_t timer);
If you have created the timer using the static method, then you can use the below function to delete the timer.
rt_err_t rt_timer_detach(rt_timer_t timer);
Start and Stop Timer
Once you create and initialize the timer, it won’t start running immediately. We need to start it manually by using the below function.
rt_err_t rt_timer_start(rt_timer_t timer);
If you want to stop the timer, you can use the below function.
rt_err_t rt_timer_stop(rt_timer_t timer);
Control the Timer
You can control the timer when it is running. The below function is used to set the time, get the time, and change the mode to one-shot or periodic and many.
rt_err_t rt_timer_control(rt_timer_t timer, rt_uint8_t cmd, void* arg);
| Parameters | Description |
|---|---|
| timer | Timer handle |
| cmd | The command for controlling the timer currently supports four command interfaces, which are setting timing, viewing the timing time, setting a one-shot trigger, and setting the periodic trigger, etc. |
| arg | Control command parameters corresponding to cmd. For example, when cmd is the set timeout time, the timeout time parameter can be set by arg. |
| Return | —— |
| RT_EOK | Successful |
Commands supported by function parameters cmd:
#define RT_TIMER_CTRL_SET_TIME 0x0 /**< set timer control command */ #define RT_TIMER_CTRL_GET_TIME 0x1 /**< get timer control command */ #define RT_TIMER_CTRL_SET_ONESHOT 0x2 /**< change timer to one shot */ #define RT_TIMER_CTRL_SET_PERIODIC 0x3 /**< change timer to periodic */ #define RT_TIMER_CTRL_GET_STATE 0x4 /**< get timer run state active or deactive*/ #define RT_TIMER_CTRL_GET_REMAIN_TIME 0x5 /**< get the remaining hang time */
Example Source Code
In the below code, we have tried to explain all the possible scenarios in the RT-Thread Timer.
We have created 4 timers in the example.
Timer 1
Timer 1 is a Dynamic periodic timer that executes every 1 second.
Timer 2
Timer 2 is a Dynamic one-shot timer. The time of that timer is 2 seconds. So, it will call the callback after 2 seconds and it won’t call that callback again like the periodic timer.
Timer 3
Timer 3 is a Static periodic timer that executes every 3 seconds. Once the count reaches to 3, then we are getting the time of the timer 3 and stop that timer. So, the timer callback function won’t be called again as we stopped the timer.
Timer 4
Timer 4 is a Dynamic soft periodic timer that executes every 4 seconds.
You can also get the below entire project from GitHub.
/*
* Copyright (c) 2006-2023, RT-Thread Development Team
*
* SPDX-License-Identifier: Apache-2.0
*
* Change Logs:
* Date Author Notes
* 2023-02-14 RT-Thread first version
*/
#include <rtthread.h>
#define DBG_TAG "main"
#define DBG_LVL DBG_LOG
#include <rtdbg.h>
/* Timer Control Block */
static rt_timer_t timer1; //Dynamic Periodic timer
static rt_timer_t timer2; //Dynamic One shot timer
static struct rt_timer timer3; //Static Periodic timer
static rt_timer_t timer4; //Dynamic Periodic soft timer
int32_t count = 0;
/* Timer 1 Function */
static void timer_1_callback(void *parameter)
{
LOG_D("Timeout: Timer 1 Function!!!");
}
/* Timer 2 Function */
static void timer_2_callback(void *parameter)
{
LOG_D("Timeout: Timer 2 Function!!!");
}
/* Timer 3 Function */
static void timer_3_callback(void *parameter)
{
LOG_D("Timeout: Timer 3 Function!!!");
if( count++ >= 2 )
{
rt_tick_t timeNow;
//get time
rt_timer_control( &timer3, RT_TIMER_CTRL_GET_TIME, &timeNow );
//Stop timer
rt_timer_stop(&timer3);
LOG_D("Timer 3 Time is %dms, Stopping Timer 3", timeNow);
}
}
/* Timer 4 Function */
static void timer_4_callback(void *parameter)
{
LOG_D("Timeout: Timer 4 Function!!!");
}
int main(void)
{
/* Create Timer 1 Periodic Timer */
timer1 = rt_timer_create( "Timer1",
timer_1_callback,
RT_NULL,
1000,
RT_TIMER_FLAG_PERIODIC );
/* Start Timer 1*/
if (timer1 != RT_NULL)
{
rt_timer_start(timer1);
}
/* Create Timer 2 One Shot Timer */
timer2 = rt_timer_create( "Timer2",
timer_2_callback,
RT_NULL,
2000,
RT_TIMER_FLAG_ONE_SHOT );
/* Start Timer 2 */
if (timer2 != RT_NULL)
{
rt_timer_start(timer2);
}
/* Create Timer 3 Static Periodic Timer */
rt_timer_init( &timer3,
"Timer3",
timer_3_callback,
RT_NULL,
3000,
RT_TIMER_FLAG_PERIODIC );
/* Start Timer 3*/
rt_timer_start(&timer3);
/* Create Timer 4 Periodic Soft Timer */
timer4 = rt_timer_create( "Timer4",
timer_4_callback,
RT_NULL,
4000,
RT_TIMER_FLAG_PERIODIC | RT_TIMER_FLAG_SOFT_TIMER );
/* Start Timer 4 */
if (timer4 != RT_NULL)
{
rt_timer_start(timer4);
}
return RT_EOK;
}
Output
\ | / - RT - Thread Operating System / | \ 4.0.3 build Feb 14 2023 2006 - 2020 Copyright by rt-thread team msh >←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 2 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 3 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 4 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 3 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 4 Function!!!←[0m ←[0m[D/main] Timeout: Timer 3 Function!!!←[0m ←[0m[D/main] Timer 3 Time is 3000ms, Stopping Timer 3←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 4 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m ←[0m[D/main] Timeout: Timer 4 Function!!!←[0m ←[0m[D/main] Timeout: Timer 1 Function!!!←[0m
What’s Next
In our following tutorial, we will see the RT-Thread Synchronization (Semaphore).
You can also read the below tutorials.
Embedded Software | Firmware | Linux Devic Deriver | RTOS
Hi, I am a tech blogger and an Embedded Engineer. I am always eager to learn and explore tech-related concepts. And also, I wanted to share my knowledge with everyone in a more straightforward way with easy practical examples. I strongly believe that learning by doing is more powerful than just learning by reading. I love to do experiments. If you want to help or support me on my journey, consider sharing my articles, or Buy me a Coffee! Thank you for reading my blog! Happy learning!
