doxygen: convert 5.device

Signed-off-by: Chen Wang <[email protected]>

Author: unicornx

documentation/5.device/INDEX.md

@@ -1 +1,14 @@
 @page device Device
+
+- @subpage device_framework
+- @subpage device_pin
+- @subpage device_uart
+- @subpage device_adc
+- @subpage device_i2c
+- @subpage device_spi
+- @subpage device_pwm
+- @subpage device_rtc
+- @subpage device_hwtimer
+- @subpage device_watchdog
+- @subpage device_wlan
+- @subpage device_sensor

documentation/INDEX.md

@@ -20,20 +20,20 @@
 - @ref env
 - @ref scons
 
-**Device**
-
-- [I/O Device Framework](device/device.md)
-- [PIN Device](device/pin/pin.md)
-- [UART Device](device/uart/uart.md)
-- [ADC Device](device/adc/adc.md)
-- [I2C Bus Device](device/i2c/i2c.md)
-- [SPI Device](device/spi/spi.md)
-- [PWM Device](device/pwm/pwm.md)
-- [RTC Device](device/rtc/rtc.md)
-- [HWTIMER Device](device/hwtimer/hwtimer.md)
-- [WATCHDOG Device](device/watchdog/watchdog.md)
-- [WLAN Device](device/wlan/wlan.md)
-- [Sensor Device](device/sensor/sensor.md)
+@subpage device
+
+- @ref device_framework
+- @ref device_pin
+- @ref device_uart
+- @ref device_adc
+- @ref device_i2c
+- @ref device_spi
+- @ref device_pwm
+- @ref device_rtc
+- @ref device_hwtimer
+- @ref device_watchdog
+- @ref device_wlan
+- @ref device_sensor
 
 **Components**
 

documentation/device/adc/adc.md

@@ -1,10 +1,10 @@
-# ADC Device
+@page device_adc ADC Device
 
-## An Introduction to ADC
+# An Introduction to ADC
 
 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
+## 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.
 
@@ -14,19 +14,19 @@ Sampling is the conversion of analog signals that changes continuously over time
 
 The process of converting a numerically continuous analog quantity into a digital quantity is called quantization. Digital signals are discrete numerically. The output voltage of the sample-and-hold circuit also needs to be naturalized to a corresponding discrete level in a similar way, and any digital quantity can only be an integer multiple of a certain minimum quantity unit. The quantized value also requires the encoding process, which is the digital output of the A/D converter.
 
-### Resolution
+## Resolution
 
 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
 
 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
+## Conversion Rate
 
 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
+# Access ADC Device
 
 The application accesses the ADC hardware through the ADC device management interface provided by RT-Thread. The relevant interfaces are as follows:
 
@@ -37,7 +37,7 @@ The application accesses the ADC hardware through the ADC device management inte
 | rt_adc_read()   | Read ADC device data |
 | rt_adc_disable()  | Close the ADC device |
 
-### Find ADC Devices
+## 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: 
 
@@ -62,7 +62,7 @@ rt_adc_device_t adc_dev;            /* ADC device handle */
 adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
 ```
 
-### Enable ADC Channel
+## Enable ADC Channel
 
 It is required to enable the ADC device with the following interface function before reading and operating the ADC device.
 
@@ -91,7 +91,7 @@ adc_dev = (rt_adc_device_t)rt_device_find(ADC_DEV_NAME);
 rt_adc_enable(adc_dev, ADC_DEV_CHANNEL);
 ```
 
-### Read ADC Channel Sample Values
+## Read ADC Channel Sample Values
 
 Reading the ADC channel sample values can be done by the following function:
 
@@ -129,7 +129,7 @@ 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*.
 
-### Disabling the ADC Channel
+## Disabling the ADC Channel
 
 An ADC channel can be disabled through the following function:
 
@@ -166,7 +166,7 @@ rt_kprintf("the voltage is :%d.%02d \n", vol / 100, vol % 100);
 rt_adc_disable(adc_dev, ADC_DEV_CHANNEL);
 ```
 
-### FinSH Command
+## FinSH Command
 
 To find out the registered device, you can use the command adc probe followed by the registered ADC device name as following,
 
@@ -198,7 +198,7 @@ adc1 channel 5 disable success
 msh >
 ```
 
-## ADC Device Usage Example
+# ADC Device Usage Example
 
 The specific usage of the ADC device can refer to the following sample code. The main steps of the sample code are as follows:
 

documentation/device/device.md

@@ -1,12 +1,12 @@
-# I/O Device Framework
+@page device_framework I/O Device Framework
 
 Most embedded systems include some I/O (Input/Output) devices, data displays on instruments, serial communication on industrial devices, Flash or SD cards for saving data on data acquisition devices,as well as Ethernet interfaces for network devices, are examples of I/O devices that are commonly seen in embedded systems.
 
 This chapter describes how RT-Thread manages different I/O devices.
 
