本项目基于ESP32以及Platformio平台开发,请自行查阅如何配置这个环境
开源gitee地址:cc_smart_device
如果愿意贡献项目or提出疑问和修改的,请在gitee上提issue
项目里的mqtt服务器是公共的 请大家最好换成私有的 否则容易收到其他用户的错误数据
文章目录
- 1 基本介绍
- 2 基本架构
- 3 中间件
- 3.1 RTOS部分
- 3.1.1 互斥锁
- 3.1.2 信号量
- 3.1.3 消息队列
- 3.1.4 软件定时器
- 3.1.5 线程
- 3.1.5.1自动初始化机制
- 3.1.6 内存分配与回收
- 3.1.7 条件变量
- 3.1.8 内存池
- 3.2 日志接口
- 3.3 Shell命令行
- 3.3.1 简单介绍
- 3.3.2 常用命令介绍
- 3.4 Msg消息层
- 3.4.1 msg
- 3.4.2 mqtt
- 3.4.3 device_msg
- 4 设备
- 4.1 简介
- 4.2 设备初始化挂载机制
- 4.3 相关API
- 4.3.1 abs_device
- 4.3.2 串口
- 4.3.3 WiFi
- 4.3.4 文件系统(基于Flash)
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(); | 清空 |