Course Outline

Linux 嵌入式实践课 · 荔枝派 4A + RuyiSDK + C 语言 · 顺序学完六章 · 每章讲义 + 本章实验（讲义把概念在首次出现处讲透；实验接线/写代码验收）· 最后做综合项目（量化本地模型 + 终端 DeepSeek Harness + 荔枝派三线程）

ch01

环境与工具链

RuyiSDK、烧录、交叉编译、CoreMark

ch02

够用的 C 语言基础

读懂、改得动本课代码

ch03

GPIO 与执行器

gpiod 控继电器/风扇；模拟温度控制

ch04

命令对话与温控

真 DHT22；SSH 打字查状态、改阈值

ch05

网络与 MQTT

电脑终端远程控灯；板子上报状态

ch06

线程与协同

采集 / 控制 / 通信三条线一起跑

本章实验

上板通道验收

CoreMark 交叉编译上板跑分

本章实验

写滞回 · 改读数

从空写出决策；再改读数坑（不上板）

本章实验

继电器控制风扇

自己写三函数；模拟温度驱动真风扇

本章实验

命令温控（cmd_thermo）

接 DHT22；补命令与 select；SSH 联调

本章实验

MQTT 远程控灯

电脑终端控外接 LED；板子上报状态；抓包看一层层包装

本章实验

三线程协同

三条线同时跑；先看抢数据翻车，再加锁修好

综合项目

端侧 Agent 环境终端

荔枝派三线程继续滞回；K3 跑量化模型；终端里用 DeepSeek Harness 打字调 MQTT 工具

基础篇外设篇 Linux 应用篇本章实验综合大项目

讲义与本章实验

文档	解决什么问题	学生要交出什么
讲义（lecture）	零件是什么、接口怎么用；概念在首次出现处讲透；带跟做小例子	跟做后单项能力会了，例如 `gpioset` 控继电器、能解释 `select`
本章实验（lab）	用本章零件做完整验收；给 C 脚手架 + 契约 + 验收标准	能演示约定现象（如风扇开/关、敲 status 有回复），并填记录表

讲义 → 同章实验 → 下一章讲义；底栏有「上一篇 / 下一篇」。
实验写差量步骤与验收；安装 / make / scp 等基础操作以讲义为准。
同一故事线递进：ch02 软件模拟温度 → ch03 模拟温度+真风扇 → ch04 真传感+命令对话。

术语表

读章节总览前可先扫一眼；各章细则表内仍有章节专属名词。每个词用一句话说清「它是什么」。

术语	说明
荔枝派 4A	本课用的 RISC-V 开发板；板上已跑 Linux，用 SSH 或串口连上去写程序。
RuyiSDK / ruyi	如意课题组的 RISC-V 开发工具入口：装交叉编译器、系统镜像、查板卡支持列表。
交叉编译	在电脑上编出只能在开发板上跑的程序，再拷到板子上运行。
SSH / SCP / 串口	SSH：远程登录板子敲命令。SCP：把文件拷到板子。串口：USB 线连上后的「聊天线」黑窗口，打字板子能看见。
CoreMark	测板子算力的小程序。ch01 实验：交叉编译后上板跑出分数并记录。
GPIO	板子上一排针脚。本课主要写输出（继电器信号端）；也可读输入（传感器数据线）。
gpiod	Linux 上读写 GPIO 的常用接口库；ch03 用它控风扇继电器。
MMIO	把硬件寄存器当成内存地址来读写。Linux 里内核管着这些地址；用户程序经 `gpiod` 间接访问。ch03 用只读方式核对某一位翻转。
devmem	按地址读/写内存的小工具。ch03 只读：改 GPIO 电平前后各读一次，看到对应位翻转。
DHT22	温湿度探头。数据线经电平转换接 GPIO；ch04 起用，综合项目由 Agent 工具读取。
TXS / AMS1117	TXS0108E：1.8 V↔3.3 V 双向电平转换。AMS1117-1.8V：给 TXS 低压侧（VA）供电。ch04 接 DHT22 时用。
继电器	用小信号开关大电流的模块。板子 GPIO 驱动继电器，继电器再给风扇通断电。ch03 起用。
阈值 / 滞回	高于上限开、低于下限关，中间保持。ch02 在软件里练；ch03 接到真风扇；ch04 可用 `set` 现场改温度上下限。
终端命令	在 SSH 窗口打字，程序认命令。例：`status` 查状态，`set temp 30` 改温度 bar。工程目录 `chapters/ch04/code/`。
select	让程序同时盯几个输入源。ch04：一边等采样周期到，一边等你在 SSH 里打字。
MQTT	物联网发消息的方式。电脑终端和板子都连一个「中转站」，按主题名收发文字（如主题 `home/led` 发 `on`）。
Broker	MQTT 的中转站。常用软件叫 Mosquitto，可跑在电脑或板子上。
发布 / 订阅	发布＝往某主题发一条消息；订阅＝盯着某主题收消息。ch05：电脑终端下行控外接 LED；板子上行发布状态。
tcpdump	抓网络包的工具。ch05：抓一条 MQTT 发布，亲眼看到消息被一层层包起来发出去。
外接 LED	远程控制用的灯。ch05：电脑终端发 MQTT 命令，板子驱动这盏灯。
DeepSeek Harness	Agent 运行时（`dsh`）。会话、工具、模型、界面都是插件。本课在终端里打字对话，像 Claude Code；不把网页当主入口。
pthread / 多线程	一个程序里同时跑多段逻辑。ch06 三线程：采集 ∥ 控制 ∥ 通信(MQTT)。
竞态	两条线同时改同一份数据，结果写乱。ch06：先故意不加锁看数据错乱，再加锁修好。
ThreadSanitizer	编译时加上 `-fsanitize=thread` 的检查器。ch06：在电脑上编同一个抢数据小程序，终端打印哪两行在抢同一变量。
llama.cpp / GGUF	C++ 本地推理栈。量化得到 `.gguf`；K3 上用带 IME2 的 `llama-server` 提供 OpenAI 兼容 HTTP。
量化	把较高精度权重量成更少比特（本课至少 Q4）。学生自己压，记下体积，并确认工具调用仍在。
模型供应商	Harness 里的脑子来源。本地填 K3 的 `llama-server` 地址，云端填 DeepSeek API。同一套工具，只换 `baseURL`。
端侧 Agent 环境终端	本课综合大项目：荔枝派三线程滞回一直转；人在终端 Harness 里打字；工具经 MQTT 动手；本地量化模型与云端 DeepSeek 可替换。

物料清单

自备电脑，用 SSH 连荔枝派 4A。MQTT 中转站（Mosquitto）从 ch05 起跑在电脑或板子上。

物料	说明	提供方
个人电脑	联网；装 `ruyi` 与交叉工具链；SSH 连板；ch05 起装 Mosquitto；ch06 跑 ThreadSanitizer；综合项目在主机上做 `llama-quantize`	学生自备
荔枝派 4A	本课开发板；兼容 RuyiSDK（见 support-matrix）；含电源、网线；板载 LED 与按键	课程提供
USB 转串口线	可选：烧录/排障时的串口登录（日常开发以 SSH 为主；ch04 命令也走 SSH stdin）	课程提供
面包板 + 杜邦线	外设接线	课程提供
风扇 + 继电器模块	GPIO 控继电器，继电器给风扇通断电；ch03 模拟温度控制；综合项目里滞回继续跑，也可由 Agent 工具改行为	课程提供
DHT22 温湿度探头	经 TXS 接 GPIO 读温湿度；ch04 起用，综合项目由 `read_status` 读到	课程提供
TXS0108E + AMS1117-1.8V	电平转换与低压侧供电；ch04 接 DHT22 数据线时用	课程提供
外接 LED 模块	ch05 MQTT 远程控灯	课程提供
进迭 K3	综合项目的脑：跑加速版 llama.cpp 与终端 DeepSeek Harness。内存建议 16 GB 起。	课程提供

章节总览

每章一行；「验收现象」与「本章实验」对照看。综合项目单独列出。

章	模块	名称	本章目标	本章实验	验收现象	章节成果
ch01	基础篇	环境与工具链	装好 RuyiSDK；会烧录与通道；会交叉编译；CoreMark 上板跑分	上板通道验收	CoreMark 交叉编译 → SCP 上板 → 跑出分数并记录；SSH / `uname` / 工具链三元组自证	开发通道与可部署工程
ch02	基础篇	够用的 C 语言基础	读懂、改得动，并能按契约写出函数	写滞回 · 改读数	从空写出 `thermo_decide`；修好 `thermo_read` 的指针与失败路径（软件、不上板）	具备继续做外设实验的语言基础
ch03	外设篇	GPIO 与执行器	会用 `gpiod` 控针脚；理解寄存器与 API；模拟温度驱动真继电器/风扇	继电器控制风扇	自己写三函数后：超阈值风扇转、降温停；可选 `devmem` 只读核对位翻转	外设能力 + 模拟温度控制
ch04	Linux 应用篇	命令对话与温控	接 DHT22；命令表 `status`/`set`；`select` 边采样边听 SSH 打字	命令温控（cmd_thermo）	自动控温同时，敲 `status` 有回复、敲 `set` 阈值立刻变	可对话的本地温控程序
ch05	Linux 应用篇	网络通信与 MQTT	三个实验：on/off 解析 → 虚拟灯命令环 → MQTT 远程控灯；tcpdump 看分层	三个实验（主实验：MQTT 远程控灯）	电脑终端控外接 LED；板子状态在订阅端可见；抓包能指出 MQTT 落在哪一层	可复用 MQTT 模块（下行控灯 + 上行状态）
ch06	Linux 应用篇	线程与任务协同	三个实验：race-demo+TSan → 成对快照加锁 → 三线程协同；共享状态加锁；Ctrl+C 干净停	三个实验（主实验：三线程协同）	三线同时跑；风扇按阈值；MQTT 通信线工作；`[RACE]` 无锁必现、加锁消失；TSan 报告；Ctrl+C 关风扇后退出	三线程骨架（供综合复用）
综合	综合大项目	端侧 Agent 环境终端	复用 ch06 三线程；量化本地模型；终端 DeepSeek Harness 打字调 MQTT 工具；本地与云端同一接口	见 project.html	滞回无人值守仍转；终端打字能读状态、动风扇/灯；换 `baseURL` 后工具不变	可答辩作品

章节细则

每章讲义按节推进（常见 x.1–x.3）；概念在首次出现处讲透。「本章实验」单独验收。实验给 C 脚手架，学生按契约补全或改 bug，结合板上看现象（ch02 可不上板）。最右栏为本名词。

章节	模块	章节目录	本章目标	本章实验	章节成果	名词解释
ch01	基础篇	1.1 荔枝派 4A 与 RuyiSDK 环境	环境通、工具链通、CoreMark 上板跑分	上板通道验收：交叉编译 CoreMark、SCP 上板跑出分数并记录；自证 SSH / `uname` / 工具链三元组；烧录可手工完成	最小可部署闭环	RuyiSDK / ruyi 装工具链与镜像的入口。交叉编译电脑上编出板子可执行文件。 SSH / SCP / 串口远程登录、拷文件、调试聊天线。深入理解电脑与荔枝派 4A 指令集不同，交叉工具链如何让程序在板子上跑起来。
		1.2 烧录、开发通道与一键准备/一键编译
		1.3 交叉编译、Makefile 与 CoreMark
		深入理解：电脑与荔枝派 4A 指令集不同，交叉工具链如何让程序在板子上跑
ch02	基础篇	2.1 类型、变量、控制流	读懂、改得动，并能按契约写出函数	写滞回 · 改读数：从空实现 `thermo_decide`；修好 `thermo_read` 的空指针与读失败	语言门槛过关	指针能看懂函数参数里的指针用法。结构体把一组相关数据捆在一起。头文件声明接口，供多个 .c 共用。深入理解多个 .c 如何编译、链接成一个可执行文件；`main` 之前发生了什么。
		2.2 函数、头文件与多文件工程
		2.3 指针、数组、结构体
		深入理解：多个 .c 如何编译链接成可执行文件；main 之前发生了什么
ch03	外设篇	3.1 外设与 I/O	会用 gpiod 控继电器；模拟温度驱动真风扇；可选只读核对寄存器位	继电器控制风扇：接线；学生实现 `line_request` / `fan_set` / `fan_decide`；模拟温度控制；改阈值验收	外设能力 + 模拟温度控制	GPIO / gpiod 针脚与用户态读写接口。继电器 GPIO 控信号端，触点驱动风扇。滞回高低两档阈值，中间保持。 devmem（只读）核对 set_value 后寄存器位是否翻转。
		3.2 GPIO：用 gpiod 控继电器与风扇
		3.3 决策 → 执行（模拟温度）
