Hardware timers generally have two modes of operation, timer mode and counter mode. No matter which mode is operated, it works by counting the pulse signal counted by the internal counter module. Here are some important concepts of timers.
**Counter mode**: The counter can count up or down. The maximum count value of a 16-bit counter is 65535, and the maximum value of a 32-bit counter is 4 294 967 295.
**Counting frequency**：Since the input frequency is usually fixed, the time it takes for the counter to reach its desired count number can be calculated from just the given frequency - `time = count value / count frequency`. For example, if the counting frequency is 1 MHz, the counter counts once every 1 / 1000000 seconds. That is, every 1 microsecond, the counter is incremented by one (or subtracted by one), at this time, the maximum timing capability of the 16-bit counter is 65535 microseconds, or 65.535 milliseconds.
The application accesses the hardware timer device through the I/O device management interface provided by RT-Thread. The related interfaces are as follows:
| rt_device_find() | to look up the timer device |
| rt_device_open() | to open the timer device in read-write mode |
| rt_device_set_rx_indicate() | to set the timeout callback function |
| rt_device_control() | to control the timer device, you can set the timing mode (single time /cycle),counting frequency, or stop the timer |
| rt_device_write() | to set the timeout value of the timer. The timer then starts |
| rt_device_read() | to get the current value of the timer |
| rt_device_close() | to turn off the timer device. |
### Find Timer Device
The application obtains the device handle based on the hardware timer device name, and thus can operate the hardware timer device. The device function is as follows:
```c
rt_device_t rt_device_find(const char* name);
```
| Parameter | **Description** |
| -------- | ---------------------------------- |
| name | hardware timer device name |
| **return** | —— |
| timer device handle | will return to the corresponding device handle if the corresponding device is found |
| RT_NULL | No device found |
In general, the hardware timer device name registered to the system is timer0, timer1, etc. The usage examples are as follows:
```c
#define HWTIMER_DEV_NAME "timer0" /* timer name */
rt_device_t hw_dev; /* timer device handle */
/* find timer device */
hw_dev = rt_device_find(HWTIMER_DEV_NAME);
```
### Open Timer Device
With the device handle, the application can open the device. When the device is open, it will detect whether the device has been initialized. If it is not initialized, it will call the initialization interface to initialize the device by default. Open the device with the following function:
Set the timer timeout callback function with the following function - this is the function that will be called when the timer reaches its set count value:
>Setting frequency is valid only when the timer hardware and included driver set the counting frequency. Generally, the default frequency of the driving setting can be used.
#define HWTIMER_DEV_NAME "timer0" /* timer name */
rt_device_t hw_dev; /* timer device handle */
/* find timer device */
hw_dev = rt_device_find(HWTIMER_DEV_NAME);
... ...
rt_device_close(hw_dev);
```
>Timing errors may occur. Assume that the counter has a maximum value of 0xFFFF, a counting frequency of 1Mhz, and a timing time of 1 second and 1 microsecond. Since the timer can only count up to 65535us at a time, the timing requirement for 1000001us can be completed 20 times at 50000us, and the calculation error will be 1us.
## Hardware Timer Device Usage Example
The specific use of the hardware timer device can refer to the following sample code. The main steps of the sample code are as follows:
1. First find the device handle based on the timer device name "timer0".
2. Open the device "timer0" in read-write mode.
3. Set the timer timeout callback function.
4. Set the timer mode to periodic timer and set the timeout period to 5 seconds. At this time, the timer starts.
5. Read the timer after 3500ms delay, the read value will be displayed in seconds and microseconds.
```c
/*
* Program listing: This is an hwtimer device usage routine
* The routine exports the hwtimer_sample command to the control terminal
* Command call format: hwtimer_sample
* Program function: The hardware timer timeout callback function periodically prints the current tick value, and the difference between the two tick values is converted to the time equivalent to the timing time value.
*/
#include <rtthread.h>
#include <rtdevice.h>
#define HWTIMER_DEV_NAME "timer0" /* timer name */