-## I/O Device Introduction
+# I/O Device Introduction
 
-### I/O Device Framework
+## I/O Device Framework
 
 RT-Thread provides a set of I/O device framework, as shown in the following figure. It is located between the hardware and the application. It is divided into three layers. From top to bottom, they are I/O device management layer, device driver framework layer, and device driver layer.
 
@@ -35,7 +35,7 @@ Usage of Watchdog device:
 
 ![Watchdog Device Use Sequence Diagram](figures/wtd-uml.png)
 
-### I/O Device Model
+## I/O Device Model
 
 The device model of RT-Thread is based on the kernel object model, which is considered a kind of objects and is included in the scope of the object manager. Each device object is derived from the base object. Each concrete device can inherit the properties of its parent class object and derive its own properties. The following figure is a schematic diagram of the inheritance and derivation relationship of device object.
 
@@ -66,7 +66,7 @@ typedef struct rt_device *rt_device_t;
 
 ```
 
-### I/O Device Type
+## I/O Device Type
 
 RT-Thread supports multiple I/O device types, the main device types are as follows:
 
@@ -95,7 +95,7 @@ A block device transfers one data block at a time, for example 512 bytes data at
 
 When the system serves a write operation with a large amount of data, the device driver must first divide the data into multiple packets, each with the data size specified by the device. In the actual process, the last part of the data size may be smaller than the normal device block size. Each block in the above figure is written to the device using a separate write request, and the first three are directly written. However, the last data block size is smaller than the device block size, and the device driver must process the last data block differently than the first 3 blocks. Normally, the device driver needs to first perform a read operation of the corresponding device block, then overwrite the write data onto the read data, and then write the "composited" data block back to the device as a whole block. . For example, for block 4 in the above figure, the driver needs to read out the device block corresponding to block 4, and then overwrite the data to be written to the data read from the device block, and merge them into a new block. Finally write back to the block device.
 
-## Create and Register I/O Device
+# Create and Register I/O Device
 
 The driver layer is responsible for creating device instances and registering them in the I/O Device Manager. You can create device instances in a statically declared manner or dynamically create them with the following interfaces:
 
@@ -245,13 +245,13 @@ rt_err_t rt_hw_watchdog_register(struct rt_watchdog_device *wtd,
 
 ```
 
-## Access I/O Devices
+# Access I/O Devices
 
 The application accesses the hardware device through the I/O device management interface, which is accessible to the application when the device driver is implemented. The mapping relationship between the I/O device management interface and the operations on the I/O device is as follows:
 
 ![Mapping between the I/O Device Management Interface and the Operations on the I/O Device](figures/io-fun-call.png)
 
-### Find Device
+## Find Device
 
 The application obtains the device handle based on the device name, which in turn allows the device to operate. To find device, use function below:
 
@@ -266,7 +266,7 @@ rt_device_t rt_device_find(const char* name);
 | device handle | finding the corresponding device will return the corresponding device handle |
 | RT_NULL  | no corresponding device object found |
 
-### Initialize Device
+## Initialize Device
 
 Once the device handle is obtained, the application can initialize the device using the following functions:
 
@@ -283,7 +283,7 @@ rt_err_t rt_device_init(rt_device_t dev);
 
 >When a device has been successfully initialized, calling this interface will not repeat initialization.
 
-### Open and Close Device
+## Open and Close Device
 
 Through the device handle, the application can open and close the device. When the device is opened, 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:
 
@@ -333,7 +333,7 @@ rt_err_t rt_device_close(rt_device_t dev);
 
 >Device interfaces `rt_device_open()` and  `rt_device_close()` need to used in pairs. Open a device requires close the device, so that the device will be completely closed, otherwise the device will remain on.
 
-### Control Device
+## Control Device
 
 By commanding the control word, the application can also control the device with the following function:
 
