#移远产品体验官#UniKnect Gen1 Pro 基于FreeRTOS的简易儿童学生手机V1

# 用 C 和 FreeRTOS 做一部 4G 小手机:STM32F413、EC200U、WouoUI 与掉电配置的完整实现

实机演示视频链接:
【#移远产品体验官#UniKnect Gen1 Pro#Based Student Microcontroller Phone】 https://www.bilibili.com/video/BV1xWH56zEtZ/?share_source=copy_web&vd_source=dba0456bc5c865c7161165c5b039107d

把屏幕点亮、向 4G 模组发送一条 AT 指令,并不难;让摇杆、页面动画、来电、信号查询和配置保存同时运行,而且互不干扰,才是这个项目真正要解决的问题。

本文以使用UniKnect Gen1 Pro 套件,在 STM32F413ZH 上用 C 语言和 FreeRTOS 实现一部带实体摇杆的 4G 小手机原型。重点放在各功能之间的数据流、任务分工、状态机和关键代码上。

本文源码基线为 **`1.2.1-privacy`**。文中的屏幕配图均由实际 C 绘制代码生成,使用离线测试夹具,**不是实体屏幕照片**

一、先明确这部“小手机”实现了什么
视频演示链接:
【#移远产品体验官#UniKnect Gen1 Pro#Based Student Microcontroller Phone】 https://www.bilibili.com/video/BV1xWH56zEtZ/?share_source=copy_web&vd_source=dba0456bc5c865c7161165c5b039107d

当前界面有五个顶层页面,左右推动摇杆循环切换:

数字时钟 → 家人联系 → 短信查看 → 信号参数 → 系统设置

| 功能 | 当前实现 | 主要代码 |

| — | — | — |

| 数字时钟 | 读取网络时间,在 MCU 内持续走时,显示北京时间 | `phone_time.c`、`phone_modem.c` |

| 家人联系 | 配置一个固定联系人,支持明确操作后的拨号、接听、拒接、挂断 | `phone_logic.c`、`voice_service.c` |

| 短信查看 | 空列表、列表、详情、中文换行与滚动已经实现;模组短信拉取尚未接入 | `phone_logic.c`、`ui_phone.c` |

| LTE 信号参数 | 查询 RSRP、SINR、RSRQ、RSSI、Band、Cell ID、运营商 | `signal_data.c`、`signal_service.c` |

| 系统设置 | 手动选择四方向显示,重新标定摇杆,保存后重启恢复 | `settings_service.c`、`settings_store.c` |

| 显示与输入 | WouoUI 动画、ST7735S 局部刷新、五向模拟摇杆 | `ui_display.c`、`lcd_st7735.c`、`joy_input.c` |

二、硬件连接:先把引脚所有权搞清楚

2.1 主控、通信和显示

项目使用以下组合:

- NUCLEO-F413ZH:STM32F413ZH,当前主频 100 MHz。

- QADP-EC200U:通过 USART6 与 STM32 交换 AT 指令和模组事件。

- ST7735S 屏盾:160×128,SPI1 输出 RGB565 像素。

- 五向模拟摇杆:通过电阻分压产生不同 ADC 档位,只占用一路模拟输入。

当前工程使用的接线如下,具体定义位于 `firmware/config/board_pins.h`:

| 功能 | STM32 引脚 | 配置 |

| — | — | — |

| LCD SCK / MOSI | PA5 / PA7 | SPI1 |

| LCD CS / DC | PD14 / PF12 | GPIO 输出 |

| 摇杆 | PC1 | ADC1_IN11,12 位采样 |

| 调试串口 TX / RX | PD8 / PD9 | USART3,115200,8N1 |

| 模组串口 TX / RX | PG14 / PG9 | USART6,115200,8N1 |

| 模组复位 | PD15 | 由板级层管理,不交给 LCD |

2. 2为什么第三方目录有 HAL,驱动却直接操作寄存器

当前 `firmware/CMakeLists.txt` 编译了 CMSIS 相关代码和项目自有驱动,没有把 ST HAL 驱动源文件加入当前固件。因此,LCD、ADC、UART 等底层主要通过寄存器实现。

例如,`board_pins.h` 中的引脚宏是 **0~15 的引脚编号**,不是位掩码

```c

#define LCD_CS_PIN 14

#define BOARD_PIN(n) (1u << (n))

```

配置 `MODER` 时用 `2 * pin` 计算位域位置,写 `BSRR` 时才使用 `BOARD_PIN(pin)`。混用编号和掩码,会把错误写入寄存器,即使程序可以正常编译。

三、整体架构:让控制、通信和绘制各自负责一件事

工程主体分为五层:

firmware/

├─ bsp/ 启动、时钟、中断、板级初始化、链接脚本

├─ config/ 引脚、功能开关、任务周期、FreeRTOS 配置

├─ drivers/ LCD、ADC、UART、Flash 等底层驱动

├─ osal/ qosa_* 接口到原生 FreeRTOS 的适配

├─ app/ 控制模型、输入、页面、通话、信号、设置服务

├─ fonts/ 中文点阵字库及来源说明

└─ third_party/ CMSIS、FreeRTOS、AT client、WouoUI 等

3.1 启动顺序为什么重要

`main.c` 的核心流程如下,省略了条件编译和日志:

```c

board_init();

settings_boot_init();

app_framework_start();

at_probe_start();

vTaskStartScheduler();

```

