企业官网建设流程全解析

1. “Microduck”不是鸭子，是嵌入式开发者的第一个“活体玩具”

你搜过“microduck”吗？点开GitHub，看到一堆叫 microduck 的仓库，有的带 LED 灯阵、有的接着 USB-C 接口、有的配着小屏幕，还有的 README 里写着“Plug in, blink, smile”。但翻遍所有项目主页，几乎没人说清楚：microduck 到底是什么？它和 Arduino、Raspberry Pi Pico、ESP32 有什么本质区别？为什么突然冒出这么多叫 microduck 的 DIY 项目？

我第一次见到这个词，是在一个硬件创客群的深夜闲聊里。有人甩出一张 PCB 图，说：“刚打样回来，microduck v1.2，USB 直连免驱动，烧录一次就能当 HID 键盘用。”旁边立刻有人回：“这不就是个带 USB Device 的 Cortex-M0+ 吗？为啥不叫 micro-pico 或 mini-esp？”——问题就在这儿。microduck 不是一个芯片型号，也不是一个官方标准，而是一类特定设计哲学的具象化产物：极简、可触摸、即插即用、拒绝抽象层。它不追求跑 Linux、不强调 Wi-Fi 性能、不堆传感器数量，它的核心目标只有一个：让第一次接触硬件的人，在 15 分钟内，亲手让一个物理设备响应自己的指令。

这和当前主流的嵌入式入门路径截然不同。你看那些“Java 自学路线图”“产品经理学习路线图”，逻辑清晰、阶段分明、资料堆山；但硬件入门却常卡在“第一步就断电”的尴尬里：买来开发板，装驱动失败、串口识别不到、烧录工具报错、LED 不亮、示波器没信号……最后不是放弃，就是靠复制粘贴硬扛过去，根本不知道哪根线在说话、哪个寄存器在控制、哪段代码真正改变了电压。而 microduck 的设计，就是从这个“断电点”开始反向工程——它把“让灯亮起来”这件事，拆解成三步：插上电脑（物理连接）、双击一个图标（软件触发）、看到灯闪（视觉反馈）。中间没有跳线帽、没有跳线帽、没有跳线帽（重要的事说三遍），也没有需要手动配置的 COM 口编号。

关键词里反复出现的“硬件选型”“第一行代码”“路线图”，恰恰暴露了当前 DIY 硬件学习的最大断层：我们有海量的芯片手册，却没有一份面向“人”的操作地图；我们能写出复杂的 RTOS 调度算法，却不敢拧开一个排针座看焊点是否虚连。microduck 就是这张地图的起点坐标。它不教你怎么写 USB 协议栈，但它让你亲手把一个 struct hid_report_descriptor 填进内存，并亲眼看到键盘按键事件出现在 Windows 的“键位测试工具”里；它不讲 ADC 采样原理，但它让你用万用表测出 GPIO 输出高电平时，引脚电压确实是 3.3V，而不是“理论上应该是”。

所以，这篇路线图，不是给你列一份“第1周学C语言、第2周看ARM架构”的时间表。它是带你回到那个最原始的触点：当你手指按下 USB 插头，听到“咔哒”一声轻响，电脑右下角弹出新设备提示——那一刻，你和硬件世界的真实连接，正式建立。后面所有的代码、电路、协议，都是对这个“咔哒声”的延伸解读。接下来，我会从一块 PCB 板的元器件清单开始，带你走完这条从螺丝刀到 printf 的完整链路。你不需要懂 Verilog，也不需要会画原理图，但你需要知道：为什么选 STM32G031K8T6 而不是 ESP32-S2？为什么 USB D+ 线上必须串一个 1.5kΩ 电阻？为什么第一行代码不是printf("Hello World")，而是HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET)？这些答案，不在数据手册的第 378 页，而在你第一次成功点亮那颗 LED 的瞬间。

2. 硬件选型不是参数对比，而是为“第一次成功”设置安全边界

很多人一上来就打开立创商城或 Digi-Key，输入“ARM 开发板”，然后被满屏的“Cortex-M4F @ 180MHz”“2MB Flash + 512KB RAM”“支持 Wi-Fi 6 + BLE 5.2”晃得眼花。结果买回来，发现驱动装不上、例程编译报错、调试器连不上，最后只能当镇纸。microduck 的硬件选型逻辑，恰恰是反其道而行之：不追求性能上限，而追求“首次通电成功率”的下限。它的选型原则只有一条：让所有可能出错的环节，都发生在你的可视范围内，且错误表现足够直观。比如，LED 不亮？你一眼就能看见；USB 无法识别？你直接拔插就能验证；串口无输出？你手边的 USB-TTL 模块立刻能帮你定位是代码问题还是接线问题。

2.1 主控芯片：为什么是 STM32G031K8T6，而不是更便宜的 CH32F103 或更火的 ESP32？

STM32G031K8T6 是 ST 推出的超值型 Cortex-M0+ 微控制器，48MHz 主频、64KB Flash、8KB RAM、20 引脚 QFN 封装。它在 microduck 项目中成为事实标准，绝非偶然。我们来拆解它的“安全边界”设计：

• USB Device 外设原生支持：这是决定性因素。STM32G0 系列内置 USB 2.0 FS Device 控制器，无需外挂 PHY 芯片，也无需额外晶振（内部 RC 振荡器精度达 ±1%，满足 USB 规范要求）。对比 CH32F103，虽然也标称 USB Device，但实际使用中需外接 12MHz 晶振且驱动兼容性差，新手极易卡在“设备管理器里显示感叹号”这一步；而 ESP32 虽然功能强大，但其 USB-JTAG/Serial 下载模式与 USB-HID 模式存在冲突，切换复杂，且默认固件常占用 USB 接口，导致 HID 功能需深度定制。

• 封装与焊接友好性：20 引脚 QFN 封装（3mm×3mm）比常见的 TSSOP-20 更易手工焊接。QFN 底部有散热焊盘，但 microduck 设计时会刻意将该焊盘悬空或仅连接 GND，避免回流焊时因锡膏过多导致芯片浮起。更重要的是，其引脚间距 0.5mm，配合 0.3mm 宽的 PCB 走线，用普通热风枪（温度 350℃、风速 2 档）即可完成焊接，无需专业 BGA 返修台。我实测过，用一把 30W 恒温烙铁 + 细焊锡丝，也能完成单颗芯片的手工贴片——这对想自己打样、自己焊接的初学者，是巨大的心理门槛降低。

• 供电简洁性：STM32G031 支持 1.8V–3.6V 宽压供电，microduck 通常直接取 USB 5V 经 AMS1117-3.3 稳压后供给主控，电路仅需 1 颗稳压芯片 + 2 颗滤波电容（10μF 钽电容 + 100nF 陶瓷电容）。对比 ESP32，其典型工作电压 3.3V，但对电源纹波极其敏感，USB 5V 直接降压时若滤波不足，极易出现启动失败或 USB 通信中断；而 CH32F103 对 VDDA（模拟供电）要求严格，需独立滤波，否则 ADC 读数飘忽，徒增排查难度。

提示：不要被“M0+ 性能弱”误导。microduck 的核心任务是执行 HID 报告发送、GPIO 控制、简单状态机，48MHz 主频绰绰有余。真正的瓶颈从来不是 CPU，而是你的调试耐心。选择 G031，等于选择了“错误反馈最快”的硬件平台——USB 插上即识别，LED 通电即亮，所有异常状态都能通过物理现象直接感知。

2.2 USB 接口电路：那个不起眼的 1.5kΩ 电阻，才是 HID 通信的“门禁钥匙”

microduck 的 USB 接口，绝不是简单地把 D+、D- 线接到芯片对应引脚上。它包含三个关键元件：USB Type-C 插座、D+ 线上的 1.5kΩ 上拉电阻、D- 线上的 15kΩ 下拉电阻（部分设计省略）。这个看似简单的电阻网络，实则是 USB 协议握手的物理基础。

USB 规范规定，全速（Full-Speed）设备需在 D+ 线上接一个 1.5kΩ 电阻至 3.3V，用于向主机表明“我是一个全速设备”。主机检测到 D+ 电压被拉高（约 2.8V），便启动枚举流程。如果这个电阻缺失或阻值偏差过大（如用 10kΩ），主机将无法识别设备，设备管理器里只会显示“未知 USB 设备”。而 D- 线上的 15kΩ 下拉电阻（接 GND），则是为了确保在未连接时 D- 保持低电平，避免误触发。

我在第一批打样的 microduck 板子上，就栽在这个 1.5kΩ 电阻上。当时为了节省 BOM 成本，用了贴片电阻（0603 封装），但焊接时锡膏量稍多，导致电阻两端轻微短路，实测阻值仅剩 300Ω。结果现象极其诡异：USB 插上后，电脑能识别出设备（设备管理器里有条目），但无法完成枚举，显示“设备描述符请求失败”。用万用表量 D+ 电压，只有 0.8V，远低于规范要求的 2.8V。重新换一颗合格电阻，问题瞬间解决。这个教训让我明白：硬件选型中的“元件”，不是参数表里的一个数字，而是你指尖能感受到的焊点温度、万用表上跳动的数值、示波器里稳定的方波。microduck 的设计，强制你直面这些物理细节，而不是躲在 IDE 的“Build Success”后面自我安慰。

2.3 外围器件：为什么只留一颗 LED 和一个按钮，其他全是“干扰项”

microduck 的 PCB 上，除了主控、USB 接口、电源电路，通常只保留两个外围器件：一颗 0805 封装的绿色 LED（阳极接 GPIO，阴极接地），和一个 6mm 贴片轻触开关（一端接地，另一端接 GPIO，内部上拉）。这种极简主义，是经过大量教学验证的最优解。

• LED 的作用远超“指示灯”：它是你的第一个“硬件输出信使”。当HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET)执行后，LED 亮起，你立刻获得正向反馈；当HAL_GPIO_TogglePin()循环执行，你看到闪烁频率，就能反推代码中 delay 函数的精度。更重要的是，LED 的限流电阻（通常 220Ω）是你理解欧姆定律的第一个实物教具——换用 1kΩ 电阻，亮度肉眼可见下降；换成 47Ω，LED 瞬间过亮甚至烧毁（我试过，冒了一缕青烟）。

• 按钮是“硬件输入”的唯一入口：它连接 GPIO 并启用内部上拉，按下时 GPIO 读取为 LOW。这个设计规避了外部上拉电阻的焊接误差风险，也避免了新手因忘记接上拉/下拉而陷入“读取值永远为高/低”的死循环。按钮的机械抖动（bounce）问题，则通过软件消抖（10ms 延时后二次确认）解决，这段代码成为理解“硬件时序”与“软件延时”关系的绝佳案例。

注意：所有 microduck 设计都刻意回避 I²C、SPI、ADC 等“高级外设”。不是它们不重要，而是它们引入了太多隐藏变量：I²C 的上拉电阻阻值、总线速率、从机地址；SPI 的 CPOL/CPHA 模式、时钟相位；ADC 的参考电压、采样时间、校准系数……这些都会在你刚建立“代码控制硬件”的信心时，无情地摧毁它。microduck 的哲学是：先让你相信“我能控制”，再教你“如何精确控制”。

3. 开发环境搭建：绕过 IDE 的“一键安装幻觉”，亲手构建最小可信工具链

现在市面上的嵌入式 IDE（如 STM32CubeIDE、PlatformIO）都宣称“一键安装、自动配置、开箱即用”。听起来很美，但当你第一次点击“Build”却弹出“arm-none-eabi-gcc: command not found”时，那种被系统背叛的感觉，足以让你卸载软件并怀疑人生。microduck 的开发环境搭建，核心目标不是“快”，而是“透明”——让你清楚知道，从你敲下gcc命令，到芯片里那颗 LED 亮起，中间到底发生了什么。

3.1 工具链三件套：GNU Arm Embedded Toolchain、OpenOCD、ST-Link Utility 的真实分工

microduck 的最小工具链由三个独立组件构成，它们各司其职，缺一不可：

• GNU Arm Embedded Toolchain：这是真正的“编译器”。它包含arm-none-eabi-gcc（C 编译器）、arm-none-eabi-g++（C++ 编译器）、arm-none-eabi-objcopy（生成二进制文件）、arm-none-eabi-size（查看代码体积）等命令行工具。它的作用，是把你的 C 代码（.c文件）翻译成 ARM 指令机器码（.elf文件）。注意，它不负责烧录，也不负责调试，它只做翻译。

• OpenOCD：这是“调试服务器”。它通过 ST-Link（或其他 JTAG/SWD 适配器）与芯片通信，提供 GDB 远程调试接口。当你在 VS Code 里按 F5 启动调试时，背后是 OpenOCD 在运行，它把你的断点、变量读取请求，转换成 SWD 协议指令发给芯片，并把芯片返回的数据传给 GDB。OpenOCD 本身不编译代码，也不生成.bin文件，它只是芯片与 PC 之间的“翻译官”。

• ST-Link Utility：这是“烧录器”。它是一个图形化工具，直接读取.hex或.bin文件，通过 ST-Link 将其写入芯片 Flash。它的优势在于简单粗暴：选文件、点“Program”，搞定。但它不支持调试，也无法设置断点。对于 microduck 的第一行代码，ST-Link Utility 是最可靠的起点，因为它绕过了 GDB 和 OpenOCD 的复杂配置。

我建议的搭建顺序是：先用 ST-Link Utility 烧录，再用 OpenOCD + GDB 调试，最后用 Makefile 管理整个流程。这样，你能在最短路径上看到 LED 亮起，建立信心；再逐步深入，理解调试机制；最终掌握自动化构建。

3.2 手动编译第一行代码：从 main.c 到 .bin 文件的七步拆解

假设你的项目目录结构如下：

microduck/ ├── core/ │ ├── startup_stm32g031k8tx.s # 启动文件（汇编） │ └── system_stm32g0xx.c # 系统初始化（时钟、中断） ├── drivers/ │ └── stm32g0xx_hal.c # HAL 库核心 ├── inc/ │ ├── stm32g0xx_hal.h │ └── main.h ├── src/ │ └── main.c # 你的主程序 ├── linker/ │ └── STM32G031K8TX_FLASH.ld # 链接脚本 └── Makefile

现在，我们手动执行编译过程（以 Windows PowerShell 为例，Linux/macOS 类似）：

1. 预处理（Preprocessing）：
   arm-none-eabi-gcc -E -I./inc -I./drivers -DUSE_HAL_DRIVER -DSTM32G031K8Tx src/main.c -o main.i
   此步展开所有#include和#define，生成main.i。你可以用cat main.i | head -n 50查看宏展开后的代码，理解HAL_GPIO_WritePin实际调用了哪些底层寄存器操作。

2. 编译（Compilation）：
   arm-none-eabi-gcc -c -mcpu=cortex-m0plus -mthumb -O0 -Wall -I./inc -I./drivers -DUSE_HAL_DRIVER -DSTM32G031K8Tx src/main.c -o build/main.o
   此步将main.i编译成目标文件main.o（机器码，但未链接）。-O0关闭优化，确保调试时源码与汇编一一对应。

3. 汇编（Assembly）：
   arm-none-eabi-gcc -c -mcpu=cortex-m0plus -mthumb -x assembler-with-cpp -I./inc -I./drivers core/startup_stm32g031k8tx.s -o build/startup.o
   将启动汇编文件编译为目标文件。

4. 链接（Linking）：
   arm-none-eabi-gcc -mcpu=cortex-m0plus -mthumb -Tlinker/STM32G031K8TX_FLASH.ld -o build/microduck.elf build/main.o build/startup.o drivers/stm32g0xx_hal.o
   此步将所有.o文件按链接脚本STM32G031K8TX_FLASH.ld中定义的内存布局（Flash 起始地址0x08000000，大小64KB）合并，生成可执行文件microduck.elf。

5. 生成二进制（Binary Generation）：
   arm-none-eabi-objcopy -O binary build/microduck.elf build/microduck.bin
   此步提取microduck.elf中的代码段（.text）和数据段（.data），生成纯二进制文件microduck.bin，这是 ST-Link Utility 能识别的格式。

6. 验证文件大小：
   arm-none-eabi-size build/microduck.elf
   输出类似：text data bss dec hex filename，其中text是代码体积。microduck 的第一版main.c（仅初始化 GPIO 并循环点亮 LED）通常 < 4KB，远小于 64KB Flash 限制，说明空间充裕。

7. 烧录（Flashing）：
   打开 ST-Link Utility，点击 "Target" → "Program"，选择build/microduck.bin，起始地址填0x08000000，点击 "Start"。几秒后，LED 应开始闪烁。

经验心得：这七步看似繁琐，但每一步的失败都有明确报错。比如第 2 步报错undefined reference to 'HAL_GPIO_WritePin'，说明stm32g0xx_hal.c未编译或未链接；第 4 步报错section .isr_vector overflowed，说明中断向量表大小超出 Flash 起始区域。这种“失败可定位”的特性，正是手动构建的价值——它把黑盒变成白盒，把玄学变成算术。

4. 第一行代码：从寄存器操作到 HAL 库，理解抽象层的代价与收益

很多教程一上来就教你用 STM32CubeMX 生成初始化代码，然后直接写HAL_GPIO_WritePin()。这没错，但就像学开车先坐进自动驾驶汽车——你踩油门，车走了，但不知道引擎怎么转、变速箱怎么换挡。microduck 的第一行代码，必须从最底层的寄存器操作开始，再逐层向上构建抽象，这样才能真正理解“代码如何控制硬件”。

4.1 寄存器级操作：直接操控 GPIOx_MODER 和 GPIOx_ODR

STM32G031 的 GPIO 控制，由多个寄存器协同完成。以控制 PA5（假设 LED 接在此引脚）为例：

• RCC->IOPENR：使能 GPIOA 时钟。
  RCC->IOPENR |= RCC_IOPENR_GPIOAEN;
  （地址0x40021000，bit 0 置 1）

• GPIOA->MODER：设置 PA5 为通用输出模式（01）。
  GPIOA->MODER &= ~(3U << (5*2));// 清除原有模式
  GPIOA->MODER |= (1U << (5*2));// 设置为输出模式
  （MODER寄存器每两位控制一个引脚，PA5 对应 bit[11:10]）

• GPIOA->OTYPER：设置为推挽输出（0）。
  GPIOA->OTYPER &= ~(1U << 5);//0表示推挽

• GPIOA->OSPEEDR：设置输出速度（00为低速）。
  GPIOA->OSPEEDR &= ~(3U << (5*2));

• GPIOA->PUPDR：设置无上下拉（00）。
  GPIOA->PUPDR &= ~(3U << (5*2));

• 点亮 LED：设置 PA5 输出高电平。
  GPIOA->BSRR = GPIO_BSRR_BS5;//BSRR寄存器，bit 5 置 1 置位
  // 或GPIOA->ODR |= GPIO_ODR_OD5;

这段代码共 6 行，直接操作寄存器地址和位域。它的好处是极致轻量（编译后 < 200 字节）、完全可控、无任何隐藏逻辑。坏处是：极度脆弱。如果你把BSRR写成BSRR = 1<<5（漏了BS前缀），就会清零 PA0；如果MODER设置错误，LED 可能不亮或烧毁 GPIO；如果忘记使能时钟，所有 GPIO 操作都无效。

4.2 HAL 库封装：用 3 行代码替代 20 行寄存器操作

STM32 HAL 库的本质，是用 C 函数封装上述寄存器操作，并加入错误检查和状态管理。HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET)的内部实现，大致如下：

void HAL_GPIO_WritePin(GPIO_TypeDef* GPIOx, uint16_t GPIO_Pin, GPIO_PinState PinState) { /* 检查参数合法性 */ assert_param(IS_GPIO_PIN(GPIO_Pin)); assert_param(IS_GPIO_PIN_ACTION(PinState)); /* 根据 PinState 选择 BSRR 或 BRR */ if(PinState != GPIO_PIN_RESET) { GPIOx->BSRR = (uint32_t)GPIO_Pin; } else { GPIOx->BRR = (uint32_t)GPIO_Pin; } }

它把寄存器操作封装成函数，同时加入了assert_param断言检查。这意味着，如果你传入GPIO_PIN_100，程序会在运行时崩溃（而非静默失败），帮你快速定位参数错误。HAL 库还提供了HAL_GPIO_Init()函数，一次性完成时钟使能、MODER、OTYPER、OSPEEDR、PUPDR 的配置，代码量从 20 行压缩到 3 行：

__HAL_RCC_GPIOA_CLK_ENABLE(); GPIO_InitTypeDef GPIO_InitStruct = {0}; GPIO_InitStruct.Pin = GPIO_PIN_5; GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; GPIO_InitStruct.Pull = GPIO_NOPULL; GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW; HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET);

4.3 抽象层的代价：为什么 microduck 项目仍坚持用 HAL，而非更底层的 LL 库？

STM32 还提供 LL（Low-Layer）库，它比 HAL 更接近寄存器，函数名直接映射寄存器（如LL_GPIO_SetOutputPin(GPIOA, LL_GPIO_PIN_5)），体积更小、执行更快。但 microduck 选择 HAL，原因在于其教学友好性：

• 命名语义清晰：GPIO_MODE_OUTPUT_PP比LL_GPIO_MODE_OUTPUT更明确地表达了“推挽输出”；GPIO_SPEED_FREQ_LOW比LL_GPIO_SPEED_FREQ_LOW更易理解其作用。

• 错误处理显式化：HAL 函数返回HAL_StatusTypeDef（HAL_OK或HAL_ERROR），你必须检查返回值。这强迫初学者思考“如果初始化失败，我的程序该如何应对？”，而不是忽略返回值，让错误在后续操作中爆发。

• 跨系列一致性：HAL API 在 STM32F0/F1/G0/L0 等系列间高度一致。今天用 G031 写的代码，明天迁移到 F401，只需改#include和HAL_Init()，主体逻辑几乎不用动。而 LL 库是按系列定制的，API 差异大，不利于知识迁移。

实操提醒：在 microduck 的早期迭代中，我曾尝试用 LL 库重写全部代码，体积减少了 15%，但调试时间增加了 3 倍——因为 LL 库的错误提示更少，一个LL_GPIO_SetOutputPin失败，你得自己去查 RCC 时钟、GPIO 模式、引脚复用等多个寄存器状态。而 HAL 的HAL_GPIO_Init()返回HAL_ERROR，配合HAL_GPIO_GetError()，能直接告诉你“错误来自 RCC 时钟未使能”。对初学者而言，节省的 15% 代码空间，远不如节省的 300% 调试时间重要。

5. 路线图落地：从 microduck v1.0 到 v3.0 的三次关键跃迁

microduck 不是一个静态的“成品”，而是一个持续演进的“学习载体”。它的版本迭代，不是为了堆砌功能，而是为了匹配学习者认知能力的阶段性跃升。我参与设计的 microduck 路线图，分为三个明确版本，每个版本解决一个核心认知障碍：

5.1 v1.0：物理连接可信（Physical Trust）

目标：建立“插上就能用”的绝对信心。
核心特征：

• 仅支持 USB HID Keyboard 模式（按下按钮，电脑输入字符 'A'）
• 无外部晶振，全靠内部 RC 振荡器（±1% 精度已足够 HID）
• PCB 板载 1 颗 LED + 1 个按钮，无其他外设
• 固件仅 2KB，烧录时间 < 3 秒

v1.0 的价值，在于消灭所有“看不见的失败点”。USB 插上，设备管理器立即显示“HID 键盘”；按下按钮，Notepad 里立刻出现 'A'。这个过程没有任何中间态（如“正在枚举”、“驱动安装中”），失败即表现为“完全无反应”，排查路径唯一：检查 USB 线、检查按钮焊接、检查 LED 限流电阻。它把硬件学习的第一课，锚定在最确定的物理世界。

5.2 v2.0：协议可读（Protocol Readability）

目标：理解“数据如何流动”。
核心升级：

• 增加 UART 调试接口（TX/RX 引出到排针）
• 固件增加printf重定向功能，所有printf("Key pressed!\r\n")输出到串口
• USB 模式扩展为 Composite Device：同时作为 HID Keyboard + CDC ACM Serial
• 提供配套 Python 脚本，实时解析串口日志并可视化按键事件

v2.0 的突破，在于把“黑盒通信”变成“白盒日志”。当你按下按钮，不仅看到 Notepad 输入 'A'，还能在串口助手里看到DEBUG: Button pressed at 12345ms。这让你第一次意识到：HID 报告不是魔法，它是一段结构化的字节数组（uint8_t report[8] = {0, 0, 0x04, 0, 0, 0, 0, 0};），而0x04就是 'A' 的 HID Usage ID。你开始主动查阅 HID Usage Tables 文档，尝试修改报告数组发送 'B'（0x05）或 'Enter'（0x28）。协议，从名词变成了动词。

5.3 v3.0：状态可塑（State Plasticity）

目标：掌握“设备如何记住自己”。
核心升级：

• 增加 24C02 EEPROM 芯片（I²C 接口）
• 固件实现按键次数持久化存储：每次按下，EEPROM 中计数器 +1，重启后继续累加
• USB 模式新增 MSC（Mass Storage Class）：插入后显示为 U 盘，可读写配置文件
• 提供 Web Configurator：microduck 作为 Web Server，通过浏览器修改 LED 闪烁频率、按键映射表

v3.0 的质变，在于引入“状态”概念。之前的版本，设备是无状态的——插上即初始态，拔掉即重置。而 v3.0 让 microduck 拥有了“记忆”。你第一次亲手用HAL_I2C_Mem_Write()写入 EEPROM，用HAL_I2C_Mem_Read()读取，看着计数器从 0 累加到 100，再断电重启依然保持。这种“设备拥有历史”的体验，是嵌入式开发从“控制”迈向“系统”的分水岭。它自然引出更多问题：EEPROM 写寿命有限（100 万次），如何避免频繁写入？Web Server 的 HTTP 解析太占内存，能否用更轻量的 CoAP？——这些问题，就是你走向更高阶开发的路标。

我的体会：microduck 的路线图，本质上是一张“认知地图”。v1.0 解决“我能否信任硬件”，v2.0 解决“我能否理解通信”，v3.0 解决“我能否赋予设备个性”。它不承诺“学完就能年薪百万”，但它保证：当你完成 v3.0，你已经亲手构建了一个具备输入、输出、存储、网络能力的完整嵌入式节点。此时，再去看那些“Java 学习路线图”“产品经理路线图”，你会会心一笑——因为你知道，所有宏大叙事，都始于一个微小的、可触摸的、名叫 microduck 的起点。