@@ -362,7 +362,7 @@ The generic device command for the parameter `cmd` can be defined as follows:
 #define RT_DEVICE_CTRL_GET_INT          0x12   /* obtain interrupt status */
 ```
 
-### Read and Write Device
+## Read and Write Device
 
 Application can read data from the device by the following function:
 
@@ -400,7 +400,7 @@ rt_size_t rt_device_write(rt_device_t dev, rt_off_t pos,const void* buffer, rt_s
 
 Calling this function will write the data in the buffer to the *dev* device . The maximum length of the written data is *size*, and *pos* has different meanings depending on the device class.
 
-### Data Transceiving and Call-back
+## Data Transceiving and Call-back
 
 When the hardware device receives the data, the following function can be used to call back another function to set the data receiving indication to notify the upper application thread that the data arrives:
 
@@ -432,7 +432,7 @@ rt_err_t rt_device_set_tx_complete(rt_device_t dev, rt_err_t (*tx_done)(rt_devic
 
 When this function is called, the callback function is provided by the user. When the hardware device sends the data, the driver calls back the function and passes the sent data block address buffer as a parameter to the upper application. When the upper layer application (thread) receives the indication, it will release the buffer memory block or use it as the buffer for the next write data according to the condition of sending the buffer.
 
-### Access Device Sample
+## Access Device Sample
 
 The following code is an example of accessing a device. First, find the watchdog device through the  `rt_device_find()` port, obtain the device handle, then initialize the device through the `rt_device_init()`  port, and set the watchdog device timeout through the `rt_device_control()`port.
 

documentation/device/hwtimer/hwtimer.md

@@ -1,7 +1,6 @@
-# HWTIMER Device
+@page device_hwtimer HWTIMER Device
 
-
-## Introduction to the Timer
+# Introduction to the Timer
 
 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.
 
@@ -11,7 +10,7 @@ Hardware timers generally have two modes of operation, timer mode and counter mo
 
 **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
+# Access Hardware Timer Device
 
 The application accesses the hardware timer device through the I/O device management interface provided by RT-Thread. The related interfaces are as follows:
 
@@ -25,7 +24,7 @@ The application accesses the hardware timer device through the I/O device manage
 | rt_device_read()  | to get the current value of the timer |
 | rt_device_close()  | to turn off the timer device. |
 
-### Find 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:
 
@@ -49,7 +48,7 @@ rt_device_t hw_dev;                     /* timer device handle */
 hw_dev = rt_device_find(HWTIMER_DEV_NAME);
 ```
 
-### Open Timer Device
+## 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:
 
@@ -76,7 +75,7 @@ hw_dev = rt_device_find(HWTIMER_DEV_NAME);
 rt_device_open(hw_dev, RT_DEVICE_OFLAG_RDWR);
 ```
 
-### Set the Timeout Callback Function
+## Set the Timeout Callback 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:
 
@@ -117,7 +116,7 @@ static int hwtimer_sample(int argc, char *argv[])
 }
 ```
 
-### Control the Timer Device
+## Control the Timer Device
 
 By sending control words, the application can configure the hardware timer device with the following function:
 
@@ -189,7 +188,7 @@ static int hwtimer_sample(int argc, char *argv[])
 }
 ```
 
-### Set the Timer Timeout Value
+## Set the Timer Timeout Value
 
 The timer timeout value can be set by the following function：
 
@@ -253,7 +252,7 @@ static int hwtimer_sample(int argc, char *argv[])
 }
 ```
 
-### Obtain the Current Value of the Timer
+## Obtain the Current Value of the Timer
 
 The current value of the timer can be obtained by the following function：
 
@@ -279,7 +278,7 @@ rt_hwtimerval_t timeout_s;      /* Used to save the time the timer has elapsed *
 rt_device_read(hw_dev, 0, &timeout_s, sizeof(timeout_s));
 ```
 
-### Close the Timer Device
+## Close the Timer Device
 
 The timer device can be closed with the following function:
 
@@ -310,7 +309,7 @@ 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
+# 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:
 

documentation/device/i2c/i2c.md

@@ -1,6 +1,6 @@
-# I2C Bus Device
+@page device_i2c I2C Bus Device
 
-## Introduction of I2C
+# 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). 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.
 
@@ -28,7 +28,7 @@ When the bus is idle, both SDA and SCL are in a high state. When the host wants
 
 * **Stop Condition：** When SDA is low, the master pulls SCL high and stays high, then pulls SDA high to indicate the end of the transfer.
 
-## Access to I2C Bus Devices
+# Access to I2C Bus Devices
 
 In general, the MCU's I2C device communicates as a master and slave. In the RT-Thread, the I2C master is virtualized as an I2C bus device. The I2C slave communicates with the I2C bus through the I2C device interface. The related interfaces are as follows:
 
@@ -37,7 +37,7 @@ In general, the MCU's I2C device communicates as a master and slave. In the RT-T
 | rt_device_find()  | Find device handles based on I2C bus device name |
 | rt_i2c_transfer() | transfer data |
 
-### Finding I2C Bus Device
+## Finding I2C Bus Device
 
 Before using the I2C bus device, you need to obtain the device handle according to the I2C bus device name, so that you can operate the I2C bus device. The device function is as follows.
 
@@ -62,7 +62,7 @@ struct rt_i2c_bus_device *i2c_bus;      /* I2C bus device handle */
 i2c_bus = (struct rt_i2c_bus_device *)rt_device_find(name);
 ```
 
-### Data Transmission
+## Data Transmission
 
 You can use `rt_i2c_transfer()` for data transfer by getting the I2C bus device handle. The function prototype is as follows:
 
@@ -144,7 +144,7 @@ static rt_err_t read_regs(struct rt_i2c_bus_device *bus, rt_uint8_t len, rt_uint
 }
 ```
 
-## I2C Bus Device Usage Example
+# I2C Bus Device Usage Example
 
 The specific usage of the I2C device can be referred to the following sample code. The main steps of the sample code are as follows: