本文档面向初次接触 roboto_motors 的开发者，帮助你建立对项目的整体认知：它是什么、能解决什么问题、适合用在哪些场景，以及代码仓库的组织方式。阅读完本页后，你将能够判断该 SDK 是否匹配自己的硬件栈，并清楚下一步应该阅读哪篇文档。

Sources: README_CN.md

项目定位与核心能力

roboto_motors 是一个面向机器人平台的电机驱动 SDK，基于 C++17 编写，同时通过 pybind11 提供了完整的 Python 接口。它的核心目标是用统一的抽象接口屏蔽不同品牌电机（达妙 DM、EVO、LeadRobot 等）的底层协议差异，让开发者只需调用同一套 API 即可完成初始化、控制指令下发和状态反馈读取。项目采用工厂模式实现多品牌电机的运行时实例化，内部通过 SocketCAN 单例与无锁发送队列完成总线通信，并在架构上预留了 CAN-FD 与 EtherCAT 扩展能力。

Sources: include/motor_driver.hpp

关键特性一览

Sources: src/pybind_module.cpp, CMakeLists.txt, debian/control

支持的硬件与控制模式

当前代码库已完整实现三类电机的驱动层，并在协议层为 CAN-FD 和 EtherCAT 预留了抽象接口。下表汇总了各品牌电机的总线类型、帧格式及可用的控制模式，帮助你快速核对自有硬件是否被支持。

名词解释：MIT 控制模式源自 MIT Cheetah 四足机器人的阻抗控制框架，通过同时下发目标位置、目标速度、位置刚度 kp、速度阻尼 kd 及前馈力矩，实现柔顺的力控效果。若你的场景涉及足式机器人或需要人机协作的柔顺控制，MIT 模式是首选。

Sources: src/motor_driver.cpp, src/drivers/dm/dm_motor_driver.hpp, src/protocol/can_iso.hpp

软件架构概览

项目的架构可以概括为**“三层一横”**：纵向从上到下分为用户 API 层、核心抽象层、通信协议层；横向的电机驱动实现层（DM / EVO / LRO）像插件一样挂接在核心抽象层之下。这种分层设计的好处在于，新增一款电机时，只需在 drivers/ 下增加一个子目录并实现基类虚函数，无需改动上层用户代码。

以下 Mermaid 图展示了模块间的依赖关系与数据流向：

flowchart TB
    subgraph UserLayer["用户接口层"]
        CPP["C++ SDK<br/>include/motor_driver.hpp"]
        PY["Python SDK<br/>motors_py (pybind11)"]
    end

    subgraph CoreLayer["核心抽象层"]
        FACTORY["工厂方法<br/>MotorDriver::create_motor()"]
        BASE["抽象基类<br/>MotorDriver"]
    end

    subgraph DriverLayer["电机驱动实现层"]
        DM["DmMotorDriver"]
        EVO["EvoMotorDriver"]
        LRO["LroMotorDriver"]
    end

    subgraph ProtocolLayer["通信协议层"]
        CAN_ABS["MotorsCAN<br/>抽象接口"]
        CAN_FD_ABS["MotorsCANFD<br/>抽象接口"]
        SOCK["SocketCAN 单例<br/>(lockfree TX 队列)"]
    end

    subgraph HW["硬件总线"]
        BUS_CAN["CAN 2.0<br/>can0 / can1"]
        BUS_CANFD["CAN-FD<br/>(预留)"]
    end

    CPP --> FACTORY
    PY --> FACTORY
    FACTORY --> BASE
    BASE --> DM
    BASE --> EVO
    BASE --> LRO
    DM --> CAN_ABS
    EVO --> CAN_ABS
    LRO --> CAN_ABS
    CAN_ABS --> SOCK
    SOCK --> BUS_CAN
    CAN_FD_ABS --> BUS_CANFD

Sources: include/motor_driver.hpp, src/protocol/can/socket_can.hpp

代码仓库结构

熟悉目录布局是快速定位源码和排查问题的第一步。下图过滤了 CI 与打包脚本，突出显示与开发直接相关的源码路径：

roboto_motors/
├── include/
│   └── motor_driver.hpp              # MotorDriver 抽象基类 + 工厂声明
├── src/
│   ├── motor_driver.cpp              # create_motor() 工厂实现
│   ├── pybind_module.cpp             # Python 绑定模块 motors_py
│   ├── utils.hpp                     # limit、range_map、bitmax、Timer 等工具
│   ├── drivers/
│   │   ├── dm/                       # 达妙 DM 电机驱动（头文件 + 实现）
│   │   ├── evo/                      # EVO 电机驱动
│   │   └── lro/                      # LeadRobot 电机驱动
│   └── protocol/
│       ├── can_iso.hpp               # 经典 CAN 抽象接口
│       ├── canfd_iso.hpp             # CAN-FD 抽象接口
│       ├── ethercat_iso.hpp          # EtherCAT 抽象接口（预留）
│       ├── can/                      # SocketCAN 实现（单例 + 收发线程）
│       └── canfd/                    # CAN-FD Socket 实现
├── cmake/
│   └── roboto_motorsConfig.cmake     # 非 ROS 消费者的 CMake 配置
├── CMakeLists.txt                    # 根构建脚本：依赖、静态库、Python 模块
└── package.xml                       # ROS 2 包描述（ament_cmake）

Sources: src/CMakeLists.txt, src/drivers/CMakeLists.txt

典型适用场景

基于现有的驱动实现与协议特性，roboto_motors 特别适合以下四类场景：

1. 足式 / 轮足机器人
   MIT 阻抗控制模式是四足机器人关节控制的 industry-standard。达妙 DM 与 EVO 电机在该领域应用广泛，SDK 提供的 motor_mit_cmd() 可直接映射为关节力控指令，配合无锁发送队列可满足 1 kHz 级别的控制循环。

2. 协作机械臂与关节模组
   如果你需要位置控制或速度控制来驱动机械臂关节，LeadRobot 与 DM 电机均支持 motor_pos_cmd() 和 motor_spd_cmd()，且 SDK 提供了零位设置、Flash 参数固化、错误清除等调试功能，便于产线部署。

3. ROS 2 机器人系统
   项目原生使用 ament_cmake 构建，可直接作为 ROS 2 workspace 中的一个 package 编译。对于已有 ROS 2 生态的团队，这意味着无需额外维护一套独立的构建系统。

4. 算法快速原型验证
   Python SDK 让强化学习、轨迹规划或 Sim2Real 算法的开发者可以在不编写 C++ 代码的情况下直接操控真实电机，大幅降低从仿真到真机的迁移成本。

Sources: src/utils.hpp

阅读路线图

如果你是初学者，建议按照以下顺序阅读文档，逐步从“能跑起来”过渡到“理解原理”：

1. 先动手：快速开始 → CAN总线接口配置 → 编译依赖与安装
2. 再写代码：Python SDK快速上手 或 C++ SDK快速上手
3. 深入理解：架构总览与模块划分 → MotorDriver抽象基类与接口设计 → 工厂模式与多品牌电机实例化
4. 按需深入：根据你使用的电机品牌，选择性阅读 达妙DM电机驱动详解、EVO电机驱动详解 或 LeadRobot电机驱动详解