基于ESP32+Platformio的物联网RTOS_SDK-CC_Device

本项目基于ESP32以及Platformio平台开发，请自行查阅如何配置这个环境
开源gitee地址：cc_smart_device
如果愿意贡献项目or提出疑问和修改的，请在gitee上提issue
项目里的mqtt服务器是公共的 请大家最好换成私有的 否则容易收到其他用户的错误数据

1 基本介绍

该项目主要用于更加便捷快速的开发esp32的APP
项目的初衷来自于大学的毕设是一个物联网的设备，工作中学习到了一些编码技巧，想应用在自己的实际项目中，加上ESP32自带的FreeRTOSAPI我觉得实在是太丑了，所以制作了这个SDK，用于未来物联网项目的便捷开发。

2 基本架构

项目的系统框图如下

本项目的特色有

• 宏定义注册初始化函数，用户无需在主函数中显式调用初始化函数，只需要通过宏定义进行函数的自动初始化，并且有优先级机制
• 宏定义注册线程，线程不需要用户在主函数进行创建，只需要通过宏定义创建线程，耦合度低
• Shell命令行导出函数，Shell命令补全，进行测试以及一些交互，方便用户进行调试。
• 宏定义注册MQTT主题对应的回调，当接收到一个主题消息时，会自动路由到该回调中
• 统一的消息层接口，使得不同节点的消息可以调用统一的上层API
• 宏定义注册消息分发，消息将会自动路由到回调中
• 宏定义注册设备初始化函数，用户不需要像linux的设备驱动那样手动设置读写控制的回调
• cc_config.h中可以配置开关WIFI，MQTT，设备分发等，实现体积缩减以及简洁程序方便自定义
• 实现抽象设备类，用户加入的物联网设备只需按规定实现对应的读写，控制函数

整个项目构成文件夹如下

• device（设备层）
  • abs_device（抽象设备类 用户设备按需实现抽象设备类的函数即可）
  • borad_device（板级设备支持，例如IIC，串口，WIFI）
  • user_device（用户自定义设备）
• middleware（中间件部分）
  • core（RTOS相关组件）
  • log（日志打印接口）
  • shell（命令行交互）
  • msg（消息层）
• user_app（用户应用层）
  非必要情况下 用户只需要改变user_app里的代码即可，其他可通过cc_config.h进行配置实现

3 中间件

3.1 RTOS部分

3.1.1 互斥锁

互斥锁用于多线程中的线程安全同步，在一个线程持有锁时，另一个线程试图获取锁时将遭遇阻塞，或超时失败不处理等。因为多个线程对一个共享变量（例如全局变量）的访问是不安全的，可能会造成不同步问题。具体互斥锁用法可以看CSDN，有很多。

cc_mutex_create	动态创建一把互斥锁
cc_mutex_init	静态创建一把锁
cc_mutex_lock	上锁操作 拿不到锁则永久阻塞等待
cc_mutex_trylock	上锁操作 拿不到锁直接return
cc_mutex_lock_time	上锁操作 上锁指定时间
cc_mutex_unlock	解锁操作
cc_mutex_del	删除一把锁（动态）

3.1.2 信号量

可以实现类似生产者消费者的模式，通过发送信号量的形式，另一个接收信号量的线程收到信号时，就会执行接下来的业务逻辑。也可以实现线程同步机制，信号量发送一次后，可以理解为有一个计数值+1，然后其他线程检测到这个计数值不是0了。就会消费掉这个计数值，然后进行自己接下来的逻辑操作，同理，如果信号量释放了三次，也会被消费三次，具体信号量用法可以看CSDN，有很多。

cc_sem_create	动态创建一个信号量
cc_sem_init	静态创建一个信号量
cc_sem_release	释放一个信号量
cc_sem_wait	等待一个信号量，拿不到就永久阻塞
cc_sem_try_wait	等待一个信号量，拿不到就直接走return
cc_sem_wait_time	等待一个信号量，拿不到就等待指定时间
cc_sem_get_cnt	获取信号量计数值
cc_sem_del	删除一个信号量

3.1.3 消息队列

实现多线程间的通信，将消息复制到一条队列中去发送，另一个接收这个队列的将会收到该条消息，实现安全的线程通信（因为如果有全局变量通信是线程不安全的，互斥锁在这里是不合适的，复杂了那样，而且互斥锁只有1和0的关系，不够灵活）