先完成板级初始化,再读取 Flash 设置,然后初始化消息通道、外设和应用任务,最后启动调度器。

其中 `settings_boot_init()` 位于调度器启动之前非常关键:配置扇区需要回收时,只在这个阶段擦除,避免运行中的显示和 AT 通信遭遇较长时间的 Flash 擦除停顿。

3.2 六个应用任务不等于系统总共只有六个任务

`app_runtime.c` 注册了以下六个默认启用的应用任务:

| 任务 | 优先级 | 栈深度,单位 word | 职责 |

| — | —: | —: | — |

| `control` | 4 | 1024 | 消费事件、推进业务状态、发布模型快照 |

| `input` | 3 | 768 | 5 ms 周期采样摇杆,处理标定 |

| `display` | 3 | 1024 | 组合页面、推进动画、刷新 LCD |

| `console` | 3 | 1536 | 串口命令和日志处理 |

| `health` | 5 | 768 | 任务心跳、剩余栈和异常监测 |

| `voice` | 4 | 1536 | 执行电话请求,维护实际呼叫状态 |

这里的 word 对当前 Cortex-M4 端口是 4 字节,例如 1024 words 对应 4096 字节。

工程还会启动 `at_probe` 通信查询任务,AT client 内部也有接收解析线程,FreeRTOS 本身有 Idle 和 Timer 等任务。因此,“六任务配置”指这张应用注册表默认启用的任务数。

应用注册任务使用 `xTaskCreateStatic()`,TCB 和栈为静态对象;AT 等组件仍可能动态分配。工程采用 `heap_4`,把 40 KiB 的 FreeRTOS 堆放到 SRAM2,显示缓冲等静态数据位于 SRAM1。不能因为应用任务静态创建,就把整个系统描述为没有动态内存。

四、事件与模型:页面不能直接操作模组

4.1 由控制任务统一修改业务模型

摇杆输入、串口命令、网络状态等会转成 `app_event_t`,进入深度为 24 的静态队列。`control` 任务持有业务模型,按顺序应用事件,再发布最新快照。

显示任务通过以下接口读取快照:

```c

void app_model_snapshot(app_model_t *m)

{

taskENTER_CRITICAL();

\*m = s_published;

taskEXIT_CRITICAL();

}

```

临界区只覆盖模型复制,绘图、串口发送和 AT 等待都在临界区之外执行。

这样的好处是,显示任务看到的是一份完整快照。不会出现列表数量已经更新,但列表内容还没更新的半成品状态。

4.2 普通事件与关键结果使用不同交付方式

共享事件队列是有容量上限的,`app_event_post()` 采用非阻塞发送,失败会增加丢弃计数。对于周期性采样,后续还有机会更新;对于“一次电话操作已经完成”这种结果,丢掉后可能导致界面永远停在等待状态。

因此,项目给通话、信号查询和标定结果设置了独立的结果保存机制。共同思路是:

```text

接受请求并分配非零 ID

    ↓

工作任务执行操作

    ↓

保存结果、请求 ID 和修订号

    ↓

控制任务读取并处理

    ↓

确认消费后释放本次请求

```

以通话服务为例,`s_delivery.result_id` 保存结果对应的请求。只有控制任务确认这个 ID 后,服务才解除占用。旧请求结果也不能清除新请求的等待状态。

这不能让所有输入事件都永不丢失,但能够把关键操作结果从共享队列容量中独立出来。

五、五向模拟摇杆:从 ADC 数值到一次可靠动作

5.1 电阻分压摇杆如何识别方向

五向模拟摇杆按下不同方向时,ADC 会停在不同电压平台。输入驱动读取 PC1 的 12 位结果,再交给 `joy_input_feed()` 分类。

默认配置使用工程中已有的档位,单位都是 12 位 ADC 原始值:

```c

c->idle = 4065;

const uint16_t values[] = {2046, 88, 3720, 737, 1308};

```

数组顺序为上、下、左、右、中。这些是本项目默认配置,不是所有同类摇杆都应该采用的固定值。重新标定成功后,会使用采集到的档位和标定时的显示方向。

分类器计算采样值与五个档位的距离,挑出最近值 `best` 和次近值 `second`,并进一步检查:

```c

if (best > (s->fixed_levels ? 180u : 80u) ||

second - best < 20u)

return JOY_NONE;

```

距离过远,说明可能不是已知档位;两个候选过于接近,说明当前采样存在歧义。两种情况都放弃判定,避免把中间电压猜成某个方向。

5.2 消抖之后,还需要“释放门”

输入任务周期为 5 ms,按下判定需要连续稳定采样达到 20 ms 对应的计数门槛。

如果只是每隔一段时间检查“当前是否按下”,持续推住摇杆就会不断换页。本项目的需求是:**按住只触发一次,完全释放后才允许下一次动作**。

因此状态机在确认按下后进入保持状态,之后即使仍能识别出方向,也不再发送按键事件;必须重新采集到稳定空闲值才解锁。

项目还专门处理了几种边界:

- 开机时先等待释放,防止上电前已经按住的方向触发动作。

- 按下过程中出现方向跳变,先要求释放,不直接跳到另一个按键。

- ADC 读取失败时清理消抖状态,并重新进入等待释放。

- 标定完成时仍要释放,避免最后一次中键又在新页面确认一次。

5.3 ADC 总线为什么要丢弃切换后的第一次转换