ch04	Linux 应用篇	4.1 串口是聊天线：字节怎么进出	接 DHT22；命令表；select 边采样边听 SSH 打字	命令温控（cmd_thermo）：焊 TXS、接线；学生实现 `status`/`set`/dispatch/`select` 主循环	可对话的本地温控	DHT22 / TXS 真温湿度；数据线经电平转换。命令表字符串对应函数，如 `status`。 select 同时等采样超时与 stdin 输入。 SSH stdin 本课命令入口；不要求另接物理串口线。
		4.2 接传感器与命令表
		4.3 两边同时工作（select）
ch05	Linux 应用篇	5.1 联网发消息：Broker、主题、发布订阅	电脑终端远程控外接 LED；板子发布状态；tcpdump 看分层包装	三个实验：① on/off 精确解析 ② 虚拟灯命令环 ③ MQTT 远程控灯（真 GPIO+Broker）；联调与 tcpdump 抓 publish	可复用 MQTT：下行控灯 + 上行状态	Broker 消息中转站（Mosquitto）。主题频道名；发布往这发，订阅盯这听。 payload 消息正文，如 `on`/`off`。深入理解用 tcpdump 抓一条发布，看 MQTT → TCP → IP 一层层包装。
		5.2 下行：订阅命令，驱动外接 LED
		5.3 上行：publish 状态
		深入理解：用 tcpdump 抓一条 publish，看 MQTT→TCP→IP 分层包装
ch06	Linux 应用篇	6.1 从单线程过渡到多线程	三线程骨架；共享状态加锁；竞态必现并修好；干净停	三个实验：① race-demo+TSan ② snapshot-lock 成对快照加锁 ③ 三线程协同（主实验：无锁 `[RACE]`→加锁、`USE_LOCK`、MQTT、Ctrl+C 干净停）	三线程骨架（供综合复用）	三线程采集 ∥ 控制 ∥ 通信(MQTT)。锁同一时刻只许一条线改共享数据。 ThreadSanitizer 电脑上 `-fsanitize=thread`，打印谁在抢变量。深入理解不加锁必现错乱 → 加锁正确 → 电脑上工具指出抢变量的两行代码。
		6.2 三线拆开：采集、控制、通信
		6.3 共享状态与干净停
		深入理解：板上不加锁看错乱、加锁修好；电脑上 ThreadSanitizer 指出抢变量的两行
综合	综合大项目	P.1 双机通：荔枝派三线程 + K3 SSH + Broker	复用 ch06 三线程；量化出 GGUF；K3 上 `llama-server`；终端 DeepSeek Harness 打字；工具转发 MQTT；本地与云端只换地址	端侧 Agent 环境终端：滞回自己转；终端打字能 `read_status` / `set_fan` / `set_led`；同一套工具走本地量化模型与云端 DeepSeek。正文见 project.html	可答辩作品	DeepSeek Harness Agent 运行时；本课在终端打字，不把网页当主入口。 llama.cpp 量化 + K3 上加速推理，提供 OpenAI 兼容 HTTP。工具插件登记后由模型调用；execute 只转发到已有 MQTT/C 程序。滞回仍在没人打字时控制线程仍按阈值拉风扇。
		P.2 主机量化：llama-quantize 得到 Q4 GGUF
		P.3 K3 启动 llama-server（IME2 加速包）
		P.4 终端启动 dsh --profile tui；登记本地与云端模型
		P.5 登记 read_status / set_fan / set_led / set_threshold
		P.6 关掉终端对照滞回；再打字改行为
		P.7 答辩：验收表走一遍，本地和云端各问一句

综合项目怎么接到前六章

正文：docs/project.html。不再做 weights.h / 手写 tiny 前向。
手仍是荔枝派上的 C 三线程（采集、滞回、MQTT），用 RuyiSDK 交叉编译。
脑是 K3 上量化后的本地模型（llama.cpp）以及可替换的云端 DeepSeek，两者对 Harness 都是 OpenAI 兼容 HTTP。
嘴是终端里的 DeepSeek Harness（dsh --profile tui），像 Claude Code 那样打字；工具转发到已有 MQTT。