cc_queue_create	创建一个消息队列 参数是队列长度和每个消息的大小
cc_queue_init	静态创建一个消息队列
cc_queue_deinit	删除一个队列(用于静态接口)
cc_queue_send_time	发送消息到队尾，若队列满 等待指定时间看看是否能入队
cc_queue_send	发送消息到队尾 若队列满 则永久等待队列有空闲位置
cc_queue_send_try	发送消息到队尾 若队列满则return
cc_queue_send_urgent_time	发送紧急消息 也就是发送到队头进行插队，若发送不了则等待指定时间看看能否入队
cc_queue_send_urgent_try	发送紧急消息 发不了就走
cc_queue_send_urgent	发送紧急消息 永久等待
cc_queue_send_overwrite	发送消息，覆盖写入，也就是如果队列满了，这将覆盖队列的第一条数据
cc_queue_recv_time	队列接收，如果指定时间没接收到则return
cc_queue_recv	队列接收，若没接收到则阻塞
cc_queue_recv_try	队列接收，若没接收到就直接return
cc_queue_destory	删除一个队列(用于动态接口)

3.1.4 软件定时器

就是在模拟硬件定时器的效果而已，没什么

cc_timer_create	创建一个定时器 参数是定时时间，定时器类型（单次多次），回调函数
cc_timer_reset	定时器复位
cc_timer_start	定时器启动
cc_timer_stop	定时器停止
cc_timer_change_time	定时器改变定时周期
cc_timer_get_systick	定时器获取系统滴答计时器
cc_timer_init	静态创建一个定时器
cc_timer_change_time	改变定时器周期
cc_timer_change_time_and_start	懒得解释了
cc_timer_change_time_and_stop	懒得解释了
cc_timer_create_and_start
cc_timer_init_and_start
cc_timer_deinit	反初始化 用于静态接口
cc_timer_destory	销毁 用于动态接口

3.1.5 线程

具体多任务多线程这种和裸机的区别，大家自己看csdn吧。

cc_thread_yield	任务切换
cc_is_in_isr	是否在中断
cc_thread_self	获取当前线程TID
cc_thread_delete	根据TID删除线程
cc_thread_delete_by_name	根据名字删除线程
cc_thread_delete_by_cb	根据回调删除线程
cc_get_tid_by_cb	根据回调获得TID
cc_get_tid_by_name	根据名字获得TID
cc_thread_create_raw
cc_thread_create_stack_size
cc_thread_create_default
cc_thread_resume_all	唤醒所有线程
cc_thread_suspend_all	挂起所有线程
cc_thread_resume	唤醒指定线程
cc_thread_suspend	挂起指定线程
cc_thread_enter_critical	进入临界段
cc_thread_exit_critical	退出临界段
cc_thread_get_priority	获得优先级
cc_thread_set_priority	设置优先级
cc_thread_get_state	根据TID获取线程状态
cc_thread_get_state_by_name	根据名字获取线程状态
cc_thread_get_state_by_cb	根据回调获取线程状态
cc_get_min_stack_using_size	根据TID获取线程剩余的最小栈空间
cc_get_min_stack_using_size_by_name	根据名称获取线程剩余的最小栈空间
cc_get_min_stack_using_size_by_cb	根据回调获取线程剩余的最小栈空间

3.1.5.1自动初始化机制

普通的函数接口大家就直接看源码吧，有过基础的肯定会用，这里主要讲一下自动初始化组件，这这里，我提供了两个宏定义，用于初始化线程，如何使用呢？只需要调用宏定义即可

CC_THREAD_REGISTER_ALIAS	参数是 线程回调，线程优先级，栈大小
CC_THREAD_REGISTER	参数是 线程回调，线程优先级，栈大小，线程名字

第一个为什么可以不传参呢？因为这里的#fun,就是把函数名字变成字符串，传入了CC_THREAD_REGISTER_ALIAS的第四个名称参数中。这是一些宏定义的奇怪用法！！！非常的酷炫
S

attribute((constructor)) 这个字段，则是可以让这个宏函数，在main函数之前执行，也就是实现所谓的自动初始化效果，具体源码这里暂不讲解。大家可以自己研究。

使用宏定义创建有一个非常大的好处就是，主函数不再需要进行任务的创建，利于项目复杂度高时进行管理，并且我会把所有的线程信息都存储下来。使得整个程序对任务的管理更加方便，代码的耦合度也更低。

一个简单的小例子。

这样就实现了一个心跳线程的创建，不需要的时候直接注释宏定义，main函数里面什么都不用，当项目体量大的时候，这样的好处会非常明显。

3.1.6 内存分配与回收

简单 直接看就行，就是free和malloc而已

3.1.7 条件变量

