libs/rt-thread-official
libs
/
rt-thread-official
mirror of https://github.com/RT-Thread/rt-thread.git
4
0
Fork 0
Code Issues Releases Wiki Activity

docs fixes half done

This commit is contained in:
snikolaj 2022-08-19 09:09:21 +02:00 committed by Man, Jianting (Meco)
parent b31a3e5210
commit d246102f89
8 changed files with 92 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
documentation/at/at.md
View File

@ -2,41 +2,43 @@
## Introduction to AT Commands
AT Commands was originally a control protocol invented by Hayes, which invented MODEM, to control MODEM. Later, with the upgrade of network bandwidth, the dial-up MODEM with very low speed basically exited the general market, but the AT command was retained. At that time, the major mobile phone manufacturers jointly developed a set of AT commands for GSM to control the GSM module of the mobile phone. The AT command evolved on this basis and added the GSM 07.05 standard and the later GSM 07.07 standard to achieve a more robust standardization.
The AT command set was originally a control protocol invented by Dennis Hayes, initially used to control dial-up modems. Later, with the upgrade of network bandwidth, low-speed dial-up modems with very low speed essentially exited the general market, but the AT command set was retained. However, the AT command set lived on when major mobile phone manufacturers jointly developed a set of commands to control the GSM modules of mobile phones. The AT command set evolved on this basis and added the GSM 07.05 standard and the later GSM 07.07 standard to achieve more robust standardization.
In the subsequent GPRS control, 3G module, etc., all use AT commands to control, AT commands gradually become the actual standard in product development. Nowadays, AT commands are also widely used in embedded development. AT commands are the protocol interfaces of the main chip and communication module. The hardware interface is usually the serial port, so the main control device can complete various operations through simple commands and hardware design.
After seeing use in GPRS control, 3G modules and similar devices, AT commands gradually become the de facto standard in product development. Nowadays, AT commands are also widely used in embedded development. AT commands are the protocol interfaces of the main chip and communication module. The hardware interface is usually the serial port, so the main control device can complete various operations through simple commands and hardware design.
**The AT commands is a way of applying device connections and data communication between the AT Server and the AT Client.** The basic structure is shown below:
**AT commands are a way of facilitating device connections and data communication between an AT Server and an AT Client.** The basic structure is shown below:
![AT Command Set](figures/at_framework.jpg)
1. The AT command consists of three parts: prefix, body, and terminator. The prefix consists of the character AT; the body consists of commands, parameters, and possibly used data; the terminator typically is `<CR><LF>` (`"\r\n"`).
2. The implementation of the AT function requires the AT Server and the AT Client to work together.
2. The implementation of AT functionality requires the AT Server and the AT Client to work together.
3. The AT server is mainly used to receive commands sent by the AT client, determine the received commands and parameter formats, and deliver corresponding response data or actively send data.
3. An AT Server mainly receives commands sent by the AT Client, interprets the received commands and parameter formats, and delivers corresponding response data or actively sends data.
4. The AT client is mainly used to send commands, wait for the AT Server to respond, and parse the AT Server response data or the actively sent data to obtain related information.
4. An AT Client is mainly used to send commands, wait for the AT Server to respond, and parse the AT Server response data or the actively sent data to obtain related information.
5. A variety of data communication methods (UART, SPI, etc.) are supported between AT Server and AT Client. Currently, the most commonly used serial port UART communication method.
5. A variety of data communication methods (UART, SPI, etc.) are supported between an AT Server and an AT Client. Currently, the most commonly used communications protocol is UART.
6. The data that the AT Server sends to the AT Client is divided into two types: response data and URC data.
- Response Data: The AT Server response status and information received by the AT Client after sending the command.
- URC Data: The data that the AT Server actively sends to the AT client generally appears in some special cases, such as disconnected WIFI connection, TCP receiving data, etc. These situations often require the user to perform corresponding operations.
- URC Data: Data that the AT Server actively sends to the AT Client generally appears only in some special cases, such as when a WiFi connection is disconnected, while it's receiving TCP data, etc. These situations often require special user handling.
With the popularization of AT commands, more and more embedded products use AT commands. The AT commands are used as the protocol interfaces of the main chip and the communication module. The hardware interface is generally a serial port, so that the master device can performs a variety of operations using simple commands and hardware design.
Although the AT command has standardization to a certain degree, the AT commands supported by different chips are not completely unified, which directly increases the complexity to use. There is no uniform way to handle the sending and receiving of AT commands and the parsing of data. Moreover, when the AT device is used to connect to the network, the simple device connection and data transceiving functions can only be completed by commands, and it is difficult to adapt the upper layer network application interface, which is not conducive to the development of the product device.
Although the AT command set has standardization to a certain degree, the AT commands supported by different chips are not completely unified, which directly increases the complexity to use. There is no uniform way to handle the sending and receiving of AT commands and the parsing of data.
In order to facilitate the user to use AT commands to easily adapt to different AT modules, RT-Thread provides AT components for AT device connectivity and data communication. The implementation of the AT component consists of both client and server.
In order to facilitate the user to use AT commands which can be easily adapted to different AT modules, RT-Thread provides AT components for AT Device connectivity and data communication. The implementation of the AT components consists of both a client and a server.
## Introduction to AT Components
The AT component is based on the implementation of the `AT Server` and `AT Client` of the RT-Thread system. The component completes the AT command transmission, command format and parameter judgment, command response, response data reception, response data parsing, URC data processing, etc.. Command data interaction process.
The AT component is based on the implementation of the `AT Server` and `AT Client` of the RT-Thread system. The component completes the AT command transmission, command format and parameter parsing, command response, response data reception, response data parsing, URC data processing, etc..
Through the AT component, the device can use the serial port to connect to other devices to send and receive parsed data. It can be used as an AT Server to allow other devices or even the computer to connect to complete the response of sending data. It can also start the CLI mode in the local shell to enable the device to support AT Server and AT Client at the same time. Server and AT Client features, this mode is mostly used for device development and debugging.
**Command data interaction process.**
Through the AT component, the device can use the serial port to connect to other devices to send and receive parsed data. It can be used as an AT Server to allow other devices or even the computer to connect to complete the response of sending data. It can also start the CLI mode in the local shell to enable the device to support AT Server and AT Client at the same time. The usage of both modes simultaneously is mostly used for device development and debugging.
**AT component resource usage:**
@ -46,23 +48,23 @@ Through the AT component, the device can use the serial port to connect to other
- AT CLI: 1.5K ROM and almost no RAM is used.
Overall, the AT component resources are extremely small, making them ideal for use in embedded devices with limited resources. The AT component code is primarily located in `rt-thread/components/net/at/`. The main functions includes :
Overall, the AT component resources are extremely small, making them ideal for use in embedded devices with limited resources. The AT component code is primarily located in `rt-thread/components/net/at/`. What follows are the main function of both AT Servers and AT Clients.
**Main Functions of AT Server:**
- Basic commands: Implement a variety of common basic commands (ATE, ATZ, etc.);
- Command compatibility: The command supports ignoring case and improving command compatibility;
- Command detection: The command supports custom parameter expressions and implements self-detection of received command parameters.
- Command registration: Provides a simple way to add user-defined commands, similar to the way the `finsh/msh` command is added;
- Debug mode: Provides AT Server CLI command line interaction mode, mainly used for device debugging.
- Basic commands: A variety of common basic commands are implemented (ATE, ATZ, etc.);
- Command compatibility: Commands are case-insensitive, which increases command compatibility;
- Command detection: Commands support custom parameter expressions and implement self-detection of received command parameters;
- Command registration: User-defined commands can be easily added, in a way, similar to how the `finsh/msh` command is added;
- Debug mode: An AT Server CLI command line interaction mode is provided, which is mainly used for device debugging.
**Main Functions of AT Client:**
- URC data processing: The complete URC data processing method;
- Data analysis: Supports the analysis of custom response data, and facilitates the acquisition of relevant information in the response data;
- Debug mode: Provides AT Client CLI command line interaction mode, mainly used for device debugging.
- AT Socket: As an extension of AT Client function, it uses AT command to send and receive as the basis, implements the standard BSD Socket API, completes the data sending and receiving function, and enables users to complete device networking and data communication through AT commands.
- Multi-client support: The AT component currently supports multiple clients running simultaneously.
- Debug mode: Provides AT Client CLI command line interaction mode, mainly used for device debugging;
- AT Socket: An extension of AT Client function, it uses the AT command set to send and receive as the basis. This is implemented through the standard BSD Socket API, which completes the data sending and receiving function, and enables users to implement complete device networking and data communication through AT commands.
- Multi-client support: The AT component supports multiple clients running simultaneously.
## AT Server ##
@ -81,7 +83,7 @@ When we use the AT Server feature in the AT component, we need to define the fol
|AT_DEBUG|Enable AT component DEBUG mode to display more debug log information |
|AT_PRINT_RAW_CMD | Enable real-time display AT command communication data mode for easy debugging |
For different AT devices, there are several formats of the line terminator of the sending commands: `"\r\n"`、`"\r"`、`"\n"`, the user needs to select the corresponding line terminator according to the device type connected to the AT Server. And then determine the end of the send command line, defined as follows:
For different AT devices, there are several formats of the line terminator for the sending commands: `"\r\n"`、`"\r"`、`"\n"` - the user needs to select the corresponding line terminator in accordance to the device type connected to the AT Server and then determine the end of transmission command, defined as follows:
| **Macro Definition** | **Terminator** |
| ---- | ---- |
@ -110,18 +112,18 @@ After the add configuration is complete, you can use the command line to rebuild
### AT Server Initialization ###
After enabling the AT Server in Env, you need to initialize it at startup aims to enable the AT Server function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task. :
After enabling the AT Server in Env, you need to initialize it at startup to enable the AT Server function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task:
```c
int at_server_init(void);
```
The AT Server initialization function, which belongs to the application layer function, needs to be called before using the AT Server function or using the AT Server CLI function. `at_server_init()` function completes initialization of resources stored by AT commands ,such as data segment initialization, AT Server device initialization, and semaphore usage by the AT Server, and creates an at_server thread for parsing the receipt data in the AT Server.
The AT Server initialization function, which belongs to the application layer function, needs to be called before using the AT Server function or using the AT Server CLI function. `at_server_init()` function completes initialization of resources stored by AT commands, such as data segment initialization, AT Server device initialization, and semaphore usage by the AT Server. It also creates an at_server thread for parsing the received data in the AT Server.
After the AT Server is successfully initialized, the device can be used as an AT server to connect to the AT client's serial device for data communication, or use a serial port conversion tool to connect to the PC, so that the PC-side serial debugging assistant can communicate with the AT client as data communication.
After the AT Server is successfully initialized, the device can be used as an AT Server to connect to an AT Client's serial device for data communication, or use a serial-to-USB conversion tool to connect to a PC, so that the PC-side serial debugging assistant can communicate with the AT Client.
### Add custom AT commands ###
At present, the format of the AT command set used by AT devices of different manufacturers does not have a completely uniform standard, so the AT Server in the AT component only supports some basic general AT commands, such as ATE, AT+RST, etc. These commands can only be used to meet the basic operation of the device. If users want to use more functions, they need to implement custom AT Server commands for different AT devices.AT component provides AT command addition method similar to finsh/msh command addition method, which is convenient for users to implement the required commands.
At present, the format of the AT command set used by AT devices of different manufacturers does not have a completely uniform standard, so the AT Server in the AT component only supports some basic general AT commands, such as ATE, AT+RST, etc. These commands can only be used to meet the basic operation of the device. If users want to use more functions, they need to implement custom AT Server commands for different AT devices. The AT component provides an AT command addition method similar to the FinSH/msh command addition method, which is convenient for users to implement the required commands.
The basic commands currently supported by AT Server are as follows:
@ -139,7 +141,7 @@ AT commands can implement different functions depending on the format of the inc
- Setting Function: `AT+<x>=...`, used for user-defined parameter values;
- Execution Function: `AT+<x>`, used to perform related operations.
The four functions of each command do not need to be fully implemented. When you add the AT Server command, you can implement one or several of the above functions according to your needs. Unimplemented functions can be represented by `NULL` . And then through custom commands, the add function is added to the list of basic commands. The addition method is similar to the way the `finsh/msh` command is added. The function for adding commands is as follows:
The four functions of each command do not need to be fully implemented. When you add an AT Server command, you can implement one or several of the above functions according to your needs. Unimplemented functions can be represented by `NULL`. Then the custom function can be added to the list of basic commands. The addition method is similar to the way the `finsh/msh` commands are added. The function for adding commands is as follows:
```c
AT_CMD_EXPORT(_name_, _args_expr_, _test_, _query_, _setup_, _exec_);
@ -256,7 +258,7 @@ AT_CMD_EXPORT("AT+TEST", =<value1>,<value2>, NULL, NULL, at_test_setup, at_test_
int at_req_parse_args(const char *req_args, const char *req_expr, ...);
```
Parsing input command parameters Among the four function functions of an AT command, only the setting function has an input parameter, and the input parameter is to remove the rest of the AT command, for example, a command input is `"AT+TEST=1,2,3,4"`, Then set the input parameter of the function to the parameter string `"=1,2,3,4"` .
Among the four functions of an AT command, only the setting function has an input parameter, and the input parameter is to remove the rest of the AT command. For example, for a given command input `"AT+TEST=1,2,3,4"`, set the input parameter of the function to the parameter string `"=1,2,3,4"`.
The command parsing function is mainly used in the AT function setting function, which is used to parse the incoming string parameter and obtain corresponding multiple input parameters for performing the following operations. The standard `sscanf` parsing grammar used in parsing grammar here will also be described in detail later in the AT Client parameter parsing function.
@ -297,15 +299,15 @@ static at_result_t at_test_setup(const char *args)
AT_CMD_EXPORT("AT+TEST", =<value1>,<value2>, NULL, NULL, at_test_setup, NULL);
```
#### Portation-related interfaces
#### Porting-related interfaces
AT Server supports a variety of basic commands (ATE, ATZ, etc.) by default. The function implementation of some commands is related to hardware or platform and requires user-defined implementation. The AT component source code `src/at_server.c` file gives the weak function definition of the migration file. The user can create a new migration file in the project to implement the following function to complete the migration interface, or modify the weak function to complete the migration interface directly in the file.
The AT Server supports a variety of basic commands (ATE, ATZ, etc.) by default. The function implementation of some commands is related to hardware or platform and requires user-defined implementation. The AT component source code `src/at_server.c` file gives the weak function definition of the migration file. The user can create a new migration file in the project to implement the following function to complete the migration interface, or modify the weak function to complete the migration interface directly in the file.
1. Device restart function: `void at_port_reset(void);`. This function completes the device soft restart function and is used to implement the basic command AT+RST in AT Server.
2. The device restores the factory settings function: `void at_port_factory_reset(void);`. This function completes the device factory reset function and is used to implement the basic command ATZ in AT Server.
3. Add a command table in the link script (add only in gcc, no need to add in keil and iar)
3. Add a command table in the link script (add only in gcc, no need to add in Keil and IAR).
If you use the gcc toolchain in your project, you need to add the *section* corresponding to the AT server command table in the link script. Refer to the following link script:
@ -328,7 +330,7 @@ If you use the gcc toolchain in your project, you need to add the *section* corr
### AT Client Configuration
When we use the AT Client feature in the AT component, we need to define the following configuration in rtconfig.h:
When using the AT Client feature in the AT component, the following configuration in rtconfig.h needs to be defined:
```c
#define RT_USING_AT
@ -371,7 +373,7 @@ After the configuration is complete, you can use the command line to rebuild the
### AT Client Initialization ###
After configuring the AT Client, you need to initialize it at startup aims to enable the AT client function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task:
After configuring the AT Client, you need to initialize it at startup to enable the AT Client function. If the component has been initialized automatically, no additional initialization is required. Otherwise, you need to call the following function in the initialization task:
```c
int at_client_init(const char *dev_name, rt_size_t recv_bufsz);
@ -412,7 +414,7 @@ In the AT component, this structure is used to define a control block for AT com
- `line_counts` is used to record the total number of rows of this response data.
- `timeout` is the user-defined maximum response time for this response data.
`buf_size`、`line_num`、`timeout` parameters in the structure are restricted conditions, which are set when the structure is created, and other parameters are used to store data parameters for later data analysis.
`buf_size`, `line_num`, `timeout` parameters in the structure are restricted conditions, which are set when the structure is created, and other parameters are used to store data parameters for later data analysis.
Introduction to related API interfaces:
@ -531,7 +533,7 @@ MSH_CMD_EXPORT(at_Client_send, AT Client send commands to AT Server and get resp
#endif
```
The implementation principle of sending and receiving data is relatively simple. It mainly reads and writes the serial port device bound by the AT client, and sets the relevant number of rows and timeout to limit the response data. It is worth noting that the `res` response needs to be created first. The structure passed `in_exec_cmd` function for data reception. When the `at_exec_cmd` function's parameter `resp` is NULL, it means that the data sent this time **does not consider processing the response data and directly returns the result**.
The implementation principle of sending and receiving data is relatively simple. It mainly reads and writes the serial port device bound by the AT client, and sets the relevant number of rows and timeout to limit the response data. It is worth noting that the `res` response needs to be created first. The structure passed `in_exec_cmd` function is for data reception. When the `at_exec_cmd` function's parameter `resp` is NULL, it means that the data sent this time **does not consider processing the response data and directly returns the result**.
### AT Client Data Parsing Method ###
@ -674,7 +676,7 @@ printf("IP=%s, MAC=%s\n", ip, mac);
at_delete_resp(resp);
```
The key to parsing data is to correctly define the expression. Because the response data of the different device manufacturers is not unique to the response data of the AT device, only the form of the custom parsing expression can be obtained to obtain the required information. The design of the `at_resp_parse_line_args` parsing parameter function is based on the `sscanf` data parsing method. Before using, the developer needs to understand the basic parsing syntax and then design the appropriate parsing syntax in combination with the response data. If the developer does not need to parse the specific parameters, you can use the `at_resp_get_line` function to get the specific data of a row.
The key to parsing data is to correctly define the expression. Because the response data of the different device manufacturers is not unique to the response data of the AT device, only the form of the custom parsing expression can be obtained to obtain the required information. The design of the `at_resp_parse_line_args` parsing parameter function is based on the `sscanf` data parsing method. Before using it, the developer needs to understand the basic parsing syntax and then design the appropriate parsing syntax in combination with the response data. If the developer does not need to parse the specific parameters, you can use the `at_resp_get_line` function to get the specific data of a row.
### AT Client URC Data Processing ###
@ -821,7 +823,7 @@ The advantages and disadvantages of the two different mode functions and in diff
![at client modes comparison](figures/at_multiple_client.jpg)
The single client mode function definition is mainly different from the single connection mode function. The definition of the incoming client object is different. The single client mode function uses the first initialized AT client object by default, and the multi-client mode function can Pass in the user-defined custom client object. The function to get the client object is as follows:
The single client mode function definition is mainly different from the single connection mode function. The definition of the incoming client object is different. The single client mode function uses the first initialized AT client object by default, and the multi-client mode function can pass in the user-defined custom client object. The function to get the client object is as follows:
```c
at_client_t at_client_get(const char *dev_name);

22
documentation/device/adc/adc.md
View File

@ -2,12 +2,11 @@
## An Introduction to ADC
ADC is a hardware device that converts continuously changing analog signals to discrete digital signals such as temperature, pressure, sound, or images signals, etc. Digital signals are easier to be stored, processed, and transmitted.
This can be achieved by using an analog-to-digital converter device and it is widely used in various platforms. According to history, ADC was first used to convert wireless signals to digital signals, for example, television signals, or signals from long-short broadcast stations.
An ADC (analog-to-digital converter) is a hardware device that converts continuously changing analog signals to discrete digital signals. Usually, these analog signals include temperature, pressure, sound, video and many other types of signals. Converting them is important, as digital signals are easier to store, process, and transmit. This conversion can be achieved by using an ADC device which is commonly integrated in various platforms. Historically, ADCs were first used to convert received wireless signals to digital signals, for example, television signals, or signals from long-short broadcast stations.
### Conversion Process
As shown in the figure below, the analog-to-digital conversion generally involves steps of sampling, holding, quantifying, and encoding. In actual circuits, some processes are combined, such as sampling and holding, and quantization and encoding are implemented simultaneously in the conversion process.
As shown in the figure below, the analog-to-digital conversion generally involves steps of sampling, holding, quantifying, and encoding. In actual circuits, some processes are combined, such as sampling and holding, while quantization and encoding are implemented simultaneously in the conversion process.
![ADC Conversion Process](figures/adc-p.png)
@ -17,15 +16,15 @@ The process of converting a numerically continuous analog quantity into a digita
### Resolution
Resolution is represented as binary (or decimal) numbers. Generally, it comes with 8 bits, 12 bits, 16 bits, etc. Higher bits means higher resolution, thus, more accuracy in conversion of analog to digital signals.
Resolution is represented as binary (or decimal) numbers. Generally, it comes in 8 bits, 10 bits, 12 bits, 16 bits, etc. A larger resolution, in bits, means more accuracy in the conversion of analog to digital signals.
### Precision
Precision means maximum error values between analog signals and real ADC device numerical points’ values.The deviation is measured from the output values to the liner maximum values. However, precision and resolution are used for different purposes and different concepts.
Precision is the maximum error value between analog signals and real ADC device numerical points’ values.An ADC with a high resolution might have a low precision, meaning that factors like noise can affect the numerical ADC reading more than small changes in the input signal.
### Conversion Rate
The conversion rate is the reciprocal of time taken for an ADC device to complete conversion from analog to digital signals. For example, an ADC device with a conversion rate of 1MHz means ADC conversion time is 1 microsecond.
The conversion rate is the reciprocal of time taken for an ADC device to complete conversion from an analog to a digital signal. For example, an ADC device with a conversion rate of 1MHz means that the ADC conversion time is 1 microsecond.
## Access ADC Device
@ -40,7 +39,7 @@ The application accesses the ADC hardware through the ADC device management inte
### Find ADC Devices
The application gets the device handler based on the ADC device name to operate the ADC device. Following is the interface function to find the devices,
The application gets the device handler based on the ADC device name to operate the ADC device. Following is the interface function to find the devices:
```c
rt_device_t rt_device_find(const char* name);
@ -53,7 +52,8 @@ rt_device_t rt_device_find(const char* name);
| Device handle | Finding the corresponding device will return to the corresponding device handle |
| RT_NULL | No device found
|
In a nutshell, the names of the ADC devices are registered as adc0, adc1, and so on. Following is the example how to use it
In a nutshell, the names of the ADC devices are registered as adc0, adc1, and so on. What follows is an example on how to use it
```c
#define ADC_DEV_NAME "adc1" /* ADC device name */
@ -64,7 +64,7 @@ adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
### Enable ADC Channel
It is required to enable ADC device with the following interface function before reading and operating the ADC device,
It is required to enable the ADC device with the following interface function before reading and operating the ADC device.
```c
rt_err_t rt_adc_enable(rt_adc_device_t dev, rt_uint32_t channel);
@ -129,9 +129,9 @@ rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100);
The calculation formula of the actual voltage value is: `sampling value * reference voltage/(1 << resolution digit)`. In the above example, variable *vol* was enlarged 100 times, so finally the integer part of voltage is obtained through *vol / 100*, and the decimal part of voltage is obtained through *vol % 100*.
### Close the ADC Channel
### Disabling the ADC Channel
Use the following function can close the ADC channel :
An ADC channel can be disabled through the following function:
```c
rt_err_t rt_adc_disable(rt_adc_device_t dev, rt_uint32_t channel);

