联盛德W801_W806_开发指南

1 · 文档导读与阅读路径

本章说明这份文档的覆盖范围、事实来源与书写约定。W80x 的资料体系相对分散——官方规格书、SDK 源码、社区帖子各管一段——先明确边界比直接跳进技术细节更省时间。

1.1 覆盖范围

本文档覆盖从选型到量产的完整链路：W80x 五个在产型号的对比与选型、工具链（wm-sdk-w80x Makefile 构建体系、CSKY 交叉编译器、CDK IDE、串口烧录工具）、第一个点灯工程、启动链与镜像格式、GPIO 与常用外设、W801 的 Wi-Fi 与蓝牙开发、RTOS 任务设计、低功耗与电源、存储与文件系统、OTA 升级、产线烧录、调试诊断，以及故障速查表与四份附录。

覆盖方式上，本文档坚持「机制优先、参数兜底」：每个主题先讲清楚它是怎么工作的（比如下载模式为什么必须有复位、双分区为什么能回退），再给出操作步骤与排查路径。这样即使 SDK 版本更迭导致个别命令或接口名变化，你也能凭机制推断出新的正确用法——这也是 W80x 这类资料分散度较高的平台唯一可靠的学习方式。

1.2 不覆盖什么

• 不逐条翻译寄存器手册。W80x 的寄存器手册（芯片设计指导 / 寄存器手册）由官方分发，本文档讲「怎么用」与「哪里会出错」，位定义以官方手册为准。
• 不覆盖 W600 / W601 等前代系列。W600 系列是 Cortex-M3 内核的上一代产品，与 W80x 的工具链、镜像格式均不通用，本文档只在容易混淆的地方提示差异。
• 不覆盖 Wi-Fi 认证与法规测试的完整流程。SRRC / CE / FCC 认证属于独立主题，第 8 章只给射频设计上的工程注意点。
• 不替代勘误与版本说明。SDK 各版本（wm-sdk-w80x、wm-sdk-w806 及社区维护分支）差异较大，涉及具体文件与函数签名时以你实际使用的 SDK 版本为准。

另外说明两件「不做但相关」的事：本文档不提供任何不开源固件的逆向方法，也不讨论绕过安全启动的手段——这两类需求请走厂商渠道；同时本文档不绑定任何特定开发板，凡涉及开发板行为（如 RTS 复位电路）处均已注明该行为来自哪一类板型，换板时按对应原理图核对。

1.3 版本与事实来源标注约定

本文档中所有容量、频率、外设数量等硬规格来自以下三类出处，行文中会标明；无法确证的细节一律写「以官方 datasheet / SDK 文档为准」，不做猜测：

• 官方规格书 —— 型号封装、内核频率、RAM / Flash 容量、外设清单、功耗模式，取自联盛德官网公布的 W801 / W806 芯片规格书。
• 官方在线文档 —— 联盛德文档站的 SOC 指南（芯片比较表、外设章节），与官网规格书交叉核对。
• SDK 与社区资料 —— wm-sdk-w80x 构建流程、烧录工具用法，取自 SDK 自带的 README 与成熟社区整理，涉及版本差异处已注明。

为什么如此强调来源？因为 W80x 的二手资料里混着大量「型号张冠李戴」的内容：把 W601 的摄像头接口安到 W801 头上、把 AIR 系列的参数混进 W806、把不同批次规格书的差异当成通用结论。本文档在两处做了显式纠偏——W801 的 LCD 是 4x32 段码而非 RGB 彩屏、官方接口清单不含 DVP 摄像头——这两点在第 2 章与第 7 章都有专门说明，选型阶段务必看到。

1.4 代码与命令书写约定

• 代码块中带 $ 前缀的是命令行，其余为 C 代码或配置文件内容。
• 路径分隔符一律用 /，Windows 下在 MSYS / Git Bash 环境中同样可用。
• SDK 的配置入口是 make menuconfig，文中提到「menuconfig 某一项」时指该交互菜单里的对应条目。
• W80x 的内核是 C-SKY 架构，交叉编译器前缀为 csky-abiv2-elf-；不要把它与 arm-none-eabi- 工具链混用。
• 示例中的端口号（COM5、/dev/ttyUSB0）与文件名（app.fls）都是占位值，按你的环境替换。

1.5 阅读路径建议

按封面给出的四条路径阅读即可。两点补充：第一，W806 与 W801 的 MCU 部分完全同构，第 4~7 章、第 9~11 章对两颗芯片同样适用，差别只在第 8 章（无线）与容量相关的小节；第二，如果你只想快速验证一块新板子，直接跳到第 4 章的烧录流程与第 15 章的速查表，其余章节按需回查。

给从其他平台迁来的工程师一句忠告：W80x 文档的「信息密度」不如 Arm 生态，很多细节藏在 SDK 源码与社区帖子里。遇到文档没写的行为时，读 SDK 源码往往是最快路径——它的驱动层代码量不大、结构清晰，配合第 5 章的目录分层说明，定位一个外设的初始化流程通常只需要十几分钟。把「读源码」当成常规手段而非最后手段，是这个平台高效开发的关键心态。

2 · W80x 家族全景与选型

W80x 不是一颗芯片，而是共用同一内核的五六个型号组成的小家族：无线型（W800 / W801 / W803）带 Wi-Fi 与蓝牙，纯 MCU 型（W805 / W806）去掉射频做成低成本单片机。选型的本质是在射频、封装引脚、内置 Flash 容量三者之间做取舍。本章先给全景地图，再逐型号拆开讲，最后给出决策流程与易错点。

2.1 共同底座：XT804 内核与 C-SKY 架构

W80x 全系采用 32 位 XT804 处理器，工作频率 240 MHz，内置 DSP、浮点运算单元与安全引擎。XT804 属于平头哥（原 C-SKY 中天微）的 C-SKY 架构——既不是 Arm，也不是 RISC-V。这件事的工程含义贯穿全文：交叉编译器要用 CSKY 工具链（csky-abiv2-elf-gcc），调试器要用 CK-Link 体系，中断控制器与 NVIC 语义相近但寄存器不同。好消息是 C 库、FreeRTOS、lwIP 这些上层软件资产都能原样复用，迁移成本集中在工具链与驱动层。

从性能定位看，240 MHz 的 32 位核加硬件乘除与浮点，覆盖物联网终端的典型算力需求绰绰有余：协议解析、传感器融合、简单加密、段码屏界面都在舒适区内；真正吃算力的场景（高帧率图形、压缩算法、密集浮点）要么用 DSP 指令优化，要么重新评估平台。与同价位 Arm Cortex-M4 相比，XT804 的整数吞吐在同一量级，差异不在算力而在生态——这一点在 2.7 节展开。

安全引擎值得一提：TEE 隔离、代码安全权限、固件加密与签名都在硬件层有支撑，这让「固件防盗取」「安全升级」从纯软件愿望变成可落地的配置项，第 6.8 节与第 12 章会用到这组能力。

2.2 五个型号一张表看清

下表把在产主力型号并排放。所有型号 RAM 均为 288 KB，内核均 XT804 240 MHz；差异集中在射频、Flash 容量与封装。表中「可用引脚」一列是评估外设接入能力的第一近似值——真正的引脚能不能用，还要等 7.1 节的复用矩阵核对过才算数。

谱系关系可以用一句话记牢：W801 = W806 + 无线 + 一倍 Flash；W800 / W803 是把 W801 塞进 QFN32 的引脚精简版；W805 是 W806 塞进 QFN32 的精简版。整张家族地图如下：

来源：联盛德官网规格书与官方 SOC 指南芯片比较表

读这张谱系图时注意两点：第一，W801S 是 W801 的增强档（带触摸传感器、引脚更多），新设计优先考虑 S 档；第二，同核衍生型号（如 AIR101 / AIR103）与 W80x 共享工具链与开发体验，但分区、封装与官方支持体系不同，混用时以对应官方文档为准。

2.3 W801：带无线的全功能型

W801 可以理解为「W806 + Wi-Fi/蓝牙」再加一批扩展接口：在 6 路 UART、2 个 SPI、SDIO HOST / DEVICE、I2C、5 路 PWM、I2S、7816 之外，集成了 PSRAM 扩展接口（最高 64 MB 外挂）与 4x32 段码 LCD 控制器。2 MB 内置 Flash 也比 W806 多一倍——无线协议栈本身要占掉一块，多出来的容量对联网产品是刚需。做带屏、带存储卡、带音频链路的联网终端，W801 是家族里唯一不用外挂太多东西的选择。

它的外设组合在单芯片上形成了一条完整的数据链路：PSRAM 承接图像与音频缓冲，I2S 外挂 codec 做采集回放，SDIO HOST 接 TF 卡做本地存储，段码 LCD 做人机界面，Wi-Fi / 蓝牙负责上报与配网。换在「MCU + 外挂模组」的传统方案里，这条链路至少要三颗芯片和两套软件栈；W801 把它们压进一颗 6x6 mm 的 QFN56，这是它作为「全功能型」的真实含义——不是外设数量多，而是数据链路闭环。

