# Arduino To Makecode

> 将 DFRobot Arduino 传感器库移植为 micro:bit MakeCode（PXT）扩展。 当用户提到 MakeCode、pxt、积木、micro:bit 扩展、Arduino 转 MakeCode， 或提供 makecode-requirements.md 时使用。仅支持 I2C；源库只有 USART/UART 时停止。 有需求书则按需求书控制积木子集与分组；无需求书则转换全部 I2C 兼容 public API。

- Skill: `jiaziui/arduino-to-makecode` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add jiaziui/arduino-to-makecode`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jiaziui/arduino-to-makecode/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/arduino-to-makecode

---


# DFRobot Arduino → MakeCode（PXT）扩展

将已有 Arduino 库（`.h` / `.cpp`）生成 `pxt-DFRobot_XXX/`。细则见 [conventions.md](conventions.md)。

## 模式选择（I2C 门禁之后立即判定）

| 条件 | MODE | 积木面行为 |
|------|------|------------|
| 用户 `@` 了需求书，或目标仓库根存在 `makecode-requirements.md` | **`requirements`** | 以需求书为应用层唯一规格；只生成白名单积木及其传递依赖 |
| 无需求书 | **`full`** | 全部 I2C 兼容 public API → 公开 `//% block`（默认） |

显式 `@` 附件优先于默认文件名。模板见 [makecode-requirements-template.md](makecode-requirements-template.md)；完整样例见 [makecode-requirements-example-HumanPose.md](makecode-requirements-example-HumanPose.md)。

**`requirements` 硬规则：**

- 未列入需求书白名单的 public API：**不生成**公开积木，也**不默认**生成隐藏 API
- 仅被多个公开积木复用的必要函数，才允许 `blockHidden=true` / 内部 helper
- 缺必填项、引用不存在的 Arduino API、或与 I2C/协议硬约束冲突 → **停止索要**，不静默回退 `full`
- 协议层始终跟当前 `.cpp`；需求书不得虚构 CMD / 帧 / 线值

## 硬门禁（第一步，必须先做）

先确认能否支持 I2C。只有 USART → 结束，不生成文件。

判定（看 `.h` / `.cpp` 用到的总线，**不**凭 `readReg` 函数名）：

| 结论 | 线索 | 动作 |
|------|------|------|
| **有 I2C** | `TwoWire` / `Wire` / `begin(TwoWire` / I2C 地址宏 | 继续；MakeCode **只做 I2C** |
| **只有 USART** | 仅 `Stream` / `HardwareSerial` / `SoftwareSerial` / `Serial`，无 I2C | **停止**。告知：需要 I2C，本库仅 USART，不生成任何文件 |

同时有 UART + I2C：继续，**不移植 UART**。

## 工作流

```
- [ ] 0. I2C 门禁（不通过则结束）
- [ ] 1. 判定 MODE：有需求书 → requirements；否则 full
- [ ] 2. requirements：读全文；输出「需求能力 → 拟积木」表；不足则停止
- [ ] 3. 盘点 public API、CMD、I2C 地址、协议帧（两种 MODE 都做）
- [ ] 4. 创建/更新 pxt-DFRobot_XXX/（pxt.json、protocol/app .ts、_locales、README、test.ts）
- [ ] 5. 协议层从当前 .cpp 直译；总线用 pins.i2cWriteBuffer / i2cReadBuffer
- [ ] 6. 积木层：
        requirements → 仅白名单公开；分组/weight/参数/结果按需求书；必要处 blockHidden
        full → 全部 I2C 兼容 public API → //% block；命名见 conventions
- [ ] 7. locales：公开积木覆盖；**`en` + `zh-cn` 始终生成并列入 `files`**；`zh-tw` 仅 §6 勾选「是」时才生成；生成的每种语言目录与 json **必须真实落盘**
- [ ] 8. README / `test.ts`：按 conventions 生成（需求书不写示例与测试）；README Basic usage 与 `test.ts` 只调用白名单公开积木；full 则 i2cInit + 1～2 典型积木；README 须含 `Supported targets` / `PXT/microbit`
- [ ] 9. **交付前自检（硬）**：逐项核验 `pxt.json` → `files` 每个路径在磁盘存在；**不得多列**不存在的 locale/源码；`files` 合计尽量小于约 64KB（超限则把 `DESIGN.md` / 非必需 md 移出 `files`，仓库可保留）
- [ ] 10. 对照 [checklist.md](checklist.md)；汇报 MODE、对照表、文件列表；确认可用 GitHub URL 作扩展导入
```

不改 Arduino `src/`。已有 `pxt-*` 则 diff 补缺，禁止 git 恢复旧扩展覆盖协议。

## GitHub / MakeCode 导入

扩展要能被 MakeCode「从网址添加扩展」导入，仓库须满足：

- 仓库**根目录**有 `pxt.json`（独立扩展仓，如 `pxt-DFRobot_XXX`）
- `pxt.json` `files` 与仓库文件 **一一对应**：缺文件或列了不存在的路径 → 导入失败
- `supportedTargets` 含 `microbit`；README 保留 `Supported targets` / `PXT/microbit`
- 导入 URL 形如 `https://github.com/<owner>/pxt-DFRobot_XXX`（带不带 `.git` 均可）
- Arduino 主库与 MakeCode 扩展宜分仓；不要把扩展埋在无根 `pxt.json` 的 Arduino 仓里再指望整仓 URL 导入

## 交付

- `pxt-DFRobot_XXX/` 文件列表、I2C 判定依据、MODE
- `full`：API↔积木对照
- `requirements`：需求项→实际积木/内部依赖对照、省略项核对
- `test.ts` 最小示例
- 已做 `pxt.json`↔磁盘存在性自检；可说明 GitHub 导入 URL（若已推送）