RT-Thread记录（十二、UART设备—使用测试）

从 UART 设备开始学会使用 RT-Thread I/O 设备模型 。

目录

前言
一、UART 设备操作

1.1 UART 设备控制块
1.2 UART 操作函数
1.2.1 查找 UART 设备
1.2.2 打开/关闭 UART 设备
实际应用中的串口读写说明
1.2.3 控制 UART 设备
1.2.4 发送数据
1.2.5 设置接收回调函数
1.2.6 接收数据

二、UART 设备使用步骤

2.1 RT-Thread setting
2.2 board.h 设置
2.3 应用程序流程

三、UART 示例测试

3.1 与无线模块串口通讯
3.2 示例说明

结语

前言

通过前面的两篇文章，我们基本上完全明白了 RT-Thread I/O 设备模型的基本原理，当然我们的最终目的还是应用，所以本文开始我们就开始进行常用设备的使用学习和测试，就从 UART 设备开始。

从本文开始，就开始进行常用 I/O 设备的学习测试。

本 RT-Thread 专栏记录的开发环境：
RT-Thread记录（一、RT-Thread 版本、RT-Thread Studio开发环境 及 配合CubeMX开发快速上手）
RT-Thread记录（二、RT-Thread内核启动流程 — 启动文件和源码分析）
RT-Thread 设备篇系列博文链接：
RT-Thread记录（十、全面认识 RT-Thread I/O 设备模型）
RT-Thread记录（十一、I/O 设备模型之UART设备 — 源码解析）

一、UART 设备操作

虽然在上一篇文章中，我们已经认识过 RT-Thread UART 的操作函数，但是我们并没有对其参数进行说明。
学习使用一个设备，在 RT-Thread 系统中就是一个对象， 还是得按照我们之前的流程进行简单介绍。

1.1 UART 设备控制块

在我们前面许多文章介绍其他内核对象的时候，我们首先都会介绍其对象控制块，对于 UART 设备而言，它也有自己的控制块。
但是与其他对象机制不同的是，UART 属于 I/O 设备，对于上层应用程序而言，所有的 I/O 设备都是属于 struct rt_device 类。

在我们前面文章《RT-Thread记录（十、全面认识 RT-Thread I/O 设备模型》初次介绍 I/O 设备模型的时候就已经说明了这个统一的控制块：

上面的控制块是对于应用程序而言，在我们的 UART 设备的设备驱动框架层，是有定义了 UART 设备自己的控制块，其继承了rt_device的内容，同时还增加了 UART 设备特有的一些配置，操作，回调函数之类的内容，如下图：

上面的 UART 设备控制块在我们的上一篇文章也有过分析说明。

❤️ UART 设备属于 I/O 设备大类中的一个小类，对于上层应用程序而言，UART 设备控制块rt_serial_device并不透明，我们用户操作的还是 I/O 设备模型的控制块rt_device_t类型。

1.2 UART 操作函数

因为 UART 的操作函数 与 I/O 设备的操作函数基本一致，所以本小结有点类似《RT-Thread记录（十、全面认识 RT-Thread I/O 设备模型》中的 2.3 访问 I/O 设备相关 API 操作，但是针对 UART 设备，也有一些独有的参数说明。

老规矩，函数介绍部分说明看注释。

1.2.1 查找 UART 设备

需要先定义一个 I/O 设备结构体（rt_device_t类型）的指针变量，接收创建好的句柄。

/*
参数 	描述
name 	设备名称,对于UART设备而言，默认一般是 uart0，uart1，uart2，uart3 等
返回 	——
设备句柄 	查找到对应设备将返回相应的设备句柄
RT_NULL 	没有找到相应的设备对象
*/
rt_device_t rt_device_find(const char* name);

1.2.2 打开/关闭 UART 设备

先说打开 UART 设备：

/**
参数 	描述
dev 	设备句柄
oflags 	设备模式标志

oflags可选的的值如下：
#define RT_DEVICE_FLAG_STREAM       0x040     流模式     
接收模式参数
#define RT_DEVICE_FLAG_INT_RX       0x100     中断接收模式
#define RT_DEVICE_FLAG_DMA_RX       0x200     DMA 接收模式
发送模式参数
#define RT_DEVICE_FLAG_INT_TX       0x400     中断发送模式
#define RT_DEVICE_FLAG_DMA_TX       0x800     DMA 发送模式

返回值：
RT_EOK 	设备打开成功
-RT_EBUSY 	如果设备注册时指定的参数中包括 RT_DEVICE_FLAG_STANDALONE 参数，此设备将不允许重复打开
其他错误码 	设备打开失败
 */
rt_err_t rt_device_open(rt_device_t dev, rt_uint16_t oflag)

打开设备时，会检测设备是否已经初始化，没有初始化则会默认调用初始化接口初始化设备。

如果 oflags 没有指定使用中断模式或者 DMA 模式，则默认使用轮询模式。

这里有个问题，流模式是什么情况下使用的？485通讯? 暂时不知道，希望知道的朋友能够给个说明。

在官方的文档中，关于流模式有如下说明：

实际应用中的串口读写说明

串口RX：

在我们正常的项目使用中，一般都是 中断接收 或者 DMA 接收，基本上不会使用 轮询接收的方式（极大的浪费资源，反正我是没用过）。

所以我们打开串口设备的时候，基本上都是如下两种：

rt_device_open(serial, RT_DEVICE_FLAG_INT_RX);

rt_device_open(serial, RT_DEVICE_FLAG_DMA_RX);

在 RT-Thread 系统中，我们常用信号量或者消息队列 来标志是否接收到串口数据，这样的好处是当没有数据的时候，会将数据处理线程挂机，让出CPU资源。

串口TX：

对于串口 TX 来说，大部分项目中我自己一直都用的是 轮询 方式发送。

对于串口的中断发送方式，在上一篇文章我们分析 UART 源码，虽然没有详细说明，但是实际上在设备驱动层 drv_usart.c 驱动文件里，中断发送方式最终还是调用了该驱动文件里面的stm32_putc函数：

我感觉还是和轮询一样，将数据写入 数据寄存器DR，使用while死等发送完成（虽然时间很短）。

上面虽然只是 RT-Thread 中的UART设备驱动文件，也多少能说明一些问题，中断发送最终无非就是发送完了多一个中断通知。

对于另外一种 DMA 发送，我记得以前听老人提到过，DMA发送使用不得当，可能导致发送数据异常，简单来说就是 DMA 发送函数返回后，数据都不一定发送完成了，如果此时修改了 DMA 发送指定的buffer 区的内容，那么后面的数据就错误了。

所以，如果没有特殊需求，我们项目中的串口发送使用 轮询发送 即可（有些特殊情况的根据自己的实际需求而定）。

所以结合上面所说，我们实际应用中，使用以下两种方式打开串口设备能满足大部分场合需求：

/*轮询方式发送，中断接收*/
rt_device_open(serial, RT_DEVICE_FLAG_INT_RX);
/*轮询方式发送，DMA接收*/
rt_device_open(serial, RT_DEVICE_FLAG_DMA_RX);

有打开设备，当然也有关闭设备:

/**
参数 	描述
dev 	设备句柄
返回 	——
RT_EOK 	关闭设备成功
-RT_ERROR 	设备已经完全关闭，不能重复关闭设备
其他错误码 	关闭设备失败
 */
rt_err_t rt_device_close(rt_device_t dev)

关闭设备接口和打开设备接口需配对使用，打开一次设备对应要关闭一次设备，这样设备才会被完全关闭，否则设备仍处于未关闭状态。

当然在一般的应用场合，用到串口通讯的地方设备都是需要一直开启的，所以很多情况下都不需要使用 UART 设备关闭函数。

1.2.3 控制 UART 设备

rt_device_control 一般用在 rt_device_open （打开串口设备）之前，对需要使用的串口进行必要的配置。

/**
参数 	描述
dev 	设备句柄
cmd 	命令控制字，可取值：RT_DEVICE_CTRL_CONFIG
arg 	控制的参数，可取类型： 
struct serial_configure
{
    rt_uint32_t baud_rate;             波特率 
    rt_uint32_t data_bits    :4;       数据位 
    rt_uint32_t stop_bits    :2;       停止位 
    rt_uint32_t parity       :2;       奇偶校验位 
    rt_uint32_t bit_order    :1;       高位在前或者低位在前 
    rt_uint32_t invert       :1;       模式 
    rt_uint32_t bufsz        :16;      接收数据缓冲区大小 
    rt_uint32_t reserved     :4;       保留位 
};

波特率可取值：
#define BAUD_RATE_2400                  2400
#define BAUD_RATE_4800                  4800
#define BAUD_RATE_9600                  9600
#define BAUD_RATE_19200                 19200
#define BAUD_RATE_38400                 38400
#define BAUD_RATE_57600                 57600
#define BAUD_RATE_115200                115200
#define BAUD_RATE_230400                230400
#define BAUD_RATE_460800                460800
#define BAUD_RATE_921600                921600
#define BAUD_RATE_2000000               2000000
#define BAUD_RATE_3000000               3000000

数据位可取值：
#define DATA_BITS_5                     5
#define DATA_BITS_6                     6
#define DATA_BITS_7                     7
#define DATA_BITS_8                     8
#define DATA_BITS_9                     9

停止位可取值：
#define STOP_BITS_1                     0
#define STOP_BITS_2                     1
#define STOP_BITS_3                     2
#define STOP_BITS_4                     3

极性位可取值：
#define PARITY_NONE                     0
#define PARITY_ODD                      1
#define PARITY_EVEN                     2

高低位顺序可取值：
#define BIT_ORDER_LSB                   0
#define BIT_ORDER_MSB                   1

模式可取值：
#define NRZ_NORMAL                      0     
#define NRZ_INVERTED                    1 
    
接收数据缓冲区默认大小：
#define RT_SERIAL_RB_BUFSZ              64

返回 	——
RT_EOK 	函数执行成功
-RT_ENOSYS 	执行失败，dev 为空
其他错误码 	执行失败
 */
rt_err_t rt_device_control(rt_device_t dev, int cmd, void *arg)

我们已经知道，在串口初始化的时候会有一个默认配置：

所以在我们使用串口的时候，如果对应的配置与默认的配置不一样，就需要使用此函数修改配置。

接收缓冲区：

当串口使用中断接收模式打开时，串口驱动框架会根据 RT_SERIAL_RB_BUFSZ 大小开辟一块缓冲区用于保存接收到的数据，底层驱动接收到一个数据,都会在中断服务程序里面将数据放入缓冲区。

在修改缓冲区大小时请注意，缓冲区大小无法动态改变，只有在 open 设备之前可以配置。open 设备之后，缓冲区大小不可再进行更改。但除缓冲区之外的其他参数，在 open 设备前 / 后，均可进行更改。

串口控制修改使用官方修改示例说明一下：

#define SAMPLE_UART_NAME       "uart2"    /* 串口设备名称 */
static rt_device_t serial;                /* 串口设备句柄 */
struct serial_configure config = RT_SERIAL_CONFIG_DEFAULT;  /* 初始化配置参数 */

/* step1：查找串口设备 */
serial = rt_device_find(SAMPLE_UART_NAME);

/* step2：修改串口配置参数 */
config.baud_rate = BAUD_RATE_9600;        //修改波特率为 9600
config.data_bits = DATA_BITS_8;           //数据位 8
config.stop_bits = STOP_BITS_1;           //停止位 1
config.bufsz     = 128;                   //修改缓冲区 buff size 为 128
config.parity    = PARITY_NONE;           //无奇偶校验位

/* step3：控制串口设备。通过控制接口传入命令控制字，与控制参数 */
rt_device_control(serial, RT_DEVICE_CTRL_CONFIG, &config);

/* step4：打开串口设备。以中断接收及轮询发送模式打开串口设备 */
rt_device_open(serial, RT_DEVICE_FLAG_INT_RX);

1.2.4 发送数据

/**
参数 	描述
dev 	设备句柄
pos 	写入数据偏移量，此参数串口设备未使用
buffer 	内存缓冲区指针，放置要写入的数据
size 	写入数据的大小
返回 	——
写入数据的实际大小 	如果是字符设备，返回大小以字节为单位；
0 	需要读取当前线程的 errno 来判断错误状态
 */
rt_size_t rt_device_write(rt_device_t dev,
                          rt_off_t    pos,
                          const void *buffer,
                          rt_size_t   size)
                          

写其实很好理解，除了多一个设备句柄参数，和我们裸机中使用的发送函数一样，看一下一个普通的裸机串口发送函数：

这里说明一下，因为我们上面分析过实际应用中的串口读写，一般都使用轮询发送，所以我这里并不打断介绍 设置发送完成回调函数 。

1.2.5 设置接收回调函数

/**
参数 	描述
dev 	设备句柄
rx_ind 	回调函数指针

回调函数参数 描述
dev 		设备句柄
size 		缓冲区数据大小
返回 	——
RT_EOK 	设置成功
 */
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))

若串口以中断接收模式打开：
当串口接收到一个数据产生中断时，就会调用回调函数，并且会把此时缓冲区的数据大小放在 size 参数里，把串口设备句柄放在 dev 参数里供调用者获取。

若串口以 DMA 接收模式打开：
当 DMA 完成一批数据的接收后会调用此回调函数。

在使用 RT-Thread 时候，一般会用一个信号量通知串口数据处理线程有数据到达。

在使用 RT-Thread Nano 的时候，其实我也是使用信号量来处理数据的接收:

具体详情可查看博文：RT-Thread 应用篇 — 在STM32L051上使用 RT-Thread (四、无线温湿度传感器 之 串口通讯)

回调函数处理的示例我们使用官方示例说明，与下面的接收数据函数一起展示。

1.2.6 接收数据

数据接收处理函数，在接收回调函数运行之后运行。

/**
参数 	描述
dev 	设备句柄
pos 	读取数据偏移量，此参数串口设备未使用
buffer 	缓冲区指针，读取的数据将会被保存在缓冲区中
size 	读取数据的大小
返回 	——
读到数据的实际大小 	如果是字符设备，返回大小以字节为单位
0 					需要读取当前线程的 errno 来判断错误状态
 */
rt_size_t rt_device_read(rt_device_t dev,
                         rt_off_t    pos,
                         void       *buffer,
                         rt_size_t   size)

我们与上面的设置接收回调函数一起使用官方示例作为说明：

#define SAMPLE_UART_NAME       "uart2"    /* 串口设备名称 */
static rt_device_t serial;                /* 串口设备句柄 */
static struct rt_semaphore rx_sem;    /* 用于接收消息的信号量 */

/* 接收数据回调函数 */
static rt_err_t uart_input(rt_device_t dev, rt_size_t size)
{
    /* 串口接收到数据后产生中断，调用此回调函数，然后发送接收信号量 */
    rt_sem_release(&rx_sem);

    return RT_EOK;
}

/* 接收数据的线程 */
static void serial_thread_entry(void *parameter)
{
    char ch;

    while (1)
    {
        /* 从串口读取一个字节的数据，没有读取到则等待接收信号量 */
        while (rt_device_read(serial, -1, &ch, 1) != 1)
        {
            /* 阻塞等待接收信号量，等到信号量后再次读取数据 */
            rt_sem_take(&rx_sem, RT_WAITING_FOREVER);
        }
        /* 读取到的数据通过串口错位输出 */
        ch = ch + 1;
        rt_device_write(serial, 0, &ch, 1);
    }
}

static int uart_sample(int argc, char *argv[])
{
    serial = rt_device_find(SAMPLE_UART_NAME);

    /* 以中断接收及轮询发送模式打开串口设备 */
    rt_device_open(serial, RT_DEVICE_FLAG_INT_RX);

    /* 初始化信号量 */
    rt_sem_init(&rx_sem, "rx_sem", 0, RT_IPC_FLAG_FIFO);

    /* 设置接收回调函数 */
    rt_device_set_rx_indicate(serial, uart_input);
}

示例中使用的是信号量，收到一个数据，便会唤醒接收数据的线程，所以其实是一个字节一个字节（一个字符等于一个字节）的读取， 示例处理方式只能使用 RT_DEVICE_FLAG_INT_RX 方式接收。

❤️ 接收数据rt_device_read 函数的返回值需要注意一下，返回值为读到的数据实际大小，就是接收到的数据长度。

二、UART 设备使用步骤

简单介绍一下在 RT-Thread Studio 开发环境下 UART的使用步骤。

2.1 RT-Thread setting

如果需要使用某个设备，是需要在 ENV 工具中配置的，现在有了 RT-Thread Studio ，所以可以直接通过工程目录下的 RT-Thread setting 进行图形化界面的配置，如下图：

因为Shell 工具需要使用串口，所以默认串口这里已经是勾选中的，这里说明只是为了让大家知道，在以后的 I/O 设备使用的时候，第一步就是在 RT-Thread setting 中使能设备。

2.2 board.h 设置

完成设备使能，我们还需要使用宏定义进行串口的基本设置，该设置在board.h文件中进行，如下图：

board.h 中包括了很多外设的使用说明，除了 UART，还有I2C、SPI、ADC等设备，我们在后面学习这些设备使用的时候，需要经常用到这个头文件，一些基本的使能配置都是在这个文件中用宏定义使能。

2.3 应用程序流程

完成上面 2 步的基本配置以后，我们就可以在应用程序通过上文介绍的 UART 设备操作函数进行串口的使用，具体的步骤概括如下：

UART 设备使用步骤 :
/
#include "rtdevice.h"
/
1、使用rt_device_find查找串口设备；
/
2、根据需求使用rt_device_control设置串口；
/
3、初始化回调函数中使用的信号量（在接收回调函数中 发送信号量 唤醒数据处理线程），如果使用消息队列接收初始化消息队列；
/
4、使用rt_device_open打开串口设备（根据自己的情况判断使用什么方式接收，发送前面分析过了，一本应用使用轮询发送即可）；
/
5、使用rt_device_set_rx_indicate设置串口设备的接收回调函数
/
6、创建数据读取的线程。

按照上面的步骤，我进行了如下的示例测试，不要忘记 #include "rtdevice.h"：

上图其实是根据官方示例代码，使用的 ESP8266 WIFI 模块做了一个简单的测试：

三、UART 示例测试

在上面介绍应用程序流程的时候，其实已经做了一个简单的示例测试。

同时在官方已经也提供了3种典型的示例程序：

中断接收及轮询发送、DMA 接收及轮询发送、串口接收不定长数据

作为以应用为目的系列博文，我自己还是根据自己的工作需求进行串口通讯的测试，使用的是 Enocean 无线通讯模块，当时在 RT-Thread 的应用篇，RT-Thread Nano 使用记录的时候就使用的这个无线模块。

要说明的是，用什么模块做通讯并不是重点，重点在于使用过程中对串口数据的处理方式。

3.1 与无线模块串口通讯

虽然换了一个通讯设备，但是官方给的例程：中断接收及轮询发送 还是适用的，我们先来看一看直接使用官方的例程做的测试：

/* 接收数据回调函数 */
static rt_err_t uart_input(rt_device_t dev, rt_size_t size)
{
    /* 串口接收到数据后产生中断，调用此回调函数，然后发送接收信号量 */
    rt_sem_release(&rx_sem);
    return RT_EOK;
}
static void test_thread_entry(void *par){
    uint8_t ch;
    while (1)
    {
        /* 从串口读取一个字节的数据，没有读取到则等待接收信号量 */
        while (rt_device_read(testuart, -1, &ch, 1) != 1)
        {
            /* 阻塞等待接收信号量，等到信号量后再次读取数据 */
            rt_sem_take(&rx_sem, RT_WAITING_FOREVER);
        }
        rt_kprintf("%x ",ch);
    }
}

其测试结果如下：

为了更好的做数据解析，我们需要对原始的程序进行修改，使得能够针对一帧数据一帧数据进行接收处理：

uint8_t USART_Enocean_BUF[64];
uint8_t Enocean_Data = 0;

/* 接收数据回调函数 */
static rt_err_t uart_input(rt_device_t dev, rt_size_t size)
{

    Enocean_Data = size;
    /* 串口接收到数据后产生中断，调用此回调函数，然后发送接收信号量 */
    rt_sem_release(&rx_sem);
    return RT_EOK;
}
static void test_thread_entry(void *par){
    uint8_t i = 0;
    while (1)
    {
        if(rt_sem_take(&rx_sem, RT_WAITING_FOREVER) == RT_EOK){
              while(!rt_sem_take(&rx_sem, 7));
              rt_device_read(testuart, -1, USART_Enocean_BUF, Enocean_Data);

        }

        for (i = 0; i < Enocean_Data; ++i) {
            rt_kprintf("%x ",USART_Enocean_BUF[i]);
        }
        rt_kprintf("\r\n");

        rt_memset(&USART_Enocean_BUF, 0, sizeof(USART_Enocean_BUF));
        Enocean_Data = 0;
    }
}

测试结果如下，实现了我们所需要的的针对每一帧数据的接收（既然都已经可以区别每一帧数据了，所那么后续的处理也就简单了）：

对于数据的接收处理信号量只是其中一种。
即便是信号量，也有多种可实现行的方式，而上面我测试使用的方式也只不过其中的一种：收到第一个数据的时候等待一定的时间，然后认为是一帧数据接收完成。
这也只是判断一帧数据接收完成的方法中的一种 = =！

3.2 示例说明

在上面我们用了信号量作为通知的方式接收串口数据，官方的示： DMA 接收及轮询发送 采用了消息队列的方式进行处理，表面上看起来与我们上面那种方式不一样。

其实本质都是一样的，都不过是给线程一个通知，并没有“真正意义上的传递了消息”（比如串口接收到的数据）：

如果想要使用消息队列作为缓存正常的传输串口接收的数据，不使用 I/O 设备模型的情况下更加适合，究其原因，如下图分析：

如上面表格所说，使用了I/O 设备模型之后，我们底层串口初始化的时候已经有了一段数据接收的buffer了，所以我们直接使用 rt_device_read 函数从驱动层的 buffer 读取数据，用临时 buffer 来处理就可以了（不过如果需要对处理程序，单独设计函数，也可以用一个全局 buffer 来处理），也不过是2个buffer 的内存占用。

所以在官方的示例中，虽然给的是信号量，和消息队列的不同的处理方式，但是究其根本还是一样的。只是给了一个通知，这个其他的 IPC机制 比如 事件集一样可以做到，即便不用 IPC 机制，普通简单的应用，全局变量也未尝不可。（对于消息队列传递串口接收数据的应用，以后我还是会单独的说明的，本文在于说明 UART 基于 I/O 设备模型的使用，所以就不做测试了 = =！）

❤️ 使用了 UART 设备模型，最终还是需要使用rt_device_read函数，从内部缓存读取串口数据，IPC只不过是给线程一个通知。

结语

一个 UART 设备画了两篇文章，还算是比较值得的，通过上一篇文章加深对 RT-Thread I/O 设备模型的理解，通过本文实际体验了一把 UART 设备。

体验上来说，还是感觉特别方便简单的。但是这个前提条件时，能够真正的理解 RT-Thread I/O 设备模型，理解到位才能用起来游刃有余，也能够在以后出问题的时候更容易的发现问题，解决问题。

❤️ 学会了使用一个东西当然是一件庆幸的事情，但是能够理解它才是更加重要的事情！ ❤️