# Create Dfrobot Arduino Lib

> 根据封库需求文档生成 DFRobot Arduino 库。需求假定目标库尚不存在； 含协议规格与能力清单，不必列全 API。当用户写封库需求、requirements.md 时使用。

- Skill: `jiaziui/create-dfrobot-arduino-lib` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add jiaziui/create-dfrobot-arduino-lib`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiaziui/create-dfrobot-arduino-lib/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jiaziui (https://skillmd.com/u/jiaziui)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jiaziui/create-dfrobot-arduino-lib

---


# 根据封库需求生成 DFRobot Arduino 库

**前提**：用户提供的 `requirements.md` 是**唯一规格**——编写需求时**没有**目标库的 `src/`、`.h`、成品代码。  
**输入**：§3 协议 + §4 能力（见 [requirements-template.md](requirements-template.md)）。  
**输出**：可发布的 DFRobot Arduino 库。  
**样例**：[requirements-example-C4002.md](requirements-example-C4002.md) 仅为**一份**封库前规格示例；其它产品复制 [requirements-template.md](requirements-template.md) 填写，**不得**把 C4002 的 CMD/枚举/方法名当作通用默认值。

## 设计原则

1. **只读需求与 §3 附件**，禁止引用或 git 恢复待生成库源码；`python_src`、既有 `src/` 均不是依据  
2. **§3 协议** → 底层实现、CMD、**每条命令的 payload 字节布局**、枚举**线值**、多步命令序列  
3. **§4 能力** → public API（Agent 推导命名，§5 可覆盖）；**§4.6 业务说明** → 各 API 的 Doxygen **`@n` 续行**；**§3 协议** → `.h` 中宏/`enum`/`struct` 的 Doxygen（见 [conventions.md](conventions.md)）  
4. §3 不足以实现 → **停止并索要**，不猜协议；**禁止**用 C 枚举序号、数组下标或「常见写法」代替 §3 线值  
5. §4.6 未写但某 API 明显需要 `@n`（阈值特殊值、重启生效、位图含义等）→ **停止并索要**，禁止只写 `@brief` 敷衍  
6. **封库日期**：§1 未填「发布日期」→ 用**生成当天**；版本号来自 §1（默认 `V1.0.0`），见 [conventions.md](conventions.md)  
7. **§5 有填写** → public API 命名/签名必须与 §5 一致；**§5 留空** → 按 DFRobot 惯例推导，**不要求**与仓库内其它成品库同名  
8. **按 §2 定主通信接口与类结构**：见 [conventions.md](conventions.md)；§3 只用于协议实现，不定类架构  
9. **外设对象由用户注入**：见 [conventions.md](conventions.md)「外设对象注入」  
10. **多接口示例一份业务逻辑**：见 [conventions.md](conventions.md)「多接口示例固定模板」；单接口不生成选择宏  
11. **§3 为 `Modbus RTU`** → 按下方 Protocol Resolution 加载公共库，禁止重写 CRC / 帧 / 功能码  

**交付物须含 `README.md` 与 `README_CN.md` 两个文件**（见 [conventions.md](conventions.md) README 节）。工作流第 7 步写「README」时**不得**只生成英文一份。

### Protocol Resolution

实现前必须读取需求 **§3 协议类型**：

| §3 协议类型 | 动作 |
|-------------|------|
| **`Modbus RTU`**（精确匹配） | 加载 [references/modbus-rtu/conventions.md](references/modbus-rtu/conventions.md) + [DFRobot_RTU.h](references/modbus-rtu/DFRobot_RTU.h)；底层用已安装的 `DFRobot_RTU`；**禁止**重新实现 Modbus RTU |
| 仅 `Modbus`，或 `Modbus TCP` / `Modbus ASCII` 等 | **停止**，要求明确是否为 Modbus RTU |
| I2C / SPI / 自定义 UART 帧等 | **不**加载 `references/modbus-rtu/`，不引用 `DFRobot_RTU` |

用户只需声明协议，**不必**填写 `Dependency: DFRobot_RTU`。  
若 §2 主接口为 I2C/SPI 而 §3 为 Modbus RTU：**停止并列冲突**，不得猜。

### §3 必须写清的内容（通用）

| 缺什么 | 常见后果 |
|--------|----------|
| 仅列 CMD 名、不写 data 布局 | 组帧长度/字段顺序错误 |
| 枚举只写含义、不写线值 | `0/1/2` 与 `0x01/0x02/0xFF` 混用 |
| 多步命令只写一步 | 恢复出厂、改波特率等流程不完整 |
| 「各门/各通道」未说明批量还是逐条 | API 形态与模块不符 |

## 工作流

```
- [ ] 1. 读 §1–§2、§4–§8：按 §2 定主通信接口与类结构（见 [conventions.md](conventions.md)）；解析日期/版本；确认 §5（若有）与 §7 产品图
- [ ] 2. 读 §3（及 @ 附件）：整理 CMD/帧/寄存器/上报；核对 payload 与枚举线值；**不够则停止索要，不进入第 3 步**；做 **Protocol Resolution**（仅 `Modbus RTU` 才加载 [references/modbus-rtu/](references/modbus-rtu/)）
- [ ] 3. 输出「§4 → 拟 public 方法」表（§5 有则不得偏离）
- [ ] 4. 输出「方法 → 拟 `@n`」表（对照 §4.6 + 下方强制 `@n` 模板）
- [ ] 5. 按 [conventions.md](conventions.md) 实现类结构与外设注入（Modbus RTU：继承/组合 `DFRobot_RTU`，见 conventions）
- [ ] 6. 实现 public + `begin()`；`.h` 注释与 Doxygen 按 [conventions.md](conventions.md)
- [ ] 7. 生成 examples、library.properties、keywords.txt、**README.md + README_CN.md**、resources/images/（示例与 README 按 [conventions.md](conventions.md)；§6 主示例含完整配置链；Modbus RTU 时 `depends=DFRobot_RTU`）
- [ ] 8. **逐条执行** [checklist.md](checklist.md)；缺项补齐后再交付
```

### 强制 `@n` 模板（§4.6 未写时也须写入 `.h` 与 README Methods）

| API 类型 | 必须有的 `@n` |
|----------|----------------|
| 通知缓存 getter（§4.4 解析后的 `getXxx`） | 「须先 `getNoteInfo`（或 §4.4 等价入口）」；数据来自哪类通知 |
| 环境光/同类阈值 setter | 为 0 的特殊行为；非 0 时的触发条件；范围与单位 |
| 改波特率 / 恢复出厂 / 会重启模块的写命令 | 模块重启或生效条件；主机侧须同步的操作 |
| 位图/数组类返回值 | 各 bit 或长度与当前模式（分辨率/档位）的关系 |
| 枚举 `@param` | 每个可选值一行 `@n` 或等价说明 |

### 交付前门禁（通用封库）

- **禁止** README 引用不存在的 `resources/images/…`；§7 无图 → **向用户索要**或 README 暂不放图片行，不得留断链  
- **禁止**示例接线表与代码引脚不一致  
- **禁止**仅 init 的 §6 主示例（通常为 `getAllResults` 或需求指定的第一个示例）
- 类结构、外设注入、多接口示例：按 [conventions.md](conventions.md)；需求对主接口冲突或无法判断时**停止并列出冲突**，不得猜

## 能力 → API（推导规则）

| §4 | 推导 |
|----|------|
| 4.1 初始化 | `begin()` |
| 4.2 每项配置 | `setXxx` / `configureXxx` / `startXxx` |
| 4.3 每项读取 | `getXxx`；缓存型数据配合通知解析 |
| 4.4 事件 | `getNoteInfo` 或等价入口 + 解析 §3.3 |
| 4.5 内部 | protected / private |

## Agent 禁止

- 读取「对照用」的既有 `src/DFRobot_XXX.*` 来补全需求缺口  
- 因仓库里已有同名库而跳过生成或只做 diff  
- 把 §3 未定义的内容当作已实现  
- 把某一产品（如 C4002）的 API 命名、枚举名、示例结构套用到其它 SKU  
- 违背 [conventions.md](conventions.md) 类结构 / 外设注入 / 多接口示例（常见错：板型串口变体当多种主接口、GPIO 当主接口、库内硬编码 `Wire`/`SPI`/`Serial`、按接口复制示例或把 `setup()`/`loop()` 塞进每个分支）