ttwards/mambo

English

Mambo 是一个面向机器人下位机开发的 Zephyr RTOS 模块。项目通过设备树描述电机、底盘、传感器、通信接口等硬件关系，并提供对应的驱动、协议库和样例程序。

项目结构

• boards/: 自定义开发板定义。
• dts/bindings/: 驱动和模块使用的设备树绑定。
• drivers/: 电机、底盘、传感器、VCAN、SBUS 等 Zephyr 驱动。
• lib/ares/: ARES 通信、协议、IMU 算法和板级辅助库。
• samples/: 可直接构建的示例应用。
• template/: 新应用模板。
• Documents/: 设计说明和专项文档。

整体结构可参考 structure.png，设备树描述示例可参考 example.dts。

环境准备

以下命令以 Ubuntu 22.04/24.04 为例：

sudo apt update
sudo apt install --no-install-recommends git cmake ninja-build gperf \
  ccache dfu-util device-tree-compiler wget \
  python3-dev python3-pip python3-setuptools python3-tk python3-wheel \
  xz-utils file make gcc gcc-multilib g++-multilib libsdl2-dev libmagic1

建议在虚拟环境中安装 West 和 Zephyr 的 Python 依赖：

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip wheel
python3 -m pip install west

如果本机已有受管理的 Python 环境，也可以使用等价的 venv、pipx 或系统包管理方案；建议避免把 Zephyr 构建依赖混入全局 Python 环境。

初始化工作区

west init -m https://github.com/ttwards/mambo --mr master my-workspace
cd my-workspace
west update
west zephyr-export
python3 -m pip install -r zephyr/scripts/requirements.txt
west sdk install -t arm-zephyr-eabi

初始化完成后，工作区根目录包含以下项目目录：

• mambo/: 当前 manifest repository。
• zephyr/: west.yml 固定的 Zephyr 源码。
• modules/hal/cmsis/
• modules/hal/cmsis_6/
• modules/lib/cmsis-dsp/
• modules/hal/st/
• modules/hal/stm32/
• modules/debug/segger/
• bootloader/mcuboot/

west sdk install -t arm-zephyr-eabi 只安装当前 ARM Cortex-M 目标所需的 GNU 工具链。需要构建其他架构时，再按 Zephyr SDK 文档补充对应 toolchain。

构建与烧录

构建 Robomaster Board C 上的 DJI M3508 示例：

cd mambo
west build -b robomaster_board_c samples/motor/dji_m3508_demo

烧录：

west flash

默认 runner 取决于开发板配置。需要指定调试器时可使用：

west flash --runner stlink
west flash --runner jlink

其他样例可按相同方式构建，例如：

west build -b dm_mc02 samples/motor/dm_demo
west build -b robomaster_board_c samples/vcan/vcan_host_demo

开发工具

项目提供 pre-commit 配置和 GitHub Actions CI。首次开发前建议安装 hooks：

./setup-precommit.sh

手动运行检查：

pre-commit run --all-files

VS Code 示例配置位于 VSC_sample_configs/。贡献流程和提交规范见 CONTRIBUTING.md。

Codex Skill

仓库在 skills/mambo 内置了面向 Mambo 的 Agentic Embedded Skill，用于指导 Codex 配置 Mambo/Zephyr 环境、编写最小可验证程序，并通过 DM-MC02、CMSIS-DAP、AresPlot 和串口采集工具进行安全调试。

从仓库根目录将 Skill 链接到个人 Codex 技能目录：

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "$PWD/skills/mambo" "${CODEX_HOME:-$HOME/.codex}/skills/mambo"

安装后可通过 $mambo 调用。默认使用新生模式，以简单中文逐步解释并核对构建、接线和运行证据；明确说“专家模式”或“老手模式”后，才会切换为更精简的批量诊断。两种模式都不会在未授权时烧录固件、连接调试探针或启用执行器电源。

Skill 同时提供只读 AresPlot CSV 采集、按时间区间绘图、JSON 配置示例和 DM-MC02 V1.1 使用说明书，详见 skills/mambo/references 与 skills/mambo/scripts。

文档

• 文档入口：Documents/README.md
• 模块参考：Documents/modules.md
• 公共 API 参考：Documents/api-reference.md
• 设备树参考：Documents/devicetree-reference.md
• CI 与测试：Documents/tests/README.md
• Motor 架构：Documents/motor/architecture.md
• 样例使用说明：各 samples/**/README.*