条件变量用于让线程等待一个条件，阻塞等待，当然，超时了也可以返回，互斥锁只有0和1的关系，而条件变量可以实现多对1个触发条件的效果，具体大家可以看csdn，”条件变量和互斥锁的区别“，和信号量的区别在，信号量是计数的，可以释放多次，释放几次，就会被拿到几次执行几次。而条件变量则是释放一次，等待这个条件的线程则会执行一次，如果是广播释放，则会全部执行。

cc_cond_create	动态创建一个条件变量
cc_cond_init	静态创建一个条件变量
cc_cond_wait	等待一个条件变量，拿不到就永久阻塞
cc_cond_try_wait	等待一个条件变量，拿不到就直接走return
cc_cond_wait_ms	等待一个条件变量，拿不到就等待指定时间
cc_cond_signal	释放一个条件变量，拿到条件的线程就执行
cc_cond_broadcast	广播释放，所有等待该条件的线程都执行下去

3.1.8 内存池

注意 内存池申请大小时,请用宏MEM_BLOCK_REAL_SIZE(sz)申请你需要的单个数据块大小,静态初始化时MEMPOOL_TOTAL_REAL_SIZE(num,sz)分配静态数组大小,因为内部存储结构有指针,所以数据有内存要留给指针,导致比如用户申请了20的内存,实际只有16而MEM_BLOCK_REAL_SIZE(sz)这个宏帮你进行了这片内存的增加

cc_mempool_t cc_mempool_create(size_t block_num, size_t block_size) ;	动态创建一个内存池
int cc_mempool_init(cc_mempool_t pool,void *smem, size_t sz, size_t block_size);	静态创建一个内存池
int cc_mempool_destroy(cc_mempool_t pool) ;	销毁内存池(暂未实现)
void* cc_mempool_alloc(cc_mempool_t pool)	申请一片内存(永久等待)
void* cc_mempool_try_alloc(cc_mempool_t pool) ;	申请一片内存(不等待)
void* cc_mempool_alloc_time(cc_mempool_t pool, uint32_t timeout) ;	申请一片内存(等待单位时间)
int cc_mempool_free(cc_mempool_t pool, void *m) ;	释放对应内存

3.2 日志接口

使用方法和printf完全兼容。

cc_log	打印正常日志
cc_log_e	打印异常日志

​ 使用日志打印比起正常的printf有个好处就是，会告诉你时间，函数，以及处于哪一行，是否出错这样的。相当于这样，会为你添加前缀

3.3 Shell命令行

3.3.1 简单介绍

开发这个组件的目的是因为，大家有没有发现，我们在测试程序的时候很麻烦，总是这里注释一下，那边注释一下。如果有很多个测试程序的话，可能还要根据串口然后switch case一个个执行，那么有没有一种办法可以像例如git,linux那样和命令行交互呢，当然可以了，所以我开发了这个命令行组件，方便大家进行一些测试用例的导出，以及控制一些变量的数值来实现**”功能的开关“**等。

**使用的方法很简单，同样也是通过宏定义进行注册。**就和之前的线程是一样的

CC_COMMAND_SHELL_ALIAS(func, name, info)	参数是 回调函数，测试用例别名，介绍信息
CC_COMMAND_SHELL(func, info)	参数是 回调函数，介绍信息，该测试用例的名字就是函数名

使用格式！！！！！！！！！！

shell 测试用例名字 参数1 参数2

不传参就是 shell 测试用例名字

参数为可变长形式 可以传无限多个参数 具体可以看代码里的测试用例 example文件夹中

一个小例子。我们写下heart_debug函数，用宏定义CC_COMMAND_SHELL导出到Shell命令行中

这就是一个简单的控制心跳任务开关的用例导出，通过cc_get_tid_by_cb函数（通过线程回调获取线程TID），再根据传入的param1，对该线程进行挂起或者恢复的操作，在命令行中使用如下。

3.3.2 常用命令介绍

1:shell help 会打印这个程序支持的所有命令，例如

2：shell tid_info 打印线程信息

**3： xx_debug，**就是打开调试信息，打开后会显示对应的debug调试信息，例如一个消息的解析过程，主要是调试的时候用的。例如我这边如果全部打开。（图中参数前的逗号）

打开了三个调试功能，下面如果我们再次输入shell help会出现什么呢？

显示了一条消息从消息层收到的原始消息 shell_help,再到shell_data_handle处理是否是自己的消息，并解析，最后发送到shell线程，最终得到执行后，回复到msg层执行的结果。

4：mqtt相关

就是对应的意思

例如串口发送 shell mqtt_subsribe cc_test 就会订阅 cc_test主题

如果串口发送 shell mqtt_publish cc_test hello 回调就会收到hello

3.4 Msg消息层

3.4.1 msg

主要负责进行各个节点的消息接收，在本项目中，不同的发送信道，被认为是一个节点，并有其对应的发送队列。提供了一个统一的消息入口。例如刚刚的shell tid_info这种命令，既可以基于串口那边，从”串口节点“发送过来，也可与从MQTT那边，从MQTT节点发送过来，主要目的是实现消息的分发路由。同时，这样对不同消息节点的轮询判断，就不会导致，全部发到一条队列时，如果有一个信道的消息过多，导致响应其他信道消息的消息太慢的情况。

但是虽然目前这个消息层写的不太好，也不完善，只是一个简单实现。

我也深知自己的技术水平目前还不足以写出一套例如握手，确认帧的这种完整的消息链路传递，会涉及到很多的对端设计，还是非常麻烦的

以后技术水平上来了会慢慢重构，而且那个也会增加项目的复杂度，有可能对用户来说也更复杂了。

目前的消息路由是

节点携带消息发送到队列 -> 消息线程 -> 轮询判断队列是否有消息 -> 有的话接收并进行消息的处理or进一步转发出去

int cc_msg_send(int node, char *data, int len, char *topic, int topic_len);	消息发送(最后两个参数是给mqtt的 普通节点可以不用)
void cc_msg_resp(int node, char *data, int len, char *topic);	消息回复(目前只支持串口和MQTT)

MSG层同样支持宏定义注册功能

CC_MSG_HANDLE_REGISTER(func, prefix_name) 用户可以通过这个宏定义注册自己对应的消息前缀的回调，数据以节点+消息帧的形式及进行传输
消息帧的结构体如下

例如我这里就注册了shell 消息的回调，这也是为什么我们前面的shell命令行的格式 是以 shell+空格 开头，数据存在node节点的mem中，用户可以通过这样的形式获取数据

解析数据采用以下形式，数据就在这个frame中

3.4.2 mqtt

作为消息层里的一个传输节点存在，里面的回调调用了cc_msg_send函数，如果mqtt的消息匹配到了上面的那些shell help这种的规则命令（还未加入主题进行路由判断，很简单后面一加就好），就会执行到对应的shell命令，这就是抽象分发层的好处。同理，这个程序也表示了我们使用线程注册的好处，其实我在这个c文件里面已经注册开启了这个线程了，但其实对用户来说，主函数里这个线程是”不可见“的。解除了代码的耦合。

然后mqtt功能可以通过cc_config.h里的CC_CONFIG_USE_MQTT开启注意，开启这个宏定义的同时 WIFI 也要一同开启，因为MQTT要基于网络使用。
本项目中多个地方都运用回到了宏定义注册的功能.这里 **MQTT 的订阅也应用了宏定义注册功能,将订阅主题和回调绑定在了一起,**调用了宏定义的,可以自动订阅这个topic,触发到topic对应的宏定义

CC_TOPIC_SUBSRIBE_ALIAS(cb, topic)	参数1回调 参数2主题
CC_TOPIC_SUBSRIBE(cb)	参数1回调,自动订阅的主题就是回调的名字

CC_TOPIC_SUBSRIBE_ALIAS(heart_msg, “heart”) 例如调用这个宏定义后,程序内部就会自动帮你订阅heart这个主题,收到主题消息后将触发你的heart_msg函数回调

CC_TOPIC_SUBSRIBE(heart_msg) 将会自动帮你订阅 “heart_msg” 这个主题,并触发你heart_msg回调.
其他API

cc_msg_mqtt_publish(const char *topic, const char *data);	发布消息
cc_msg_mqtt_subsribe(const char *topic);	消息订阅
cc_get_mqtt_state	连接状态

3.4.3 device_msg

这是设备消息层，主要用来进行设备消息的分发。是提前规定好了消息帧格式以及帧头的，可以通过配置文件CC_CONFIG_USE_DEVIEMSG开启或者关闭。

消息帧头和格式可以通过 shell d_distr_help 打印

帧头也可以通过CC_CONFIG_DEVICE_DISTR_HEAD进行配置。

当用户注册了设备（这里后面会写到怎么注册） 并且发送了正确的消息后，消息将会被路由到这个设备的回调or线程中去，如果消息帧表面是异步的，那么就会发送到设备内部的消息队列，用户可以自行去接收并做对应处理，如果是同步，则会直接调用这个设备的对应的读写或者控制的回调函数，然后操作到实际的硬件中。

这里就是一条消息发送完成，发送到分发层，状态机根据逗号进行解包，发送到设备分发层线程，最终处理完成调用硬件的写回调，以及默认的退出回调的过程。

4 设备

4.1 简介

基于linux的设备驱动的设计思想,设计了一个抽象设备类**,hard_drv为设备的真实物理硬件驱动**,id和类型就是单纯的设备ID与类型，pin用于那种引脚不多的设备可以内部初始化时使用,剩下的那些状态啊,缓冲区啊,num_data主要用于存储设备信息(我知道这样不节约内存 但是方便)。

最重要的还是中间四个函数,初始化,读,写,控制的回调(后续会增加关闭回调,和复位回调那些)。

这四个函数就是底层用户自己实现的时候需要重写的函数,这样消息路由到每个设备的时候,就可以自动调用对应设备的回调,进而操作到对应设备的硬件驱动函数,实现代码的解耦合。

几个退出回调主要用于操作完成后,需要的后续操作,系统的默认实现是不操作,用户如果定义了的话,就按用户操作走,比如读取数据完,发送到mqtt,那么读取数据这个操作就是read_cb实现,发送到mqtt就是read_exit_cb实现。

后面的三个变量为，互斥锁和队列以及静态创建队列所需的存储消息的内存块大小(主要用于异步通信使用),例如操作led设备时,既可以通过回调直接同步操作,也可以通过发送消息到它的队列里,等待队列拿出消息执行,异步操作。

4.2 设备初始化挂载机制

由于不同类型的设备，本质上用的都是这个抽象设备类实现，那么该如何将不同设备的不同回调实现逻辑对应起来呢？

自动挂载机制实现了这件事

​ CC_DEVICE_INIT_MOUNT（func,type） 这个宏的第一个参数，为设备的初始化回调，第二个参数为设备类型。他可以存储某个特定设备类的回调，具体这个存储的作用，后续会讲到，这边先看用例
例如这边，我注册了一个舵机设备，将初始化函数作为第一个参数，设备类型作为第二个参数。这样 我们就完成了舵机类型设备的挂载。

使用时**（注意这里的devices变量名字不能变）**只需要往数组里填入对应的设备类型即可，如果在外部初始化了硬件驱动的话，则直接改变第一个参数就行

这边，我们就已经完成了一个ID为1的舵机设备的初始化

4.3 相关API

4.3.1 abs_device

user_device_t cc_device_get(user_device_t devices, uint8_t device_type, uint8_t device_id);	获取设备
CC_DEVICE_INIT_MOUNT	设备类型初始化挂载

4.3.2 串口

用户其实不需要动这三个函数，打印调用日志接口，读取的话串口那边会发送消息队列

cc_println(format, …)	串口打印 带换行
cc_printf(format, …)	串口打印
cc_read()	串口读取

4.3.3 WiFi

初始化接口一般不需要用户手动用，会自动初始化的

int cc_wifi	WIFI初始化
int cc_get_wifi_state()	获取WIFI状态
int cc_wifi_disconnect()	WiFi断开连接

4.3.4 文件系统（基于Flash）

这是一个基于flash的文件系统，当需要持久化某些参数的时候，可以通过这个文件系统进行持久化的存储，掉电不丢失，利用键值对的方式进行存储

int cc_fs_set_string(const char* key, char *data);	根据键设置字符串
String cc_fs_get_string(const char* key);	根据键获取字符串
int cc_fs_set_bool(const char* key, int data);	根据键设置bool
int cc_fs_get_bool(const char* key);	根据键获取bool
int cc_fs_set_double(const char* key, double data);	根据键设置double
double cc_fs_get_double(const char* key);	根据键获取double
float cc_fs_get_float(const char* key);	根据键设置float
int cc_fs_set_float(const char* key, float data);	根据键获取float
int cc_fs_set_char(const char* key, char data);	根据键设置char
char cc_fs_get_char(const char* key);	根据键获取char
int cc_fs_set_uchar(const char* key, uint8_t data);	根据键设置unsigned char
uint8_t cc_fs_get_uchar(const char* key);	根据键获取unsigned char
int cc_fs_set_uint(const char* key, uint32_t data);	根据键设置unsigned int
uint32_t cc_fs_get_uint(const char* key);	根据键获取unsigned int
int cc_fs_set_bytes(const char* key, void *data, uint32_t len);	根据键设置bytes
int cc_fs_get_bytes(const char* key, void *data, uint32_t len);	根据键获取bytes
int cc_fs_remove_key(const char* key);	移除某个键
uint32_t cc_fs_get_free_size();	获取剩余大小
int cc_fs_clear();	清空