# e-calender

**Repository Path**: swxu/e-calender

## Basic Information

- **Project Name**: e-calender
- **Description**: 基于AB32VG1和RT-Thread的墨水屏日历
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 16
- **Forks**: 4
- **Created**: 2021-11-13
- **Last Updated**: 2025-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于AB32VG1的墨水屏智能日历



## 项目背景

本项目是【RT-Thread x RISC-V 应用创新大赛】参赛项目之一，大赛活动页面：

[RT-Thread X RISC-V 创新应用设计大赛 (elecfans.com)](http://www.elecfans.com/project/contest/2021RTThread/index.html)

本项目硬件部分包含4.2寸墨水屏、墨水屏驱动板、ESP8266模组和W25Q128闪存模组以及开发板自带的按键，硬件功能上使用了AB32芯片的SPI、UART、GPIO。软件部分包含业务代码、RT-Thread内核、RT-Thread组件包以及一些移植的三方组件，软件功能方面不仅使用了RT-Thread内核基础API（线程、信号量、互斥锁等），还使用了RT-Thtread组件库的at_device、netutils、webclient、cJSON、gbk2utf8、FlashDB、fal 组件。本项目实现了根据IP地址定位查询所在城市天气，从NTP服务器同步时间到片上RTC，最终在4.2寸墨水屏上显示当前日期、天气、温度、阳历、农历的效果。



> 作品上传内容应包含：
> 1.应用的背景，实现功能，开发板或RT-Thread使用情况概述，硬件框架，软件框架说明，软件模块说明，作品完整图片，视频演示效果，代码地址。
> 2.参赛者比赛项目代码须托管到Gitee（如无可上传到附件）。



## 项目简介

本项目解决了什么问题？

1. 传统纸质日历需要手动翻页，容易遗忘；
2. 传统纸质日历仅有静态信息，没有天气、时间等信息，内容较为单调；
3. 传统纸质日历一次购买后样式不能更换，比较无趣（不在乎的可以买新的）；



本项目有什么创新点（实现了哪些功能）？

1. 相比纸质日历，无需手动翻页；
2. 相比纸质日历，可以显示实时天气信息；
3. 相比LCD/OLED屏的同类产品，电子墨水屏的功耗更低，更节能环保；



## 硬件部分

本项目主要包括五个硬件模块：

1. AB32VG1开发板，作为主控制器控制其他外设；
2. ESP8266 WiFi模块，用于联网获取时间和实时天气信息；
3. 微雪的Arduino墨水屏扩展板，用于驱动墨水屏，同时带有一个128KB的SPI RAM芯片（用于作为显存），和一个T-Flash卡槽（没用到）；
3. 4.2英寸三色墨水屏，分辨率400x300，用于显示画面，一帧画面至少需要占用45KB 内存（400 x 300 x 3 / 8 = 45000）；
3. W25Q128闪存模块，容量16MB，用于存储中文字体，以及阳历和农历的对应关系；



### 硬件模块间连接

五个硬件模块之间的整体连接关系如下图：

![模块连接关系](https://gitee.com/swxu/e-calender/raw/master/pic/mod-con.png)





### 开发板引脚分配

开发板和外设的引脚连接关系（电源部分）：

![外设供电](https://gitee.com/swxu/e-calender/raw/master/pic/pow-sup.png)

主要使用到的资源，以及开发板和外设的引脚连接关系（控制部分）：

![引脚连接关系](https://gitee.com/swxu/e-calender/raw/master/pic/pin-map.png)

具体使用情况说明：

1. RTC
   * 用于保存当前时间和日期，以及时间的自动递增；
2. UART1
   * 连接ESP-01S模块，用于实现联网获取时间和实时天气信息；
3. SPI1
   * 连接墨水屏扩展板，用于和上面的SRAM芯片、墨水屏芯片通信；
4. GPIO
   * 连接墨水屏扩展板上的RAM_CS，用于输出SRAM的片选信号
   * 连接墨水屏扩展板上的EPD_CS，用于输出墨水屏的片选信号；
   * 连接墨水屏扩展板上的EPD_DC，用于输出墨水屏的数据/命令信号；
   * 连接墨水屏扩展板上的EPD_RST，用于输出墨水屏的复位信号；
   * 连接墨水屏扩展板上的EPD_BUSY，用于墨水屏的繁忙状态的输入；
   * 连接W25Q128模块的CS，用于输出闪存芯片的片选信号；
   * 开发板自带的三个按键，用于作为输入按键；
5. 3V3/GND
   * 连接ESP-01S模块，用于向ESP8266芯片供电；
   * 连接墨水屏扩展板，用于向SRAM和墨水屏供电；
   * 连接W25Q128模块，用于向闪存芯片供电；



## 软件部分

本项目的软件部分基于RT-Thread物联网操作系统，除了本项目开发的业务逻辑代码外，还使用了一些RT-Thread 内核API、一些RT-Thread软件包，以及一些三方组件，下面分别介绍。

主代码仓：https://gitee.com/swxu/e-calender.git （欢迎Star支持）

下载命令：`git clone --recursive https://gitee.com/swxu/e-calender.git `

部分组件通过git submodule引用了其他代码仓，具体见`.gitmodules`文件；



### 组件框图

软件各部分的组件框图如下：

![软件组件图](https://gitee.com/swxu/e-calender/raw/master/pic/sw-arch.png)



### 业务代码

本项目开发的业务代码位于`applications`目录下，具体文件功能如下（大部分是.c和.h两个文件）：

1. amap_location_api 高德定位和搜狐IP查询API对接；
2. amap_weather_api 高德天气预报API对接；
3. chinese_date_api 农历查询API对接；
4. flash_init.c 闪存分区挂载（依赖RT-Thread内核的fatfs支持）；
5. http_api_utils http工具函数；
6. hzk16 HZK16汉字字体相关接口；
7. hzk16_data HZK16汉字字体数据；
8. hzk16_setup 将HZK16字体安装到闪存分区；
9. key_task 按键扫描任务；
10. kvdb 封装了FlashDB里面的KVDB，更容易使用；
11. main.c 程序入口；
12. network_task 网络任务，用于处理网络请求（由于UART串口传输速度较慢，查询较慢，所以单独放在一个任务里面执行）；
13. time_utils 时间处理工具函数；
14. ui_consts UI常量；
15. ui_draw UI绘制，界面绘制逻辑单独放在了这里面；
16. ui_task UI任务，调用ui_draw实现相关功能；



### RT-Thread软件包

本项目使用到的RT-Thread软件包位于`packages`目录下：

1. bluetrum_sdk
   * RT-Thread Studio创建项目时自带，包含了二进制的`libhal.a`；
2. at_device
   * 提供ESP8266 AT命令构造和响应解析功能，实现联网；
   * **修改**：将所有sscanf都替换为atoi和strtol了（测试过程中间发现，每次send/recv会crash在sscanf里面）；
   * 修改后代码仓：https://gitee.com/swxu/at_device.git
3. netutils
   * 提供网络时间协议（NTP）的实现，实现从网络获取时间、设置时间；
4. webclient
   * 提供了超文本传输协议（HTTP）客户端的实现，用于天气查询请求的发送和接收；
5. cJSON
   * 一个轻量级的纯C实现的JSON字符串解析库，用于解析天气查询响应的JSON字符串；
6. FlashDB
   * 一个嵌入式数据库，提供了键值数据库（KVDB）和时序数据库（TSDB）两类API，同时提供了一些msh的测试命令；
   * **修改**：开启了DEBUG日志，bench命令中的KV测试次数改为100
   * 代码仓：https://gitee.com/swxu/FlashDB.git
7. fal
   * 闪存抽象层，FlashDB依赖的软件包，提供了闪存操作的封装和抽象，同时提供了一些msh的测试命令；
   * **修改**：添加了w25q128的移植文件；
   * 代码仓：https://gitee.com/swxu/fal.git
8. gbk2utf8
   * GBK和UTF8互相转换，HTTP API返回的汉字是UTF8编码的；



### 其他三方软件包

本项目使用到的其他三方软件均来自外设模块供应商，代码放在`board`目录下，包括：

1. epaper
   * 微雪墨水屏扩展板驱动软件包，来自微雪的[E-Paper_Shield]([E-Paper Shield - Waveshare Wiki](https://www.waveshare.net/wiki/E-Paper_Shield))页面；
   * **删除**了无用的代码，包括不是4.2寸屏幕的代码、以及SD卡驱动；
   * **修改**了GPIO相关的代码，改为用RT-Thread的pin驱动接口；
   * **修改**了SPI相关的代码，改为用重新实现的bsp_spi接口；
   * **添加**了基于RT-Thread finsh的墨水屏测试程序（绘制棋盘格、全屏填充、输出引脚测试），可以在shell模式下通过命令调用执行；
2. w25qxx
   * W25Q128 闪存驱动，来自微雪的[W25QXX DataFlash Board](https://www.waveshare.net/wiki/W25QXX_DataFlash_Board)页面；
   * **修改**了GPIO相关代码，改为使用RT-Thread的pin驱动接口；
   * **修改**了SPI相关代码，改为用重新实现的bsp_spi接口；
   * **添加**了基于RT-Thread msh的RAM测试程序（字模式、页模式、流模式），可以在shell模式下通过命令调用执行；

3. **重新实现**的bsp_spi.h和bsp_spi.c
   * 硬件SPI初始化，使用了greedyhao大佬提供的代码，参考[AB32VG1_DOC](https://gitee.com/bluetrum/AB32VG1_DOC)；
   * SPI接收和发送，使用了Bluetrum技术群中的SDK_AB53XX_V061_20190103.zip里面的相关代码；
   * greedyhao大佬提供的驱动，实现部分全部在libhal.a中，暂时不太好移植到RT-Thread驱动框架上；



## 效果展示

界面显示：

![主界面](pic/ui-month.png)



演示视频：

![演示视频](pic/ui-show.gif)

（这是原视频经过ffmpeg缩放、降低帧率后生成的gif图片，原始视频请戳这里：https://www.bilibili.com/video/BV1DP4y1H7UB/）



## 项目小结

这里是现阶段的项目小结，也是后续需要完善的地方：

1. 目前实现的界面功能还比较基础，只绘制了一个月历的界面，后续可以添加日历、周历的界面；
2. 目前WIFI热点名称和密码是通过env工具配置代码里面的Kconfig选型的，后续可以添加配网功能，参数配置可以考虑基于嵌入式HTTP服务器（例如webnet组件）开发，实现网页化配置，不用安装APP；
3. SPI驱动目前使用的不是RT-Thread驱动框架，这部分后续可以尝试实现一个基于RT-Thread硬件驱动（目前难点在于SPI初始化代码还没有可供参考的，寄存器文档上也没有SPI相关的说明），这部完成后，可以继续改进：
   * 重写epaper驱动SPI相关代码；
   * w25qxx驱动，直接使用RT-Thread的SFUD，直接配置即可；
   * fal也不需要新增适配代码，直接配置即可；



## 开发指南

对于部分想要**基于本项目进行二次开发**的朋友，有一些细节需要**注意**，下面分别介绍；



### 下载代码

下载命令：`git clone --recursive https://gitee.com/swxu/e-calender.git`

本项目代码仓使用了git submodule功能，使用`git clone`命令下载时需要带` --recursive`参数才能下载全部代码，网页端下载的zip包不包含子模块，编译会失败；



### 编译代码

编译命令：`scons -j 9`

本项目后期我是用`scons`命令编译的，RT-Thread Studio的工程文件`.cproject`，`.project`和`.settings`已经不是最新的了，不保证可以直接导入RT-Thread Studio成功，以及编译通过；



### 高德定位和天气服务

本项目使用了高德定位和高德天气服务，需要注意：

1. 需要注册高德开发者账号，并申请API Key之后才能使用相关功能；
2. API Key的Kconfig配置项位于菜单"Application config" -> "AMAP API config" 菜单下；
3. 由于在项目顶层Kconfig直接添加`source "applications/Kconfig"`选型后RT-Thread env工具打开会报错，因此`source "applications/Kconfig"`添加到了`board/Kconfig`文件中了；



### 农历查询服务

农历查询服务是基于Spring Boot和Redis搭建的tianapi.com的黄历服务的缓存版本，主要解决了：

1. tianapi允许的每日API调用次数太少的问题；
2. 移除了响应中目前设备端不需要的一些字段；

代码仓地址：https://gitee.com/swxu/wservice.git




### 硬件物料清单

本项目包含的物料清单如下（都可以直接淘宝买到）：

| 编号 | 物品名称                            | 价格  | 商家                      | 备注                           |
| ---- | ----------------------------------- | ----- | ------------------------- | ------------------------------ |
| 1    | AB32VG1开发板                       | 49    | 睿赛德科技                | 包邮                           |
| 2    | 4.2寸（红白黑）三色墨水屏           | 126   | WaveShare微雪电子         | 不包邮，邮费8元                |
| 3    | Arduino墨水屏驱动板                 | 48    | WaveShare微雪电子         | 带有一颗SPI SRAM芯片：23LC1024 |
| 4    | W25Q128闪存模组                     | 11.96 | telesky旗舰店/risym旗舰店 | 包邮                           |
| 5    | ESP-01S模组+烧录器                  | 17.5  | 佳信微数码专营店          | 满19.9包邮                     |
| 6    | 40P母对母杜邦线（10cm）             | 2     | 佳信微数码专营店          | 满19.9包邮                     |
| 7    | 40P公对母杜邦线（10cm）             | 3.3   | 佳信微数码专营店          | 满19.9包邮                     |
| 8    | 迷你逻辑分析仪（C口）+5条贴片测试钩 | 38    | Muse Lab                  | 不包邮，邮费3元                |

注：

1. 部分商品价格可能会有变动，上表仅为我购买时的不含邮费的价格；
2. ESP-01S烧录器不是必选，如果有其他USB-UART转接器也可以用；
   * 这个转换器也可以当USB-UART转接器用，
   * 标号是为了ESP-01S对应的，所以实际上TX是接收脚，RX是发送脚；
3. 逻辑分析仪不是必选项目，但是非常方便用来对SPI相关的问题进行调试；



### 接线注意事项

接线需要注意的细节有：

1. 因为微雪Arduino墨水屏驱动板和AB32VG1开发都是Arduino，AB32VG1开发板上Arduino UNO的步伐；
2. AB32VG1开发板上Arudino UNO针孔有几个位置的标号不对，需要对照电路图确认；
3. W25Q128模组的DI脚作为SPI的MOSI，DO脚作为SPI的MISO；
3. 最好有一块万用表，可以用于检查线路连通性；