同时要把边界讲清楚：W801 是 MCU 而非应用处理器，它跑 RTOS 与裸机业务，不跑 Linux；它的高吞吐能力受串口与内存带宽约束，适合「采集 + 上报 + 控制」的物联网形态。给方案定位时把它当「带无线的增强型 MCU」，别当「缩小版 Linux 板」。

2.4 W806：无射频纯 MCU 型

W806 把射频部分整个去掉，Flash 减到 1 MB，其余 MCU 特性与 W801 一致，官方 SOC 指南明确它有 43 个可用引脚并支持触摸传感器。它的典型位置是「比 STM32 便宜的通用 32 位 MCU」：点灯、电机控制、传感器采集、段码屏人机界面这类不联网的应用。开发板便宜、SDK 开源、教程多，也是大多数人第一次接触 W80x 的入口型号。

W806 的性价比来自两处：一是去射频后电源方案极简，单 3.3 V LDO 即可闭环（第 10.5 节）；二是封装引脚多而成本低，43 个可用引脚在同价位的芯片里相当宽裕。它承接「8 位机升 32 位」的替换需求非常顺——240 MHz、288 KB RAM 的规格让原来在 8 位机上精打细算的代码可以放开写，而开发体验（串口烧录、printf 日志）又足够轻。

限制同样明确：1 MB Flash 减去分区开销后应用空间有限，大型中间件（完整 TCP/IP、文件系统 + 大字体库）叠起来要仔细核算；无射频意味着联网需求必须外加模组或换 W801。选型时先过一遍 Flash 预算表再下结论。

2.5 W800 与 W803：小封装无线型

当 W801 的 QFN56 引脚用不满、PCB 又要求紧凑时，小封装无线型就是答案。两者都是 QFN32、2 MB Flash、Wi-Fi + BT/BLE 4.2，差别在引脚数量与触摸传感器配置。

2.6 W805：W806 的 QFN32 精简版

W805 与 W806 同为无射频纯 MCU、1 MB Flash，区别只在封装：QFN32 对 QFN56，可用引脚 18 对 43。选型逻辑与无线侧的 W800 / W803 完全对称——引脚够用就选小封装省板面积与成本，引脚吃紧就上 QFN56。两颗芯片的 SDK、烧录流程、外设驱动完全一致，中途换封装的迁移成本接近零。

工程上有一个反直觉的经验：先定引脚数，再定封装。很多项目在原理图阶段发现 18 脚不够用——晶振、串口、若干模拟通道、一排按键就把 QFN32 占满了——被迫中途换 W806，改封装改走线反而更贵。选型阶段把引脚预算表（7.1 节）先画出来，这类返工可以完全避免。

2.7 与主流 Arm Cortex-M MCU 的定位差异

把 W80x 放进「Arm MCU 们」旁边的坐标系里看，差异不在单点性能，而在体系：

一句话结论：用 Arm 生态的惯性来用 W80x 会处处别扭，把它当成「带 C-SKY 体系约束的超高集成度 MCU」就顺了。凡是「必须用某个 Arm-only 中间件」的项目，不要硬迁；凡是「一颗芯片闭环做联网终端」的项目，W80x 的集成度优势非常直接。

2.8 选型决策树

下面这张图把最常见的分叉按优先级串起来。先问要不要无线，再在同类里按封装、引脚与 Flash 细分；技术维度之外还要叠加供货与已有代码资产。

走完这棵树后，用三个问题复核一遍：协议栈加双备份后 Flash 还剩多少（2.10 节的算法）；目标外设的引脚在所选封装上是否全部引出（附录 A 的引脚定义表）；团队是否有人愿意读 C-SKY 汇编级的启动代码——三个问题都有答案，选型就算闭环了。

2.9 选型时最容易忽略的四件事

这四件事的共性是「出问题在量产前后，根因却在选型周」：Flash 算错、ADC 选错、把段码屏当彩屏、封装换不动——全都源于选型阶段的信息缺口。逐条对照：

2.9.1 无线产品的 Flash 要按三份算

做联网产品至少要按「当前固件 + OTA 备份 + 参数区」三段来规划 Flash，再留余量。W801 的 2 MB 里，Wi-Fi 与蓝牙协议栈会占掉一块，真正留给应用的是剩余部分——选型时不要只看编译出来的 bin 有多大。

三份算法之外还要给文件系统与日志留位，完整的算式是：总容量 - 引导区 - 参数区 - 应用区 - 升级备份区 - 文件系统区 = 应用真实可用量。每一段都在第 6.4 节的分区图上有对应位置。把这张算式做成电子表，选型评审时现场代入实测数据，比「感觉够用」有说服力得多。

2.9.2 ADC 等模拟外设的规格以规格书为准

W80x 集成 4 路 ADC，采样率上限在 kHz 量级，不同批次规格书对位宽的描述有差异。它适合电池电压、温度这类慢速采集，不适合音频级采样——需要高速采集时用 I2S 外挂 codec。具体位宽与量程以对应型号官方规格书为准。

2.9.3 LCD 控制器是段码屏，不是彩屏控制器

官方清单里的 LCD 控制器是 4x32 段码接口，用来驱动段码式液晶。要驱动 SPI 彩屏应走高速 SPI 或主/从 SPI 接口，不要把「LCD 控制器」理解成 RGB/TFT 控制器。

2.9.4 封装与可制造性

QFN 封装的散热焊盘与返修难度都高于 SOP，小批量手焊优先考虑带引脚的适配转接板或直接选带排针的开发板打样；量产再切直贴。QFN32 与 QFN56 的引脚定义不同，换封装不是「换个焊盘」而是要重画引脚映射。

可制造性评审时还有两件小事值得确认：丝印与极性标识的易读性（QFN 无引脚边缘，贴片方向错是产线常见缺陷）；测试点预留（串口、复位、关键电源至少各留一个，量产调试与返修全靠它们）。这两项改动在原理图阶段是零成本的，投板之后就是改造费用。

2.10 内置 Flash 容量要按三份算

第 2.9.1 节的三段式规划在这里展开：1 MB 的 W806 做纯 MCU 应用通常宽裕；2 MB 的 W801 扣掉无线协议栈与 OTA 备份后，应用可用空间需要在项目早期实测（第 5 章编译产物小节给方法）。若实测不够，W801 还有 PSRAM 与 SDIO 两条外挂路径，但代码仍然只能在内置 Flash 上 XIP 执行——外挂解决的是数据与资源，不是代码。

容量核算建议做成一张随版本更新的表：分区基线（引导 + 参数 + 应用 + 备份）、协议栈实测占用、应用与文件系统预算、余量。每次协议栈特性开关变化、每次大依赖引入都更新一次。这张表在 OTA 方案评审（第 12 章）与 Flash 溢出排障（第 15 章）时都会被反复引用。

2.11 文档体系与事实来源

W80x 的官方资料四件套是：芯片规格书（电气与外设清单）、寄存器手册（位定义）、芯片设计指导（外设工作机制）、SDK 及其文档。加上官方在线文档站的 SOC 指南，共五类入口，附录 A 给出索引。查规格时的优先级建议：规格书定能力边界，SOC 指南定外设有无，SDK 源码定 API 形态——三层冲突时以最新版规格书为准。

还有一个实操建议：把本文档与官方规格书放在一起用。本文档负责「为什么」与「怎么绕坑」，规格书负责「确切数值」；凡本文档标注「以官方 datasheet 为准」的地方，动手前花一分钟翻到对应页确认，可以挡掉大部分「抄错参数」类事故。

3 · 工具链全景

W80x 的工具链由四层组成：SDK 构建体系、CSKY 交叉编译器、串口烧录工具、CDK IDE 与 CK-Link 调试链路。本章把每一层的职责边界、安装要点与常见误区讲清楚——工具链装不对，后面每一步都在还债。

3.1 官方工具链四件套

官方推荐的完整组合是：wm-sdk-w80x SDK 负责源码组织与编译调度，平头哥 CSKY 工具链负责把 C 代码变成 XT804 机器码，wm_tool 负责打包与串口烧录，CDK IDE 负责图形化的编辑与在线调试。四件套的分工见第 3 章工具链职责边界图：前三者构成日常开发的最小闭环，IDE 与调试器只在需要断点调试时引入。

与 Arm 平台「装个 IDE 全搞定」的体验不同，W80x 的四件套是松耦合的：每一层都可以独立替换。编译可以换成社区开源工具链，烧录可以换 w80xprog 或自研脚本，IDE 甚至可以完全不用（VS Code + 命令行是很多团队的实际配置）。理解了这种松耦合，环境问题的定位思路就清晰了——每一层单独验证：工具链能编译出 elf、打包能出 fls、串口工具能握手成功，三层各过各的，环境就通了。

3.2 wm-sdk-w80x 构建体系

官方 SDK 采用经典的 Makefile + menuconfig 组合：make menuconfig 配置工具链路径、下载端口与波特率，make 触发编译与打包，make flash 调用 wm_tool 完成下载，make monitor 打开串口看日志。W806 有独立的 wm-sdk-w806 仓库，社区维护分支（如 IOsetting 版）在文档与开箱体验上更友好，目录结构一致。整个体系对 Linux / macOS / Windows（MSYS）都可用。

menuconfig 是这套体系的「配置真相源」：所有会随环境变化的东西——工具链路径、端口名、波特率——都收在这里，其余人只管 make。团队协作时把 menuconfig 的最终状态存档（截图或导出），新人搭环境从「恢复存档 + 改端口」开始，十分钟内可复现。下面是四个最高频命令：

$ make menuconfig    # Toolchain Configuration 填工具链 bin 路径（带末尾斜杠）
                     # Download Configuration 填端口（如 COM5）与波特率
$ make               # 编译 + 打包，产物在 bin/ 型号目录下（如 W806.fls）
$ make flash         # 调用 wm_tool 串口下载
$ make monitor       # 串口监视日志

3.3 CSKY 工具链：csky-abiv2-elf-gcc

XT804 属于 C-SKY abiv2 ABI，交叉编译器前缀为 csky-abiv2-elf-。工具链从平头哥渠道获取（SDK 文档会给定版本，如 csky-elfabiv2-tools 系列），解压后在 menuconfig 里填入其 bin 目录即可，编译系统会自动拼出完整前缀。最常见的两类错误：一是路径没带末尾斜杠导致拼接失败；二是误装了 abiv1 的旧工具链，报非法指令或链接错误。社区另有开源工具链方案（可参考开源生态整理的 W80x 工具链仓库），内核一致、可按需选用。

工具链版本管理是团队协作的隐形坑：同一份代码在不同版本的 CSKY 工具链下，编译告警集合与优化行为可能不同。建议在仓库里记录「SDK 版本 + 工具链版本 + menuconfig 配置」三元组，新成员按三元组复现环境。升级工具链属于「全量回归」级别的变更——三个关键场景（烧录、Wi-Fi 连接、OTA）必须重新验证后再全面切换。

3.4 CDK IDE 的角色

CDK（C-SKY Development Kit）是平头哥提供的集成开发环境，覆盖编辑、编译、烧录与调试。对 W80x 而言它的核心价值是在线调试：配合 CK-Link 调试器与 csky-debug-server，可以在源码级打断点、单步、看变量与调用栈——这是串口 printf 做不到的。日常改代码、编译、烧录用命令行更轻快，CDK 建议在疑难问题定位时再上手，两套流程并存不冲突。

一种被验证过的高效组合是：VS Code 负责写代码与版本管理，命令行负责编译烧录，CDK 只在「需要断点」时打开。这样规避了 CDK 在工程管理上的学习成本，又保留了它在调试上的核心价值。CK-Link 的获取与自制方案（社区有基于通用开发板的低成本自制资料）可按团队预算选择，调试链路的完整说明见第 14 章。

3.5 官方烧录工具：wm_tool 与 Upgrade_Tools

wm_tool 是 SDK 自带的命令行烧录工具，也是 make flash 的实际执行者，核心参数只有五六个：-c 端口、-rs 复位方式（at / rts）、-ds 下载波特率、-dl 固件路径，另有 -eo 全片擦除与 -sl 串口监视。Upgrade_Tools 是同一协议的 Windows 图形化版本，适合手工操作：选端口、开串口（默认 115200）、选 fls 文件、点下载、短按 Reset。两者协议相同，选哪个只影响效率不影响结果。

理解 wm_tool 的最佳视角是把它当成「第 4 章下载模式时序的自动化实现」：打开串口、发同步码、等 Secboot 回显、协商速率、传固件、复位——每个参数都对应时序里的一个环节。烧录参数出问题时，回到时序图逐环节对照，比反复换参数试错有效得多。命令全集见附录 B。

3.6 社区开源烧录器：w80xprog

社区的开源命令行烧录器 w80xprog（C 语言，GPLv2）覆盖了与 wm_tool 相同的一线协议，并补上了几个产线友好的能力：读芯片信息（-i）、改 Wi-Fi / 蓝牙 MAC（-w / -b）、设射频发射增益（-g）、链路提速（-n 921600）与操作后自动复位（-r）。它的单二进制、无 Python 依赖的特性很适合写进产线脚本。附录 B 给出两个工具的命令速查。

选型建议：研发日常用 SDK 内置的 make flash / wm_tool（与构建流程一体）；产线与自动化脚本用 w80xprog（参数平面、行为可预期）；手工给客户演示用 Upgrade_Tools（有图形界面，不用背命令）。三者在协议层完全等价，混用不会产生冲突——唯一的纪律是「同一时刻只有一个程序占用串口」。

3.7 社区生态与第三方开发板

W80x 的社区生态相当活跃，形态上有四类：SDK 的社区维护分支（补文档、修跨平台问题）、开源烧录与调试脚本、把 W80x 内核移植进既有 IoT 固件平台的适配层，以及第三方厂商基于 W806 / W806 同核衍生型号（如 AIR101 / AIR103）的开发板。官方开发板与第三方板并存，选板子主要看三件事：板载 USB 转串口是否带 RTS 复位电路（决定能否自动进下载模式）、引脚引出是否齐全、是否有基于该板的教程与示例。本文档不点名推荐，按这三个标准自行评估即可。

参与生态时留意信息时效性：W80x 的 SDK 与工具链迭代较快，两年前的教程里工具链版本、烧录命令可能已经过时。判断一篇资料是否仍可靠的最快方法是看它的工具链前缀（abiv2 才是现行）与产物格式（fls 打包流程是否与当前 SDK 一致）。

3.8 工具链职责边界

把第 3 章的工具们放回一张图里：源码组织、编译、打包烧录、IDE 调试各管一段，链路之间只通过「fls 固件文件」和「串口」两个接口衔接。

这张图还有一个用途：新成员入职时按图分工答疑——「为什么编译过了烧不进去」是烧录层的事，「编译都过不了」是工具链层的事，「编译报找不到头文件」是源码组织层的事。把问题先归层再排查，是工具链维护者的第一课。

4 · 第一个工程：W806 最小系统与点灯

本章以 W806 开发板为例走通完整闭环：最小系统、硬件连接、进入下载模式、串口烧录、验证三个「成功标志」，并前置三个「假成功」陷阱。W801 的流程完全相同，只是开发板带 RTS 自动复位电路，第 3 步可以由工具代劳。

4.1 W806 最小系统

在开发板上这一切都已就绪，但理解最小系统有助于排查自制板的问题：W80x 单芯片闭环，最小系统就是「3.3 V 供电 + 晶振 + 复位 + 下载串口引出」。

自制板第一条铁律是照抄官方硬件参考设计再谈优化：电源去耦的位置与容值、晶振负载电容、复位 RC 参数，这些在参考设计里都有现成答案。自己「顺手优化」的最常见下场是：晶振不起振（烧录与日志全无）、复位电平漂移（时进时不进下载模式）、去耦不足（射频型发射时电压跌落复位）。参考设计的价值就在于把这些坑一次性替你踩完。

4.2 硬件连接与串口参数

只需要一根 USB 数据线（注意很多线是纯充电线）：板载 USB 转串口接到 PC，设备管理器里确认端口号（如 COM5）。串口参数与日志波特率一致，SDK 默认常用 115200。若用外接 USB 转串口模块，TX/RX 交叉连接，共地，并确认电平为 3.3 V。

把「连上但不对」的情况提前列出来能省大量时间：设备管理器里没有端口 → 转换芯片驱动没装或线是充电线；有端口但日志空白 → TX/RX 没交叉或波特率不对；日志乱码 → 见第 14.6 节（多半是时钟配置而非接线）；W801 一连终端就重启 → RTS 复位电路在起作用，见 4.3 节。这张「症状 → 根因」清单与第 15 章速查表互通。

4.3 进入下载模式的条件

下载模式的本质是：复位瞬间 ROM secboot 接管串口，并在总线上收到工具的同步码流。两个条件缺一不可——只复位不同步，secboot 直接启动应用；只同步不复位，应用不会让出串口。第 4 章串口烧录链路图给出了完整五步时序，工程上的操作对应关系是：W806 开发板手动短按 Reset 配合工具；W801 开发板由 RTS 自动复位，工具用 -rs rts 即可全自动。

理解「两个条件缺一不可」之后，所有下载模式的疑难都能归因：有时候应用代码把下载串口的波特率改成了非常规值，工具与 ROM 之间反而握不上手（ROM 以固定速率监听）——这类问题的解法是在应用里保留下载串口的默认配置，或把业务通信挪到其他 UART。另外，W801 开发板「连上即复位」的行为意味着烧录与看日志不能共用一个终端会话，分开操作是正解。

4.4 串口烧录流程

完整链路见第 4 章串口烧录链路图：固件从 PC 工具出发，经 USB 转串口、芯片 UART、ROM secboot 握手，最终写进内置 Flash。三个关键环节（进入下载、wm_tool 参数、w80xprog 参数）浓缩如下：

