RIOT 板卡命名规范解读：RDM3《Board Names for RIOT Boards》设计备忘录全解析

本篇技术指南以 RIOT 官方设计备忘录 doc/memos/rdm0003.md 为核心，系统讲解 RIOT 如何为板卡（Board）分配结构化的"技术名称"与"友好名称"，并辅以当前仓库中 boards/ 目录的源码与文档实证。读完本文，你将掌握 RIOT 板名从厂商命名到 BOARD 变量值（如 adafruit-pybadge、generic-nrf52-dk）的完整推导规则，理解"well-known prefix"、"defining representative"、"Generic 厂商"等关键概念，并能在添加或辨析板卡时准确判断其命名是否合规。

一、什么是 RDM3：一份 RIOT 开发者备忘录

RIOT 通过"RIOT Developer Memos（RDM）"系列记录社区的设计决策与演进方向，其索引维护在 doc/memos/README.md，目前已发布 RDM0（备忘录格式与发布流程）、RDM1（RIOT 设计目标）、RDM2（802.15.4 无线 HAL）与 RDM3（板卡命名）。RDM 在 Pull Request 中成形、被接受后合入。

RDM3 的元数据如下：

字段	值
RDM 编号	3
标题	Board names for RIOT boards
作者	Christian Amsüss
状态	Active
类型	Design
创建时间	2022-09

备忘录在 Status 一节明确指出：本文档是一份草稿，反映了作者的看法。这意味着它描述的是目标状态（target state）——RIOT 尚未立即达到的状态，迁移的技术细节在 RDM 的 Pull Request 中讨论。在出现兼容性重命名机制（如第 4 节 Aliases 所描述的）之前，不应仅为符合本方案而重命名现有板卡，新成员仍可沿用与既有命名惯例一致的家族名。

二、核心术语界定

RDM3 特意不对"board"本身下定义，而是从命名角度给出三个操作性术语：

• 板卡（board）：由同一个 BOARD 变量值构建的一组设备。BOARD 是 RIOT 构建系统中的核心变量，直接决定编译目标与板级配置。
• 技术名称（technical name）：BOARD 变量对应的值，即机器可用的板名。
• 友好名称（friendly name）：文档中展示给人类阅读的名称。
• 定义代表（defining representative）：板卡维护者选定的一块明确硬件，用于承载厂商命名。该概念仅对"包含多个厂商设备"的板卡有意义——典型场景是某板卡存在（未经授权的）克隆，或是开源硬件（Open Hardware）的复刻分支。

三、板卡命名规则：从厂商命名到技术名称

RDM3 的核心是两条命名规则，分别对应友好名称与技术名称，二者都源自定义代表的厂商所指定的名称。

3.1 友好名称（friendly name）

• 厂商名称与产品名称逐字取自厂商，尽可能在 Unicode 范围内保留其风格化写法与大小写，例如 "Arduino"、"PHYTEC"、"micro:bit"、"TRÅDFRI"。
• 厂商名中含"常见于名称但少见用于实际称呼"的成分时会被移除，例如 "Microchip Technology Inc." 简化为 "Microchip"；主要使用自身简称的厂商按其简称称呼（"MikroElektronika d.o.o." 使用 "MIKROE"）。
• 由于厂商常同时使用多个名称（如 "Thunderboard"、"Thunderboard Sense" 与 "SLTB001A" 指向同一产品），选择哪个名称由板卡维护者决定，原则是选择长期可用的名称——营销名往往不合适，因为厂商（如 "Galaxy A7"）可能在后续修订版中不再保留清晰的名称区分。

仓库中可找到直接实证：boards/ikea-tradfri/doc.md 的 @defgroup 标题即为 "IKEA TRÅDFRI modules"，完整保留了厂商名 "IKEA" 与产品名 "TRÅDFRI" 的大小写风格。

3.2 技术名称（technical name）

技术名称将友好名称规约到小写 ASCII 字母、数字与连字符（-） 构成的字符集：

• 一般规则：名称中的空白以连字符替换；
• 精确转换方式由维护者决定，鼓励参考源语言与生态的惯例。例如 "TRÅDFRI" 转为 "tradfri"、"micro:bit" 转为 "microbit"——这两者都遵循了厂商自身在 URI 中的用法（即 Å→a、冒号直接删除）。

3.3 拼接与 well-known prefix 规则

• 友好名称 = 厂商名 空格 产品名；
• 技术名称 = 厂商名 连字符 产品名；
• 若产品名使用了 well-known prefix 列表中的前缀，则厂商名与连接字符从两个名称中同时省略。该 well-known prefix 列表建议作为 RIOT 文档的一部分维护；
• 在厂商自身的语境下（如列出某厂商的全部板卡时），友好名称可省略厂商部分单独使用。

RDM3 特别提醒：名称无法可靠地拆分为"厂商名 + 产品名"，这种拆分只能通过检查板卡的元数据（如果定义了的话）完成——这正是需要维护独立厂商/前缀列表的原因。

四、无固定厂商的板卡：Generic 分类

部分板卡没有清晰的厂商，只是在电商平台上"突然出现"。备忘录给出的例子是 "bluepill" 系列，以及当时被文档记录为 "nRF52 DK" 的板卡。在找到定义代表的、结构良好的厂商之前，这类板卡一律归入 "Generic" 厂商（技术名称："generic"），产品名由维护者根据通行叫法指定。

对于这类板卡，文档中记录指向典型来源（如电商页）的链接是有用的，且优先使用 Wayback Machine 快照（因为来源页面可能不稳定）。

仓库实证：boards/bluepill-stm32f103c8/doc.md 将 bluepill 描述为基于 STM32F103C8 的通用板（其资料指向 stm32-base 等第三方来源），而 boards/generic-cc2538-cc2592-dk/doc.md 开篇即说明该板可从多家厂商购得——这正是 "generic" 前缀的典型用例。

五、官方示例与仓库实证对照

RDM3 用五个示例演示了完整推导，以下逐一与当前仓库对照核实：

5.1 Adafruit PyBadge → adafruit-pybadge

友好名称 "Adafruit PyBadge" 的技术名称为 adafruit-pybadge。该板卡目前还覆盖了 PyBadge LC 与 EdgeBadge 两块设备，但 PyBadge 是定义代表。

仓库实证：boards/adafruit-pybadge/doc.md 确认 PyBadge 由 Atmel SAMD51 驱动，并说明 PyBadge LC 与 EdgeBadge 是差异很小的变体（EdgeBadge 多一个麦克风、PyBadge LC 只有 1 颗 Neopixel），可直接适配现有移植——与备忘录"定义代表 + 变体覆盖"的描述完全吻合。同时该文档给出了实战命令：

make BOARD=adafruit-pybadge -C examples/basic/hello-world flash

5.2 Silicon Labs EFM32GG-STK3700 → silabs-efm32gg-stk3700

该板卡技术名称为 silabs-efm32gg-stk3700，其中 Silicon Labs 的技术名称取 silabs（与其官网一致）。

需要特别说明：这是备忘录的目标状态。当前仓库中 Silicon Labs 的 STK 系列板卡（如 boards/stk3200、boards/stk3700、boards/slstk3701a 等）仍沿用历史名称，尚未迁移到 silabs-* 前缀——这恰好印证了 RDM3"描述的是未即时达成的状态、达成共识前不应仅为合规而重命名"的原则。

5.3 STM32F7508-DK → stm32f7508-dk

"STM" 是 STMicroelectronics 的 well-known prefix，因此技术名称中省略厂商名与连接字符。仓库中确实存在 boards/stm32f7508-dk 目录，且 STM32 家族大量板卡（stm32f746g-disco、stm32f4discovery、nucleo-f103rb 等）都遵循这一约定。

5.4 BBC micro:bit v2 → bbc-microbit-v2

"BBC" 是 Micro:bit Educational Foundation 为其板卡使用的 well-known prefix（这一名称源于 BBC Education 主导的初始项目）。仓库中 boards/microbit-v2/doc.md 的 @defgroup 标题正是 "BBC micro:bit v2"，且说明该板由 BBC 设计、于 2020 年发布，基于 Nordic nRF52833。

5.5 Generic nRF52 DK → generic-nrf52-dk

对于无固定厂商的 nRF52 开发板，技术名称为 generic-nrf52-dk，从而与 Nordic Semiconductor 官方的 "nRF52 DK"（well-known prefix 命名，nrf52-dk，对应仓库中的 boards/nrf52dk）明确区分。

六、命名规范的落地场景：构建系统与板级文档

RDM3 指出，结构化命名是为了方便板卡发现（discovery）、避免用户被宣传板名误导。命名规则在 RIOT 中的实际落地体现在：

• 构建系统：BOARD 变量贯穿编译、烧录全流程，如 5.1 节的 make BOARD=adafruit-pybadge ... flash。技术名称的字符集约束（小写 ASCII + 数字 + 连字符）保证其可作为 Makefile 变量值与文件系统目录名安全使用——boards/ 下的每个子目录名即对应一个 BOARD 值。
• 板级文档：每块板的 doc.md 使用 @defgroup boards_<board> <Friendly Name> 形式声明 Doxygen 分组，友好名称直接进入 API 文档与 Doxygen 搜索。
• 板卡选购指南：boards/doc.md 的 "Popular Boards" 表格（如 @ref boards_microbit_v2、@ref boards_adafruit-feather-nrf52840-sense）以友好名称展示推荐板卡，而引用锚点使用技术名称，正是两种名称分工的日常体现。

七、别名（Aliases）：未来的迁移机制

备忘录设想了别名的四种用途，但别名的具体实现机制超出本文范围：

1. 作为板卡重命名的过渡机制；
2. 以新厂商的名义收录克隆/复刻板卡；
3. 消除对 well-known prefix 规则的依赖；
4. 在必须重命名时提供兼容路径。

当前仓库中 boards/bluepill-stm32f103c8 与 bluepill-stm32f103cb 这类"家族内多板并存"的形态，正体现了过渡期"新成员可沿用既有命名惯例"的现实需求。

八、总结与使用建议

RDM3 为 RIOT 板卡命名确立了清晰的推导链：厂商定义代表命名 → 保留风格化友好名称 → 规约出技术名称 → well-known prefix 或 Generic 分类处理特例。给开发者的实操建议可归纳为：

• 新增板卡时，优先采用定义代表厂商在产品资料/URI 中使用的名称形态；
• 无厂商板卡统一使用 generic- 前缀，产品名取通行叫法；
• 在出现兼容别名机制前，不要仅因合规而重命名存量板卡；
• 需要区分克隆板与官方板时，注意 generic-* 与官方 well-known prefix 命名的差异（如 generic-nrf52-dk vs nrf52-dk）。

该备忘录的修订记录仅含 Rev0（初始文档），作者邮箱为 [e-mail]，并致谢了 Kaspar Schleiser、Alexandre Abadie、Marian Buschsieweke、Koen Zandberg、Martine Lenders 与 Benjamin Valentin 的评审意见——这些信息在 doc/memos/rdm0003.md 末尾均有记录，感兴趣的读者可进一步查阅原始文本。