20
documentation/device/hwtimer/hwtimer.md
View File

@ -5,13 +5,11 @@
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:** Counts the external pulse.
**Timer mode**: Counts the internal pulse. Timers are often used as timing clocks for timing detection, timing response, and timing control.
**Counter **: Counter can count up or down. The maximum count value of the 16-bit counter is 65535, and the maximum value of the 32-bit counter is 4294967295.
**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 **：As for the number of counts within the counter time unit under the timer mode, since the system clock frequency is fixed, the timer time can be calculated according to the counter count value. `Timing time = count value / count frequency`. For example, if the counting frequency is 1 MHz, the counter counts once is 1 / 1000000 second. That is, every 1 microsecond counter is incremented by one (or subtract one), at this time, the maximum timing capability of the 16-bit counter is 65535 microseconds, which is 65.535 milliseconds.
**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.
## Access Hardware Timer Device
@ -80,7 +78,7 @@ rt_device_open(hw_dev, RT_DEVICE_OFLAG_RDWR);
### Set the Timeout Callback Function
Set the timer timeout callback function by the following function, this callback function will be called when the timer expires:
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:
```c
rt_err_t rt_device_set_rx_indicate(rt_device_t dev, rt_err_t (*rx_ind)(rt_device_t dev, rt_size_t size))
@ -121,7 +119,7 @@ static int hwtimer_sample(int argc, char *argv[])
### Control the Timer Device
By commanding the control word, the application can configure the hardware timer device by the following function:
By sending control words, the application can configure the hardware timer device with the following function:
```c
rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg);
@ -146,11 +144,11 @@ The command control words available for the hardware timer device are as follows
| HWTIMER_CTRL_INFO_GET | get timer feature information |
| HWTIMER_CTRL_MODE_SET | set timer mode |
Get the timer parameter arg,which is a pointer to the structure struct rt_hwtimer_info, to save the obtained information.
Get the timer parameter argument, which is a pointer to the structure struct rt_hwtimer_info, to save the obtained information.
>Setting frequency is valid only when the timer hardware and driver support sets the counting frequency. Generally, the default frequency of the driving setting can be used.
>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.
When setting the timer mode, the parameter arg can take the following values：
When setting the timer mode, the parameter argument can take the following values：
```c
HWTIMER_MODE_ONESHOT /* Single timing */
@ -283,7 +281,7 @@ rt_device_read(hw_dev, 0, &timeout_s, sizeof(timeout_s));
### Close the Timer Device
The timer device can be closed by the following function:
The timer device can be closed with the following function:
```c
rt_err_t rt_device_close(rt_device_t dev);
@ -297,7 +295,7 @@ rt_err_t rt_device_close(rt_device_t dev);
| -RT_ERROR | the device has been completely shut down and cannot be closed repeatedly |
| other error code | fail to close the device |
To close the device interface and open the device interface should be used in pairs. When open a device, close the device after use , so that the device can be completely shut down, otherwise the device will remain a opening status.
When a timer device has been used and is not necessary anymore, it should be closed, otherwise the device will remain in an open status.
An example of use is shown below：

6
documentation/device/i2c/i2c.md
View File

@ -2,9 +2,9 @@
## Introduction of I2C
The I2C (Inter Integrated Circuit) bus is a half-duplex, bidirectional two-wire synchronous serial bus developed by PHILIPS. The I2C bus has only two signal lines, one is the bidirectional data line SDA (serial data), and the other is the bidirectional clock line SCL (serial clock). The SPI bus has two lines for receiving data and transmitting data between the master and slave devices, while the I2C bus uses only one line for data transmission and reception.
The I2C (Inter Integrated Circuit) bus is a half-duplex, bidirectional two-wire synchronous serial bus developed by Philips. The I2C bus has only two signal lines, one is the bidirectional data line SDA (serial data), and the other is the bidirectional clock line SCL (serial clock). Compared to the SPI bus, which has two lines for receiving data and transmitting data between the master and slave devices, the I2C bus uses only one line for data transmission and reception.
Like SPI, I2C works in a master-slave manner. Unlike SPI-master-multi-slave architecture, it allows multiple master devices to exist at the same time. Each device connected to the bus has a unique address, and the master device initiates data transfer, and generates a clock signal. The slave device is addressed by the master device, and only one master device is allowed at a time. As shown below:
Like SPI, I2C works in a master-slave manner. Unlike SPI-master-multi-slave architecture, it allows multiple master devices to exist at the same time. Each device connected to the bus has a unique address, and the master device initiates data transfer, and generates a clock signal. The slave device is addressed by the master device, and only one master device is allowed to communicate at a time. As shown below:
![I2C Bus master-slave device connection mode](figures/i2c1.png)
@ -12,7 +12,7 @@ The main data transmission format of the I2C bus is shown in the following figur
![I2C Bus Data Transmission Format](figures/i2c2.png)
When the bus is idle, both SDA and SCL are in a high state. When the host wants to communicate with a slave, it will send a start condition first, then send the slave address and read and write control bits, and then transfer the data (host send or receive data). The host will send a stop condition when the data transfer ends. Each byte transmitted is 8 bits, with the high bit first and the low bit last. The different terms in the data transmission process are as follows:
When the bus is idle, both SDA and SCL are in a high state. When the host wants to communicate with a slave, it will send a start condition first, then send the slave address and read and write control bits, and then transfer the data (the host can send or receive data). The host will send a stop condition when the data transfer ends. Each byte transmitted is 8 bits, with the high bit first and the low bit last. The different terms in the data transmission process are as follows:
* **Starting Condition：** When SCL is high, the host pulls SDA low, indicating that data transfer is about to begin.

8
documentation/device/pin/pin.md
View File

@ -2,9 +2,9 @@
## Introduction of Pin
The pins on the chip are generally divided into four categories: power supply, clock, control, and I/O. The I/O port is further divided into General Purpose Input Output (GPIO) and function multiplex I/O (such as SPI/I2C/UART, etc.) in the usage mode.
The pins on the chip are generally divided into four categories: power supply, clock, control, and I/O. The I/O pins are further divided into General Purpose Input Output (GPIO) and function-multiplexed I/O (such as SPI/I2C/UART, etc.) pins, referring to their usage mode.
Most MCU pins have more than one function. The internal structure of different pins is different and the functions are different. The actual function of the pin can be switched through different configurations. The main features of the General Purpose Input Output (GPIO) port are as follows:
Most MCU pins have more than one function. Their internal structure is different and their supported functionality are different. The actual function of the pin can be switched through different configurations. The main features of the General Purpose Input Output (GPIO) port are as follows:
* Programmable Interrupt: The interrupt trigger mode is configurable. Generally, there are five interrupt trigger modes as shown in the following figure:
@ -31,7 +31,7 @@ The application accesses the GPIO through the PIN device management interface pr
### Obtain Pin Number
The pin numbers provided by RT-Thread need to be distinguished from the chip pin numbers. They are not the same concept. The pin numbers are defined by the PIN device driver and are related to the specific chip. There are two ways to obtain the pin number: use the macro definition or view the PIN driver file.
The pin numbers provided by RT-Thread need to be distinguished from the chip pin numbers, which not the same. The pin numbers are defined by the PIN device driver and are related to the specific chip used. There are two ways to obtain the pin number: use the macro definition or view the PIN driver file.
#### Use Macro Definition
@ -157,7 +157,7 @@ status = rt_pin_read(BEEP_PIN_NUM);
### Bind Pin Interrupt Callback Function
To use the interrupt function of the pin, you can use the following function to configure a pin to some interrupt trigger mode and bind an interrupt callback function to the corresponding pin. When the pin interrupt occurs, the callback function will be executed. :
To use the interrupt functionality of a pin, you can use the following function to configure the pin to some interrupt trigger mode and bind an interrupt callback function to the corresponding pin. When the pin interrupt occurs, the callback function will be executed.:
```c
rt_err_t rt_pin_attach_irq(rt_int32_t pin, rt_uint32_t mode,

2
documentation/device/pwm/pwm.md
View File

@ -8,7 +8,7 @@ PWM (Pulse Width Modulation) is a method of digitally encoding the level of an a
Above is a simple schematic diagram of PWM. Assuming that the timer works in a up-counter mode. When the count value is less than the threshold, it outputs a level state, such as a high level. When the count value is greater than the threshold, it outputs the opposite, such as a low level. When the count value reaches the maximum value, the counter recounts from 0 and returns to the original level state. The ratio of the high-level duration (pulse width) to the cycle time is the duty cycle, ranging from 0 to 100%. The high level of the above picture is just half of the cycle time, so the duty cycle is 50%.
One of the common PWM control scenarios is to adjust the brightness of the light or screen. The brightness can be adjusted according to the duty cycle. The PWM adjusts the brightness not continuously, but constantly lights up and turns off the screen. When the light is turned on and off fast enough, the naked eye will always think that it is always bright. In the process of on and off, the longer the light is off, the lower the brightness of the screen to the naked eye. The longer the light is on, the less time is spent and the screen will be brighter.
One of the common PWM control scenarios is to adjust the brightness of a light or screen. The brightness can be adjusted through changing the duty cycle. The PWM does not adjust the light continuously, rather it constantly turns the screen on and off. When the light is turned on and off fast enough, the naked eye will always think that it is always bright. In the process of switching it on and off, the longer the light is off, the lower the brightness of the screen to the naked eye. Conversely, the longer the light is on, the brighter the screen will appear.
![PWM Brightness Adjustment](figures/pwm-l.png)

4
documentation/device/rtc/rtc.md
View File

@ -4,7 +4,7 @@
The RTC (Real-Time Clock) provides accurate real-time clock time, which can be used to generate information such as year, month, day, hour, minute, and second. At present, most real-time clock chips use a higher precision crystal oscillator as a clock source. In order to work when the main power supply is powered down, some clock chips will be powered by a battery to keep the time information valid.
The RT-Thread RTC device provides the basic services for the operating system's time system. In the face of more and more IoT scenarios, RTC has become the standard configuration of the product, and even in the secure transmission process such as SSL, RTC has become an indispensable part.
The RT-Thread RTC device provides the basic services for the operating system's time system. RTCs find many uses in IoT scenarios, and even in secure transmission processes such as SSL, RTC has become an indispensable part.
## Access RTC Devices
@ -119,7 +119,7 @@ RT-Thread online packages →
[*] Enable NTP(Network Time Protocol) client
```
After the NTP is turned on, the RTC's automatic synchronization function will be automatically turned on, and the synchronization period and the delay time of the first synchronization can also be set:
After NTP is turned on, the RTC's automatic synchronization function will be automatically turned on, and the synchronization period and the delay time of the first synchronization can also be set:
```c
RT-Thread Components →

24
documentation/device/sensor/sensor.md
View File

@ -2,17 +2,17 @@
## Introduction
Sensor is an important part of the Internet of Things, and "Sensor to the Internet of Things" is equivalent to "eyes to humans". Without eyes, human beings can not see the vast world of flowers. The same is true for the Internet of Things.
Sensors are an important part of the Internet of Things, and sensors in an IoT system are equivalent to the eyes of humans. Without eyes, human beings can not see and interpret the world around them. The same is true for the Internet of Things.
Nowadays, with the development of Internet of Things, a large number of Sensors have been developed for developers to choose, such as Accelerometer, Magnetometer, Gyroscope, Barometer/pressure, Humidometer and so on. These sensors, manufactured by the world's leading semiconductor manufacturers, have increased market selectivity and made application development more difficult. Because different sensor manufacturers and sensors need their own unique drivers to run, so when developing applications, they need to adapt to different sensors, which naturally increases the difficulty of development. In order to reduce the difficulty of application development and increase the reusability of sensor driver, we designed a Sensor device.
Nowadays, with the development of IoT, a large number of sensors are available for developers to choose, such as Accelerometers, Magnetometers, Gyroscopes, Barometers/pressure senosrs, Hygrometers/humidity meters and so on. However, these sensors, manufactured by the world's leading semiconductor manufacturers, have increased market selectivity and made application development more difficult. Because different sensor manufacturers and sensors need their own unique drivers to run, developers need to write a device driver for each sensor, which can be difficult and time-consuming. In order to reduce the difficulty of application development and increase the reusability of sensor driver, we designed a Sensor device.
The function of Sensor device is to provide a unified operation interface for the upper layer and improve the reusability of the upper code.
The function of the Sensor device is to provide a unified operation interface for the upper layer and improve the reusability of the upper code.
### Characteristics of Sensor Device
### Characteristics of the Sensor Device
- **Interface**: Standard device interface (open/close/read/control)
- **Work mode**: support polling, interruption, FIFO three modes
- **Power mode**: support four modes: power failure, common, low power consumption and high power consumption
- **Interface:** Standard device interface (open/close/read/control)
- **Work mode:** Supports polling, interrupts, three FIFO (First In, First Out) modes
- **Power mode:** support four modes: power failure, common, low power consumption and high power consumption
## Access Sensor Device
@ -53,7 +53,7 @@ sensor_dev = rt_device_find(SENSOR_DEVICE_NAME);
### Open Sensor Device
Through the device handle, the application can open and close the device. When the device is opened, it will check whether the device has been initialized or not. If it is not initialized, it will call the initialization interface initialization device by default. Open the device through the following functions:
Through the device handle, the application can open and close the device. When the device is opened, it will check whether the device has been initialized or not. If it is not initialized, it will call the initialization interface by default. Open the device through the following functions:
```c
rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflags);
@ -79,7 +79,7 @@ The oflags parameter supports the following parameters：
There are three modes of receiving and sending sensor data: interrupt mode, polling mode and FIFO mode. When using these three modes, **only one of them can be chosen**. If the sensor's open parameter oflags does not specify the use of interrupt mode or FIFO mode, polling mode is used by default.
FIFO ,means first Input first output. FIFO transmission mode needs sensor hardware support, data is stored in hardware FIFO, read multiple data at a time, which saves CPU resources to do other operations. Very useful in low power mode
FIFO transmission mode needs sensor hardware support, data is stored in hardware FIFO, which reads and stores multiple data simultaneously, which allows the CPU to do other operations while gathering data. This feature is very useful in low power mode.
If the sensor uses FIFO receiving mode, the value of oflags is RT_DEVICE_FLAG_FIFO_RX.
@ -109,7 +109,7 @@ int main(void)
### Control Sensor Device
By command control word, the application program can configure the sensor device through the following functions:
By command control words, the application program can configure the sensor device through the following functions:
```c
rt_err_t rt_device_control(rt_device_t dev, rt_uint8_t cmd, void* arg);
@ -167,7 +167,7 @@ rt_device_control(dev, RT_SEN_CTRL_SET_RANGE, (void *)1000);
#### Setting the Output Rate of Sensor Data
Set the output rate to 100HZ and call the following interface.
Set the output rate to 100Hz and call the following interface.
```c
rt_device_control(dev, RT_SEN_CTRL_SET_ODR, (void *)100);
@ -222,7 +222,7 @@ rt_err_t rt_device_set_rx_indicate(rt_device_t dev, rt_err_t (*rx_ind)(rt_device
| **Return** | —— |
| RT_EOK | Successful setup |
The callback function of the function is provided by the user. If the sensor is opened in interrupt mode, when the sensor receives data and interrupts, the callback function will be called, and the data size of the buffer will be placed in the `size` parameter, and the sensor device handle will be placed in the `dev` parameter for users to obtain.
The callback function of the function is provided by the user. If the sensor is opened in interrupt mode, as the sensor receives data the callback function will be called. The data size of the buffer will be placed in the `size` parameter, and the sensor device handle will be placed in the `dev` parameter for users to obtain.
Generally, receiving callback function can send a semaphore or event to inform sensor data processing thread that data arrives. The use example is as follows: