RCU 教育机器人（E6RCU / E7RCU）的 C/C++ 声明层与 API 目录：完整接口声明、机器可读的接口数据与可复跑的生成工具链。（MIT）

RcuBasicLibrary

RCU 教育机器人的 C/C++ 声明层与 API 目录

RcuBasicLibrary 为 RCU 教育机器人（E6RCU / E7RCU）提供一套标准、可读、可维护的 C/C++ 开发接口：以一组声明头文件呈现完整的设备 API，并附带机器可读的接口数据清单与一套可复跑的生成工具链。

借助本项目，开发者可以脱离图形化 IDE，使用标准 Arm GNU 工具链与任意编辑器或 IDE 直接为 RCU 编写 C/C++ 程序。

特性

完整的接口声明 —— 覆盖执行、光电、触碰、传感器、内置、显示、无线等全部模块；平台差异（E6RCU / E7RCU）以编译期分支显式表达，不做掩盖
机器可读的数据真源 —— Registry/ 以 CSV / TXT 记录接口元数据（签名、模块归属、参数范围、符号面等），便于二次开发与工具集成
可复跑的生成链 —— Tools/VendorGen/ 由数据真源重生成全部声明头，结果可复现、可校验
标准工具链 —— 不依赖特定 IDE，兼容 CMake / Make 等任意构建系统

支持平台

平台	MCU	内核	编译选项
E6RCU	STM32F407VGT6	Cortex-M4F	`-mcpu=cortex-m4 -mthumb -mfpu=fpv4-sp-d16 -mfloat-abi=hard`
E7RCU	STM32H743ZIT6	Cortex-M7	`-mcpu=cortex-m7 -mthumb -mfpu=fpv5-d16 -mfloat-abi=hard`

两平台在函数集合与参数取值范围上并不相同：部分接口仅在其中一平台可用，同一函数的参数上下限也可能不同。差异是编译期可见的事实，请勿以「统一签名」将其掩盖。各平台参数取值范围见 Registry/RcuVendorParamRange.csv。

快速开始

1. 安装工具链

安装 Arm GNU Toolchain （arm-none-eabi- 前缀），确保 arm-none-eabi-gcc 可在命令行调用。

2. 准备 SDK

从 RoboEXP 发行包中提取所需的 SDK 文件（头文件与预编译对象）：

python Tools/VendorFetch/FetchVendorSdk.py --roboexp "<RoboEXP 安装目录>"

--roboexp 接受发行包根目录或其 Robots 子目录
脚本按 Tools/VendorFetch/manifest.json 逐文件校验 SHA256，任何不一致即中止，不会留下未校验的半成品目录
默认输出到 VendorSDK/（可用 --sdk-out 指定其他路径），结构为 VendorSDK/<RCU>/{Include,o,Library}
--verify-only 仅做一致性校验，不写入任何文件

3. 引入声明头

将 Include/ 加入头文件搜索路径：

-I <本项目路径>/Include

然后包含汇总入口：

#include "RcuVendor/RcuVendorApi.h"

按目标平台定义 RSCY_TARGET_E6RCU 或 RSCY_TARGET_E7RCU（二者选其一）。

4. 链接

将目标平台的预编译对象加入链接：

VendorSDK/E6RCU/o/*.o    或    VendorSDK/E7RCU/o/*.o

并将 VendorSDK/<RCU>/Include 一并加入头文件搜索路径。跨二进制边界的符号名由对象文件单方面规定，改名即断链；这些边界已在 RcuVendorFrozenAbi.h 与 Platform/RcuVendorContract*.h 中显式登记。

目录结构

RcuBasicLibrary/
├── Include/
│   └── RcuVendor/                    接口声明头
│       ├── RcuVendorApi.h            汇总入口（包含下列各模块头）
│       ├── RcuVendorPerformer.h      执行模块
│       ├── RcuVendorLightSensor.h    光电传感器
│       ├── RcuVendorTouchSensor.h    触碰传感器
│       ├── RcuVendorOtherSensor.h    其它传感器
│       ├── RcuVendorBuiltIn.h        内置模块（存储、音量、电源等）
│       ├── RcuVendorDisplay.h        显示模块
│       ├── RcuVendorWireless.h       无线模块
│       ├── RcuVendorInternal.h       内部与共用符号
│       ├── RcuVendorTypes.h          公共类型与常量
│       ├── RcuVendorState.h          状态
│       ├── RcuVendorFrozenAbi.h      冻结 ABI 边界登记（不可改名的符号）
│       ├── RcuVendorSharedVars.h     跨模块共享变量的平台入口
│       ├── RcuVendorSharedVars-E6RCU.h
│       ├── RcuVendorSharedVars-E7RCU.h
│       └── Platform/
│           ├── RcuVendorContractE6.h E6RCU 冻结 ABI 契约
│           └── RcuVendorContractE7.h E7RCU 冻结 ABI 契约
├── Registry/                         接口数据真源（CSV / TXT）
├── Tools/
│   ├── VendorGen/                    声明头生成器（11 个脚本，可复跑）
│   └── VendorFetch/                  SDK 获取工具
│       ├── FetchVendorSdk.py         获取脚本
│       ├── manifest.json             文件清单（文件名 + SHA256）
│       └── seeds/                    辅助文件
├── LICENSE
├── NOTICE.md
└── README.md

Include/RcuVendor/ 下的模块头与辅助头均由 Tools/VendorGen/ 从 Registry/ 数据生成；Platform/ 下的两个契约头为手工维护的声明，用于登记「不可改名的 ABI 边界」。

数据真源（Registry/）

Registry/ 记录接口的客观元数据：函数名与签名、模块归属、命名映射、符号名、行号范围、参数取值范围、生成产物清单等，是本项目唯一的数据真源。

当数据与工具输出不一致时，以 CSV 为准——CSV 是真源，工具是消费者。

主要文件：

RcuVendorApi.csv —— 函数 → 模块 / 帕斯卡名映射
RcuVendorSymbols.csv —— 符号面
RcuVendorParamRange.csv —— 各平台参数取值范围
RcuVendorRename.csv —— 命名映射表
RcuVendorBlocks-* / RcuVendorFunctions-* / RcuVendorClosure-* —— 分平台的块 / 函数 / 闭包
_DefSymbols-* / _UndefSymbols-* / _VendorTuSymbols-* —— 符号面实测
_GeneratedManifest-* —— 生成产物清单
RcuVendorDeadCode-* —— 死代码清单

生成与复现

Tools/VendorGen/ 提供可复跑的生成链：由 Registry/ 数据重生成 Include/ 下的声明头，并附带一致性校验。生成结果由数据与工具完全决定，任何人可独立复现。

如需在生成的头文件中包含中文接口说明，将 SDK 中的 JMlib.xml 一并准备好—— 生成器会自动探测 <sdk-root>/<RCU>/Include/JMlib.xml，也可用 --jmlib-xml 显式指定：

python Tools/VendorGen/GenerateVendorLayer.py --sdk-root "<VendorSDK 路径>" --out "<输出目录>"

许可

本项目以 MIT 许可发布；许可范围与第三方内容声明详见 LICENSE 与 NOTICE.md。

RcuBasicLibrary:基于 C/C++ 的 RCU 教育机器人基础库项目