以 SDK 内置流程为例，make flash 内部调用形如下面的命令；手工操作用 Upgrade_Tools 亦可：

$ wm_tool -c COM5 -rs at -ds 115200 -dl bin/W806/W806.fls
# -rs rts：由 RTS 自动复位进下载模式（W801 开发板）
# -eo all：全片擦除；下载完成后按提示再复位一次运行新固件

烧录成功的现象是：工具回显 Secboot 版本、进度条走完、提示 download completed；随后再按一次 Reset（或工具自动复位），新固件开始运行。进度缓慢时可把 -ds 与 menuconfig 里的下载波特率一起提到 921600。若要把烧录并入自研脚本，建议直接调 w80xprog：单二进制、参数简单、-r 自动复位，比包装 wm_tool 更省事。

4.5 点灯工程与三个成功标志

SDK 示例工程里把某个 GPIO 配成输出并周期翻转，编译烧录后按三个标志验收：

这三个标志的深层价值在于分层验证：编译通过验证的是工具链与工程配置；烧录通过验证的是串口链路与下载模式；运行通过验证的是时钟、GPIO、串口三项硬件与软件的配合。任何一个标志不过，问题就被限定在一层之内——这也是排障时先问「卡在第几个标志」的原因。

4.6 三个「假成功」

初学者最容易被这三种状态骗到：

三个假成功的共同解法是建立「事实链」：fls 文件的修改时间戳 → 烧录工具的回显记录 → 板上运行日志的版本号。三个事实对得上，才是真成功；对不上时按链条找断点。把时间戳打印加进构建脚本（第 5.7 节）后，第一环就不存在争议了。

4.7 常见失败与排查

首烧失败集中在三类：串口被占用（关掉其他串口终端再 make flash）、没按 Reset 或复位时机不对（工具在等同步码时复位芯片）、波特率链路不稳（先回 115200 验证）。SDK 报 can not open serial 时优先查端口占用；报 serial sync 失败时按第 4 章下载模式时序图逐步对照。更细的处置表在第 14 章与第 15 章速查表中复用。

有一类「玄学失败」值得单独点名：时好时坏的握手失败。多数最终指向物理层——USB Hub 供电不足、劣质延长线、杜邦线接触电阻——而不是软件。判断方法：换一条短线直插 PC 再试一次，如果成功率立刻恢复，问题就在物理层。这条经验在产线上同样适用（第 13.7 节）。

4.8 从点灯到工程化

点灯通过后，建议立刻做三件事把「能跑」变成「可维护」：把 SDK 纳入版本管理并固定工具链版本；在应用入口建立统一的日志输出与错误码（第 14 章日志体系）；把 menuconfig 配置导出存档，保证任何一台机器 checkout 后 make menuconfig 只需改端口。第 5 章从工程结构层面展开这三件事。

第四件常被遗漏的事：把「从零复现环境」写成一篇内部文档并实测一次——在一台干净电脑上按文档把环境搭到点灯成功。文档里写不清楚的每一步，都会在未来某次换电脑、新人入职或 CI 搭建时变成半天到两天的损耗。

5 · 工程结构与编译体系

W80x 的工程组织是「SDK 目录树 + Makefile + menuconfig」。本章讲清三件事：目录分层与用户代码的位置、menuconfig 与 Makefile 里真正会影响你的配置项、以及编译产物到 fls 固件之间的打包链路。

5.1 SDK 目录分层

官方 SDK 的目录树可以按五层理解：应用层（app）、平台层（platform：启动、驱动、系统）、头文件层（include）、协议栈与源码层（src，W801 SDK 特有）、工具层（tools 与 bin）。分层图如下：

日常开发的纪律由此而来：应用代码只写在 app 层；要改 platform 层驱动时，用「改动清单」记录每一个补丁，SDK 升级时逐条重放——这是 W80x 项目里最省后续时间的一个习惯。

为什么这么强调分层纪律？因为 W80x 的 SDK 不同于「库 + 你的工程」的结构——SDK 本身就是工程的根，git 仓库里存的是整个 SDK 树。没有分层纪律的项目，三个月后没人说得清哪些文件被改过、升级 SDK 要重放什么。改动清单的推荐格式很简单：文件路径 + 改动摘要 + 关联需求，几十行文本就够；配合 git 分支「sdk-baseline / project」两支管理，升级时 diff 一眼可查。

头文件层（include）值得单独提醒：应用里 #include 的驱动 API 声明都在这一层，改动它意味着所有模块受影响。需要扩展驱动接口时，优先在自己的 app 层写包装函数，而不是直接改 include 里的声明——前者只影响自己，后者影响全局。

5.2 menuconfig 与 Makefile 关键配置项

menuconfig 里真正高频使用的配置集中在三组：

关于这三组配置的操作建议：工具链路径只在环境变更时修改；端口与波特率是「每个开发者唯一需要改的两项」，值得写进新人文档；优化等级与内核模式的改动影响面大，改动前先看 5.6 节的报错表，改动后全量重编并重烧验证。menuconfig 本质上是在改写配置头文件——理解了这一点，就能读懂「配置不生效」的多数案例（改了菜单没重编、头文件被手改与菜单打架）。

Makefile 层面需要知道的只有三件事：顶层 make 会递归编译各子目录再链接；产物输出到 bin 目录；make flash / make monitor 是对 wm_tool 的薄封装，其参数模板在 tools 下的规则文件里，改端口波特率优先走 menuconfig 而不是直接改规则。

5.3 编译产物链：从 elf 到 fls

一次成功的 make 会产出一条产物链：elf（带符号，调试用）→ bin / 汇编镜像（纯二进制）→ 打包工具加上固件头（长度、校验、压缩与签名属性）→ fls（最终烧录文件）。串口烧录只认 fls；第 6 章会展开固件头与 secboot 的校验关系。判断「烧的到底是不是新固件」，最快的办法是看 fls 文件的修改时间戳——把它加进你的构建后输出脚本里。

产物链里最值得盯着的是 size 输出与 map 文件：text / data 段对应 Flash 占用，bss 段对应 RAM 占用。W801 的 Flash 预算紧张（第 2.10 节），建议每次构建后把 size 摘要打出来：一次不起眼的依赖引入可能悄悄吃掉几十 KB，等 OTA 放不下时才发现就晚了。map 文件则用于「Flash 都花在哪了」的拆解——按段排序找大头，通常能发现一两个没料到的占用大户。

5.4 应用代码写在哪里

入口与主循环放在 app 层的示例目录里，新工程直接复制官方示例改名；驱动封装放在 app 层自己的子目录而不是 platform 层，除非确有跨项目复用价值。与 STM32 的「USER CODE 保护 区」不同，W80x SDK 没有生成式代码保护机制——SDK 是你的代码库本身，因此更要靠 git 分支与补丁清单来隔离「SDK 基线」与「项目改动」。

推荐的 app 层内部组织：按功能域建子目录（drv / net / ui / util），每个域一个初始化入口，由 main 顺序调用。这比「所有代码平铺一个目录」的好处是：单元边界清楚、第 9 章的任务划分可以直接映射到目录、以及出问题时「问题属于哪个域」的判断变得机械——机械的判断才是好判断。

5.5 从 W806 SDK 到 W801 SDK

两个 SDK 的 app 层写法一致，迁移时主要换三样：工具链与 menuconfig 配置按 W801 SDK 重新走一遍；启用 src 层的无线协议栈（默认 W806 SDK 是裁掉无线的）；烧录端口与复位方式按开发板调整（W801 用 -rs rts）。第 8 章的联网代码都建立在 W801 SDK 之上。

迁移后第一件事是重算 Flash 与 RAM 预算：协议栈启用后 Flash 占用与常驻 RAM 都会显著增长，第 5.3 节的 size 摘要能立刻看到差值。第二件事是重验烧录链路——W801 开发板的 RTS 行为与 W806 不同（第 4.3 节），首次烧录务必按 W801 的流程走一遍，别沿用肌肉记忆。

5.6 构建常见报错

报错表的价值在于「先看根因再动手」——构建报错的表面信息（如 undefined reference）几乎从不指向真实根因，先对表再操作：

5.7 工程组织的实用建议

四条经验：工具链版本与 SDK 版本一起冻结记录；menuconfig 的最终配置导出存档；构建脚本在 make 之后追加「打印 fls 时间戳与 size 摘要」；把「改动过的 platform 文件清单」放在仓库根目录的固定文件里维护。这四条都是为第 12 章 OTA 与第 13 章量产服务的——版本可追溯是它们的共同前提。

再补一条容易低估的建议：让 CI 或半自动脚本做「每晚全量构建 + 烧录冒烟」。W80x 的构建链路对环境敏感（路径、斜杠、端口名），人肉维护的环境总会悄悄漂移；一个每晚跑的冒烟脚本能在漂移发生的当天发出警报，而不是在紧急发版那天爆炸。脚本不需要复杂——编译、出 fls、调 w80xprog 烧一块常驻板、抓两行启动日志即可。