`adc_bus.c` 把 ADC 访问放在一个带递归互斥锁的接口中,按单通道转换使用 ADC1,并统一设置 480 cycles 的采样时间。

切换通道后,先转换一次并丢弃结果,再取下一次结果。这是针对该工程模拟输入串扰现象采取的处理方式。接口还给等待 EOC 的循环设置了上限,读取失败后返回错误,避免硬件异常把输入任务永久卡死。

5.4 旋转后的方向如何保持直观

屏幕旋转后,用户眼里的“上”可能已经不是标定时的“上”。所以配置中除了 ADC 档位,还保存 `calibration_rotation`。

`joy_screen_direction()` 根据以下差值查表变换方向:

```c

unsigned delta = (calibration_rotation - current_rotation) & 3u;

```

内部方向编码 0~3 对应 0°、90°、180°、270°。中键保持不变,四个方向按相对旋转映射。只保存五个 ADC 数值而不保存标定方向,会让旋转后的导航行为难以保持一致。

六、页面导航:页面、焦点和业务动作分开维护

6.1 屏幕分成三个区域

160×128 横屏时,布局固定为:

```text

┌──────────────────────────────┐

│ 日期、时分、LTE 信号 16 px│

├──────────────────────────────┤

│ │

│ 图标、时钟、列表或详情 92 px│

│ │

├─────────┬──────────┬─────────┤

│ 选择 │ 主界面 │ 返回 │ 20 px

└─────────┴──────────┴─────────┘

```

旋转为竖屏后,逻辑尺寸变为 128×160,顶部和底部仍保留对应区域,内容高度随之调整。

6.2 为什么一个 `page` 变量不够用

除了当前页面,`phone_state_t` 还维护顶层入口位置、内容选中行、底栏焦点、底栏索引、短信滚动位置、信号详情滚动位置及历史栈。

它们分别解决不同问题:

- 左右切换顶层入口,只改变入口位置,不不断压入返回历史。

- 下推进入底栏,默认选中“选择”;底栏左右到边缘停止。

- 底栏上推返回内容区,恢复原内容位置。

- “返回”恢复父页以及父页当时的选中行、滚动位置。

- “主界面”清空历史,回到数字时钟。

如果返回时只恢复 `page`,用户回到列表后往往会丢失原来的阅读位置。

6.3 一次“确认”何时才会拨号

家人联系入口的确认,只打开联系人列表;在联系人列表确认后,才会生成电话意图。

控制任务中的处理顺序可以概括为:

```text

物理按键 → 页面与焦点路由 → 设置动作处理

                     → 电话意图判断 → 普通模型事件

```

`phone_intent_from_key()` 会结合页面、通话状态、是否有请求处理中、导航是否锁定等条件,决定能否产生 `DIAL`、`ANSWER`、`REJECT`、`HANGUP`。

绘图代码只读取这些状态,**不提交电话请求、不修改页面焦点**。这样即使一个页面被重新绘制很多次,也不会重复拨号。

七、WouoUI 如何驱动彩色 LCD

7.1 复用绘图与动画模块,页面状态由项目维护

本项目实际编译并使用了 WouoUI 的三个模块:

```text

WouoUI_graph.c 基础绘图

WouoUI_font.c ASCII 字体

WouoUI_anim.c 整数非线性动画

```

页面布局、导航、中文显示、电话状态机属于项目自身代码。

显示链路如下:

```text

业务模型快照

↓

ui_phone.c:WouoUI 单色画布

↓

6×8 位图单元组成的 ui_frame_t

↓

ui_display.c:比较当前帧与已显示帧

↓

RGB565 framebuffer 中的变化区域

↓

lcd_flush_rect() → SPI1 + DMA → ST7735S

```

WouoUI 画布中的 1 表示墨色,最终转换成白底黑字的 RGB565 像素。因此,彩色 LCD 上也能使用单色 UI 的绘图和动画能力。

7.2 动画状态属于显示任务

`ui_animation_t` 分别保存横向切页、列表焦点、内容滚动三个动画位置。业务模型提供目标值,显示任务逐步追赶:

```c

WouoUI_Animation(&a->carousel, CFG_UI_EASE_MS,

             CFG_DISPLAY_MS, &finish);

WouoUI_Animation(&a->cursor, CFG_UI_EASE_MS,

             CFG_DISPLAY_MS, &finish);

WouoUI_Animation(&a->viewport, CFG_UI_SCROLL_EASE_MS,

             CFG_DISPLAY_MS, &finish);

```

当前调度周期为 22 ms,普通缓动参数为 96 ms,滚动参数为 72 ms。动画采用整数位置和误差累计,不需要每帧进行浮点插值。

当任务短暂延迟时,代码按已经经过的周期补推进动画,同时把单次补步限制为最多 8 步,避免积压很久后又长时间追赶旧动画。

八、6.25 MHz SPI 下,为什么还能有接近 40 FPS 的动画

8.1 先计算整屏传输的物理上限

160×128 的 RGB565 帧缓冲大小为:

```text

160 × 128 × 2 = 40960 bytes = 40 KiB

```

在 6.25 MHz SPI 下,仅像素数据的理论传输时间为:

```text

40960 × 8 / 6250000 ≈ 52.43 ms

```

还没计算命令、窗口设置、任务调度和绘图,整屏传输就已经超过 50 ms。因此,在这个 SPI 频率下,不可能靠每帧整屏发送实现 40 FPS。

项目中的高帧率来自 **只发送变化区域**,不是把全屏 RGB565 数据每秒传输了四十多次。

8.2 先比较 6×8 单元,再收缩到变化像素

`ui_frame_t` 把画面划分为 6×8 的单元。横屏需要 27 列、16 行,最右侧一列只显示有效的 4 个像素;竖屏最多使用 20 行。

`ui_flush_step()` 把新帧与 `s_shown` 逐格比较,生成脏区位图,并统计变化格数、连续区段数和总包围盒。

对于前后均为同色位图的单元,还会把每行位图进行异或,进一步找出真正变化的像素范围。也就是说,6×8 用来快速定位变化,最终传输窗口可以小于整格。

8.3 为什么脏区不能一律合并成一个大矩形

如果两小块变化分别位于左右边缘,直接取大包围盒,会把中间大量未变区域也发送出去;反过来,每个小块都单独设置窗口,又会产生过多命令和 DMA 启停开销。

项目使用了一个基于本机参数的选择条件,以下为源码条件:

```c

if (area <= 6144u && area <= count * 48u + runs * 256u) {

send_cells(frame, min_x, min_y,

           max_x - min_x + 1u, max_y - min_y + 1u,

           bounds);

/\* 成功后提交已显示缓存 \*/

}

```

其中 `count` 是脏单元数,一个单元有 48 个像素;`runs` 是连续变化区段数,乘以 256 的项是工程中的启发式合并权重,不是硬件寄存器参数。

6144 像素的纯数据线时间约为:

```text

6144 × 16 / 6250000 ≈ 15.73 ms

```

把合并窗口限制在这个量级,可以为 22 ms 周期中的组合绘制和其他任务留出余量。若不满足条件,则继续合并连续的横向脏单元,并将相同跨度向纵向扩展。

8.4 非整行矩形如何交给 DMA

RGB565 framebuffer 按物理屏幕宽度连续存储。全宽矩形可以直接发送对应内存;窄矩形的行尾有未使用数据,不能把它当作一整块连续像素直接 DMA。

`lcd_flush_rect()` 使用 `160×16` 个半字的传输缓冲,把窄矩形按最多 16 行打包:

```c

for (int i = 0; i < rows; ++i)

memcpy(&s_transfer\[i \* w\],

       &s_fb\[(size_t)(y + row + i) \* LCD_W + (size_t)x\],

       (size_t)w \* 2u);

bus_write16(s_transfer, (size_t)w * (size_t)rows);

```

整个矩形传输期间 CS 保持低电平,避免 ST7735 的连续像素写入过程被中途打断。

8.5 DMA 完成后为什么还要等待 SPI 不忙

LCD 发送采用 **DMA2 Stream3 Channel3**,UART 接收采用 **DMA2 Stream1 Channel5**,两者使用不同 DMA Stream。

LCD 数据阶段切换为 16 位 SPI 帧,DMA 完成中断通过信号量唤醒显示任务。接下来驱动还会等待 `TXE` 和 `BSY=0`,确认 SPI 完成最后的数据移出,再恢复 8 位命令传输模式。

DMA 计数归零只说明内存到外设的数据搬运结束,不能直接等同于总线最后一个比特已经发送完成。

DMA 等待期间显示任务会阻塞,其他任务可以得到 CPU。这里没有实现多帧排队或双 framebuffer 并行扫描;它依靠单一显示所有者、局部传输和任务调度保持秩序。

九、中文与长文本:把重复工作移出每一帧

9.1 字库放在 Flash 中

项目使用生成后的 C 点阵字库,包含 7382 个字形,采用二分查找;ASCII 占 6 像素宽,其他字形占 12 像素宽,字形高度为 12 像素。

字形表占用 191932 字节,常驻 Flash,不需要开机从 SD 卡加载。它是项目需要的中文子集,不是完整 Unicode 或完整 GB2312 字库,不支持的字符会显示替代方框。

字库来自 Fusion Pixel Font,工程保留来源、生成信息及 OFL 许可。普通构建直接编译已生成的 `phone_font.c`,无需再次下载字体。

9.2 128 项字形缓存

原始字形按行存储,而 WouoUI 更适合按列字节绘制。如果每帧都逐字逐像素转换,CPU 开销会被重复放大。

`ui_phone.c` 设置了 128 项字形缓存,把使用过的字形转置为列字节。再次绘制同一个字符时,直接把缓存字节合并到画布中,并处理裁剪边界。

这份缓存由显示任务独占,因此无需为每次字体查找再引入互斥锁。

9.3 长短信保存换行位置和局部栅格

长文本滚动时,变化的主要是视口位置,而不是正文内容。项目分别缓存:

1. 正文和当前行宽对应的换行偏移。

2. 最多 10 行、每行 14 像素的局部文本栅格。

3. 当前可见区域对应的像素偏移。

正文或行宽变化时重算换行;可视范围离开缓存范围时重建局部栅格;普通滚动帧直接从缓存提取像素。

十、AT 通信:循环 DMA、环形缓冲与解析线程

10.1 接收数据经过两级缓冲

`uart_at.c` 的接收链路为:

```text

USART6 RX

↓

512 B 循环 DMA 缓冲

↓ IDLE / 半传输 / 全传输中断

2048 B 环形缓冲

↓

AT client 接收解析线程

↓

命令响应 或 URC 回调

```

DMA 当前写入位置由剩余计数计算:

```c

uint16_t remaining = (uint16_t)DMA2_Stream1->NDTR;

uint16_t pos = (uint16_t)(AT_UART_DMA_SIZE - remaining);

```

驱动记住上一次搬运位置。如果新位置在旧位置之前,说明 DMA 发生了回绕,需要分两段复制。

IDLE 只是提示串口暂时空闲,不能替代 AT 协议解析。多行响应、URC 和命令完成标记仍由 AT client 识别。

10.2 为什么 IDLE 和 DMA 中断使用相同优先级

这两类中断都会调用 `drain_dma()`,修改同一个生产者游标。项目把它们配置为同一抢占优先级 5,避免同一搬运逻辑互相嵌套。

调用 FreeRTOS `FromISR` 接口的中断,还要遵守当前 `configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY=5` 的限制。这里的“数值更大”表示硬件中断优先级更低,与应用任务的优先级数字含义不同。

10.3 两级缓冲也有延迟上限

按 115200、8N1 估算,一字节约占 10 个线位,512 B DMA 缓冲的一半接收时间为:

```text

256 × 10 / 115200 ≈ 22.22 ms

```

因此,相关中断不能长期被屏蔽,环形缓冲消费者也必须跟得上。驱动记录 DMA 错误、迟服务、UART 溢出和环形缓冲丢弃计数,用实际计数判断系统健康。

10.4 如何复用现有 AT 服务

工程通过 `qosa_*` 适配层把 AT client 需要的线程、互斥锁、信号量和串口接口映射到原生 FreeRTOS。

信号、时钟和通话服务复用同一个 AT client。AT client 的命令互斥用于串行化请求,接收线程持续区分响应与 URC。服务层另外通过 `voice_service_busy()` 等判断,在通话忙时暂缓低优先级参数查询。

十一、真实通话:AT 返回值与呼叫状态是两回事
11.1 用户动作先变成电话意图

项目把拨号、接听、拒接、挂断定义为类型化意图,由 `voice_service_submit()` 提交。请求队列深度为 1,服务一次只允许一个请求占用。

每次成功接受请求,生成一个非零递增 ID。模型保存 `pending_id`,UI 用它显示等待状态;结果返回时必须匹配这个 ID。

真正执行电话指令的代码集中在 `voice_service.c`:

```c

switch (intent->kind) {

case PHONE_INTENT_DIAL:

rc = at_obj_exec_cmd(cli, r, "ATD%s;", intent->number);

break;

case PHONE_INTENT_ANSWER:

rc = at_obj_exec_cmd(cli, r, "ATA");

break;

case PHONE_INTENT_REJECT:

case PHONE_INTENT_HANGUP:

rc = at_obj_exec_cmd(cli, r, "AT+CHUP");

break;

}

```

这个示意保留了实际命令分支,省略了对象创建、默认分支和释放。普通上电不提交拨号意图,旧版自动电话探针默认不编译。

11.2 收到 `OK` 不立即把操作判为成功

网络呼叫是异步过程。命令得到 `OK` 后,实际电话可能仍在建立;命令超时时,也不能直接推断模组没有执行。

项目使用两条路径跟踪真实状态:

- URC:`^DSCI:`、`RING`、`+CLIP:`。

- 主动对账:`AT+CLCC`,检查当前实际通话记录。

URC 回调只做有界解析和非阻塞通知,不在回调中发起下一条 AT 指令。呼叫身份和完成判断由语音任务持有。通知队列没有处理完整时,周期性的 CLCC 对账提供恢复实际状态的机会。

11.3 呼叫身份需要 ID 和代次

项目内部维护 `IDLE`、`DIALING`、`ACTIVE`、`INCOMING`、`ENDED` 等状态,同时保存模组通话 ID 和本地 generation。

当出现新的一通电话时,generation 递增。接听或挂断意图带上目标 generation,防止旧页面的操作误作用于后来出现的新电话。

读取 CLCC 时,会遍历多条记录并匹配当前通话 ID;不会因为另一条记录排在前面就把它接管为主通话。`RING` 先到而号码或 ID 尚未到时,允许临时来电状态,之后再补齐身份。

11.4 命令等待与状态确认分别计时

当前代码中,拨号命令的响应等待上限为 15 秒,接听、挂断等为 5 秒。命令返回后,另设 7 秒实际状态确认期限。

这是两个阶段,不能把 7 秒写成用户操作的完整总超时;AT 互斥等待、命令等待等也会影响总耗时。

成功条件随意图不同而不同:

| 意图 | 状态确认条件 |

| — | — |

| 拨号 | 发现新代次的本机呼出,处于拨号或已接通状态 |

| 接听 | 目标代次进入 `ACTIVE` |

| 拒接、挂断 | 目标通话已经结束 |

拨号请求完成只说明拨号动作已被实际呼叫状态确认,**不等于对端已经接听**。通话计时以真实接通状态为依据。

每次显式拨号,包括用户手动重试前,都重新执行 CLCC 检查。遇到不确定结果时,不自动重发 `ATD`,避免上一条其实已经执行而造成重复动作。

11.5 通话可以继续,页面可以离开

拨号、接通、结束快照不会反复抢占导航。用户可以在通话中回时钟页或联系人页,电话模型继续维护状态;新来电则按来电优先规则显示。

这正是把“当前页面”和“当前通话”分开建模的价值:页面变化不等于挂断,绘图变化也不等于电话指令。

十二、信号参数页:一次刷新得到一组可阅读快照

12.1 数据从哪里来

参数页使用两条命令:

AT+QENG=“servingcell” 服务小区参数

AT+QSPN 运营商名称

解析字段包括 RSRP、RSRQ、RSSI、原始 SINR、Band 和 Cell ID;运营商名称按 SPN、短名称、完整名称的顺序选择,并处理工程覆盖到的 UCS2 与 UTF-8 字段。

解析器检查前缀、网络制式、字段数量、字段长度、整数范围和缺失标记。LTE 报文中的字段位置只用于当前支持的报文格式,不能无条件套用其他制式或模组。

每个指标都有有效位,部分字段无效时显示 `–`,不会把初始化的 0 误当成测量结果。参数页不执行邻区查询。

12.2 SINR 原始码如何转成 dB

本项目对所支持报文中的 SINR 原始码采用:

SINR_dB = (raw - 47) / 2

例如原始码为 116 时,显示为 34.5 dB。代码采用半 dB 整数保存,即 `raw - 47`,输出时再拆成整数和 `.0` 或 `.5`,并单独处理负号,防止 `-0.5` 被格式化成正数。

项目使用的有效原始码范围是 1~127。换算依据参见移远 [AT Commands Manual V1.1](https://quectel.com/content/uploads/2024/02/Quectel_EC200UEG91xUEG915G_Series-AT-Commands-Manual_V1.1.pdf) 中的 QCSQ 说明,以及 [QuecCell Application Note V1.3](https://quectel.com/content/uploads/2024/02/Quectel_EC200UEG91xU_Series_QuecCell_Application_Note_V1.3.pdf) 中的相关字段说明;两份文档范围描述存在版本差异,工程结合本机返回和交叉查询核对了换算。

12.3 为什么详情不跟着后台信号栏不停变

顶部信号栏需要周期性更新,详情页则需要保持可阅读。项目把两者分开:

- 后台网络状态更新只影响状态栏。

- 进入详情时请求一组参数。

- 中键或底栏“选择”手动刷新。

- 查询期间保留旧数据,完成后整体替换。

请求使用非零 ID,重复请求合并;结果保存在静态邮箱,直到控制任务消费。时间戳取整组查询完成时的共享时钟,表示完成时间,不代表两条命令在同一瞬间采样。
12.4 通话为什么会让参数查询暂缓

信号查询复用现有 `at_probe` 任务,通过任务通知唤醒,不为这个页面新增应用任务。每条参数查询的响应等待上限为 3000 ms。

服务在查询前、两条命令之间以及命令完成后检查通话忙状态。如果中途遇到来电,丢弃半组结果,恢复后重新采集整组,避免把不同阶段的数据拼成一份成功快照。

已经进入 AT 等待的命令不会因此瞬间撤销,所以“通话优先”仍受当前命令等待边界约束。

十三、网络时钟:UTC 锚点加单调运行时间

13.1 为什么选 `AT+QLTS=2`

项目查询 `AT+QLTS=2`,取得模组根据网络同步信息计算的当前本地时间,而不是把最后一次同步时刻直接当成现在。模式差异可参考移远 [QLTS 官方说明](https://quectel.com/content/uploads/2024/02/Quectel_EC200UEG91xUEG915G_Series-AT-Commands-Manual_V1.1.pdf)。

时区后缀的单位是 15 分钟。例如 `+32` 对应 UTC+8:

32 × 15 分钟 = 8 小时

`phone_modem_clock()` 校验年月日、时分秒、时区和尾部字符后,把网络本地时间换成 UTC;UI 显示时再统一转成北京时间。

13.2 不需要每秒发 AT 命令

软件时钟保存两个核心值:

utc 校时时刻对应的 UTC 秒

anchor_ms 校时发生时的系统累计运行毫秒

读时钟时使用:

```c

uint64_t utc = (uint64_t)c->utc + (now - c->anchor_ms) / 1000u;

```

因此,秒钟变化由本地运行时间推进,网络查询只负责校准。控制任务使用无符号 Tick 差累计到 64 位运行时间,也为持续运行处理 Tick 回绕提供基础。

顶部时分和中央时分秒使用同一次页面时钟快照,避免跨分钟时出现两处显示暂时不一致。网络时间无效时显示占位,不构造一个看起来正常的假时间。

工程还支持主机手动校时;手动设置在本次启动期间优先,后续模组读数不会直接覆盖它。当前持久化配置保存的是显示方向和摇杆标定,不能认为软件时钟也随之保存。

十四、系统设置:RAM 中生效和 Flash 已保存是两个状态

14.1 显示方向立即生效,保存异步进行

方向列表提供 0°、90°、180°、270°。确认后先更新运行时方向,再提出保存请求。模型分别保存 desired 和 saved 配置,用来表达“当前想要保存的值”与“已经写入成功的值”。

这样可以明确显示:

- 保存中。

- 通话期间待保存。

- 已生效未保存。

- 空间已满,需要重启后重新设置。

14.2 标定状态由输入任务独占

标定开始时,输入任务备份原分类器,依次采集空闲和上、下、左、右、中键档位;步骤之间必须释放。每个档位都检查稳定性和相互间距。

成功后将结果交给控制任务校验,再请求保存;取消、来电中断或 **60 秒没有步骤进展** 时恢复旧标定。这里的 60 秒是无进展期限,不是整个向导固定只能运行 60 秒。

标定期间导航被锁定,避免采样动作同时触发页面切换。完成结果也通过带请求 ID 的保留机制交付,并覆盖了“输入任务已经成功、控制任务还未接受时恰好来电”的竞态处理。

十五、Flash 掉电保存:双扇区追加日志如何实现

15.1 先给应用和配置划出硬边界

STM32F413ZH 的本项目链接布局如下:

| 区域 | 地址范围 | 大小 | 用途 |

| — | — | —: | — |

| 应用 Flash | `0x08000000~0x0813FFFF` | 1280 KiB | 程序、常量、字库、初始化数据镜像 |

| 配置扇区 A | `0x08140000~0x0815FFFF` | 128 KiB | 配置日志 |

| 配置扇区 B | `0x08160000~0x0817FFFF` | 128 KiB | 配置日志 |

应用链接长度已经减去末尾的配置空间,并添加了镜像重叠断言。构建工具还会检查 ELF 下载段,烧录脚本拒绝跨入配置区的应用镜像。

配置区没有被打包成普通固件下载内容,正常应用升级保留它;整片擦除仍会清掉配置,因此不能把“升级保留”理解为任何烧录方式都能保留。

15.2 一条完整配置记录只有 64 字节

`settings_store.c` 使用 16 个 32 位 word,布局为:

| word 下标 | 内容 |

| — | — |

| 0 | Magic:`0x554B5331` |

| 1 | 格式版本,当前为 1 |

| 2 | 非零递增序号 |

| 3 | 显示方向、标定方向、手动标定标志 |

| 4~6 | 空闲值和五个按键档位,按 16 位打包 |

| 7~13 | 当前置零的保留字段 |

| 14 | 前 56 字节的 CRC32 |

| 15 | 提交标记:`0x43544D31` |

每条记录保存完整配置,启动时不需要把多条局部修改重新拼起来。

15.3 提交标记为什么最后写

运行时按顺序每轮最多写入一个 32 位字。每次写之前确认目标仍处于擦除态,写后读回核对;驱动刷新 Flash 数据缓存,避免读到缓存旧值。

只有前面 15 个字都写入完毕,最后才写提交标记。启动扫描要求同时满足:Magic 正确、版本支持、序号有效、提交字正确、CRC 正确、参数校验通过。
如果在正文写入期间掉电,提交字不成立,该记录不会被当成有效配置;上一条完整记录仍可恢复。即使记录已提交,CRC 和参数检查也仍然会执行。

这是软件上对中断写入的容错设计,不表示能够消除所有供电异常或 Flash 硬件故障。

15.4 两个扇区如何轮换

每个 128 KiB 扇区可容纳:

```text

131072 / 64 = 2048 条记录

```

启动扫描两个扇区,选择最新有效记录,并记录各自已经使用到的位置。即使遇到不完整记录,也跳过该位置,避免在写过的地址上重新覆盖。

已有有效配置时,启动回收只擦除另一扇区,保留包含最新配置的扇区。运行阶段向当前扇区追加,当前扇区满后切换到另一个有空位的扇区;两个都满时报告空间耗尽,不在实时任务里直接擦除。

因此,两扇区的 4096 条物理槽位不等于任意运行状态都还能再保存 4096 次,实际剩余数量取决于启动回收和已用位置。

序号比较使用:

```c

(int32_t)(candidate_sequence - current_sequence) > 0

```

它利用差值处理本项目有限日志跨度内的序号回绕,并跳过 0 这个保留值。其前提是参与比较的新旧序号距离小于半个 32 位序号空间。

15.5 “分步写入”不等于底层完全不阻塞

`settings_store_step()` 每次只写一个字,减少单轮工作量;底层 Flash 编程仍需要短暂屏蔽中断、等待硬件完成。这是受限的小步同步操作,而不是 DMA 异步写入。

擦除只允许发生在调度器未启动时;通话期间保存步骤暂缓。二者共同避免把较重的存储工作放进通信繁忙时段。

十六、性能与验证:把数字和它的适用范围一起写出来

16.1 22 ms 调度不等于每秒完成 45.45 帧

`1000 / 22 ≈ 45.45 Hz` 是目标调度节奏。实际帧率还受页面组合、脏区大小、SPI 传输和调度干扰影响。

显示任务使用 `vTaskDelayUntil()` 把本轮绘图和传输时间计入周期。超期后重置节拍并让出 CPU,不在已经超时的一帧后再额外等待完整 22 ms。

帧率计数只在有变化且传输成功时增加。无变化循环不计动画帧,旋转、初始化和普通整页首次加载也不混入交互动画统计。
16.2 1.2.0 的实际性能记录

下面引用 `1.2.0-settings` 的实板验收,每个场景连续采集不少于 60 秒,同时检查连续五秒窗口和滑动窗口,表中取较低完成帧率。SPI 为 6.25 MHz,LTE 服务运行,SD 关闭。

| 场景 | 方向 | 最低完成 FPS | 最长帧间隔 | 达到 40 FPS |

| — | —: | —: | —: | — |

| 五页横滑 | 0° | 44.0 | 51 ms | 是 |

| 短信列表焦点 | 0° | 45.2 | 35 ms | 是 |

| 长短信滚动 | 0° | 39.8 | 47 ms | 否 |

| 设置方向列表 | 0° | 44.6 | 44 ms | 是 |

| 设置方向列表 | 90° | 44.6 | 45 ms | 是 |

| 设置方向列表 | 180° | 44.6 | 44 ms | 是 |

| 设置方向列表 | 270° | 44.8 | 44 ms | 是 |

16.3 软件回归覆盖什么

公开源码 `1.2.1-privacy` 的交付记录包含:

- 19 组 ARM 仿真测试,包含空联系人、通话服务、信号、导航、设置与绘图等。

- 17 项 Python 工具测试。

- 默认、离线、LCD 诊断三种构建及 ELF/BSP 检查。

- 正常配置实际链接的 FreeRTOS 集成检查。

- 第三方源码与字体内容锁定校验。

- 四方向实际 C 渲染预览,以及联系人隐私页面检查。

ARM 测试将实际 C 代码编译为 ARM 指令,在 Unicorn 中运行,并在硬件或时间边界注入测试替身。它能够验证状态转换和故障路径,但不能替代实体屏幕电气时序、射频行为或真实音频验收。

绘图测试还会比较四方向下的局部刷新和完整绘制结果,检查像素一致性,避免只优化了速度却留下旧光标、漏行或裁剪越界。

十七、如何构建、配置联系人并调试

17.1 准备环境

当前验证环境为 Windows、Python 3.13、ARM GNU Toolchain 13.3.rel1;烧录使用 STM32CubeProgrammer。新机器先建立虚拟环境并安装锁定依赖:

```powershell

py -3.13 -m venv .venv

.venv/Scripts/python.exe -m pip install -r tools/requirements.lock.txt -r tests/requirements.txt

```

工具链可以放在 `tools/arm-gnu-toolchain/`,或通过 `ARM_GCC_ROOT` 指向本机安装目录。不要把示例机器路径直接当成自己的安装路径。

17.2 联系号码只放在本地配置

```powershell

if (-not (Test-Path firmware/config/phone_number.local.h)) {

Copy-Item firmware/config/phone_number.example.h firmware/config/phone_number.local.h

}

```

编辑本地头文件中的 `CFG_GUARDIAN_PHONE_NUMBER`,填写自己的联系号码。这个文件已加入 Git 忽略规则。

未配置号码仍然可以构建,联系人列表显示“暂无联系人”,固定联系人拨号不可用。配置后,列表及匹配的家庭通话页面显示“家人1”;号码匹配处理了本项目覆盖的 `+86`、`0086` 等形式。

**界面隐藏号码不等于固件中没有号码。** 宏展开后号码仍进入固件,所以含真实号码的 ELF、BIN、HEX、完整 Flash 备份和原始日志都不能作为公开发布材料。公开发布包应使用空联系人构建。

17.3 编译和烧录
在工程根目录执行:

```powershell

# 普通构建

.venv/Scripts/python.exe tools/build.py

# 不启动模组服务的离线构建

.venv/Scripts/python.exe tools/build.py --no-modem

# 屏幕诊断构建

.venv/Scripts/python.exe tools/build.py --lcd-diagnostic

# 连接正确的 ST-LINK,确认无活动电话后再烧录

.venv/Scripts/python.exe tools/build.py --flash

# 查看控制台,COM3 按本机实际端口修改

.venv/Scripts/python.exe tools/monitor.py -p COM3 -t 10

```

普通应用升级保留配置区,不进行整片擦除。首次替换原固件前应保留自己的原始镜像,调试串口同一时间只由一个进程打开。

17.4 先看状态,再看页面

常用控制台命令包括:

```text

help

status

tasks

page home

page contacts

page signalinfo

signal status

signal refresh

page settingsmenu

settings status

joy calibrate

joy cancel

lcd profile dma3

lcd profile gpio

```

`status` 用于检查网络、页面、通话、显示与丢弃计数;`tasks` 关注任务是否超时、剩余栈是否足够。任务心跳有各自期限和启动宽限,不能只看设备是否还在输出串口文字。

`joy calibrate` 会启动实际标定。串口 `rotate` 用于临时旋转诊断,不修改持久化方向;需要保存时应通过系统设置页确认。

显式电话诊断命令会影响真实电话,日常导航测试使用方向、确认和返回命令即可。本文构建与预览命令不需要自动拨打电话。

本项目参考链接: [WouoUI-PageVersion]( GitHub - Sheep118/WouoUI-PageVersion: 这是一个灵感源自WouoUI的纯C语言(C99标准),无依赖库(只需要C的标准库),适用于多种不同大小屏幕,极易部署的代码框架,可以快速构建、开发一个丝滑、Q弹的单色屏UI。 · GitHub )、[Fusion Pixel Font]( GitHub - TakWolf/fusion-pixel-font: 开源的泛拉丁与泛中日韩像素字体,黑体风格 · GitHub )、[FreeRTOS Kernel]( GitHub - FreeRTOS/FreeRTOS-Kernel: FreeRTOS kernel files only, submoduled into https://github.com/FreeRTOS/FreeRTOS and various other repos. · GitHub )、[移远 AT 指令手册](https://quectel.com/content/uploads/2024/02/Quectel_EC200UEG91xUEG915G_Series-AT-Commands-Manual_V1.1.pdf)、[移远 QuecCell 应用说明](https://quectel.com/content/uploads/2024/02/Quectel_EC200UEG91xU_Series_QuecCell_Application_Note_V1.3.pdf)。

干货满满,感谢大佬分享 :hand_with_index_finger_and_thumb_crossed: