一，综述
EngineAI ROS 包：
- 高层开发模式：用户可通过发布身体速度指令，直接调用 EngineAI 机器人的行走控制器。
- 底层开发模式：用户可通过发布关节指令，自主开发专属的控制器。
- ROS2 package：全称为 “Robot Operating System 2 Package”（机器人操作系统 2 功能包），是 ROS2 生态中用于组织代码、配置文件等资源的基本单元，便于模块化开发与复用。
- body velocity command：“身体速度指令”，通常包含机器人在三维空间中的线速度（如前后、左右移动速度）和角速度（如转向速度），是高层控制中常用的指令类型，无需用户关注单个关节的运动细节。
- joint command：“关节指令”，针对机器人单个或多个关节的控制指令（如目标角度、角速度等），底层开发模式下用户需通过该指令精确控制关节运动，以实现自定义动作或控制逻辑。
二，接口协议
| Topic/Service Name | Type | Rate | Message | Description | DataStructure |
|---|---|---|---|---|---|
| /hardware/gamepad_keys | Topic Publish | >=500hz | GamepadKeys.msg | Gamepad Message Feedback | # Timestamp field using ROS2 header uint8 LT = 0 std_msgs/Header header # Digital buttons (0 = released, 1 = pressed) # Analog inputs (range: -1.0 to 1.0) |
| /hardware/imu_info | Topic Publish | >=500hz | IMUInfo.msg | IMU Sensor Feedback | std_msgs/Header header geometry_msgs/Quaternion quaternion geometry_msgs/Vector3 rpy geometry_msgs/Vector3 linear_acceleration geometry_msgs/Vector3 angular_velocity |
| /hardware/joint_state | Topic Publish | >=500hz | JointState.msg | Joint Status Feedback | std_msgs/Header header float64[] position float64[] velocity float64[] torque |
| /hardware/joint_command | Topic Subscription | 0~500hz | JointCommand.msg | Joint Command Subscription | std_msgs/Header header float64[] position float64[] velocity float64[] feed_forward_torque float64[] torque float64[] stiffness float64[] damping uint8 parallel_parser_type |
| /motion/motion_state | Topic Publish | >=5hz | MotionState.msg | Motion Status Feedback of Robot | string current_motion_task |
| /hardware/motor_debug | Topic Publish | >=50hz | MotorDebug.msg | Feedback of Temperature, Tau, etc. | float64[] tau_cmd float64[] mos_temperature float64[] motor_temperature |
| /motion/body_vel_cmd | Topic Publish | >=5hz | BodyVelCmd.msg | body velocity command publish, linear_x_vel ranges [-0.5m/s +0.5m/s] linear_y_vel ranges [-0.2m/s, +0.2m/s]， yaw_vel rangs [-0.5rad/s, 0.5rad/s] | std_msgs/Header header
|
| /heartbeat | std_msgs/Header header string node_name int64 startup_timestamp # idle, running, error, sleep int64 error_code string error_message | ||||
| /enablemotor | serve | EnableMotor.srv | bool enable --- bool success string message |
三，工作区架构及编译环境
└── src├── interface_example # Interface examples, recommended to run on Nezha├── interface_protocol # Interface protocols, common modules├── third_party # Third-party libraries├── simulation # Simulation environment running on host- Ubuntu 22.04
- ROS2 Humble Desktop
- GCC >= 11
- CMake >= 3.22
- Python >= 3.10
四，FSM 三个模式：操纵杆模式，高层开发模式，底层开发模式
操纵杆模式、高层开发模式和底层开发模式的有限状态机（FSM）
操纵杆状态机
注意：LB+CORSS_Y_LEFT 是切入 joint commands即低层开发控制
高层开发模式
Body Velocity Control
底层开发模式
底层开发（Low-level Development）允许用户使用基于 EngineAI 开源强化学习（RL）训练框架（仓库地址：https://github.com/engineai-robotics/engineai_gym）训练的自定义强化学习控制器。用户可按照以下步骤逐步操作，实现基于 Mujoco 模拟器的 “仿真到仿真”（sim2sim）功能及实际部署。
五，部署操作：
在主机上运行 rl_basic_example 程序
步骤 1：进入 PD 站立模式（pd-stand mode）
- 确保机器人稳固放置在平整地面上，且周围有足够操作空间；
- 使用遥控器进入 PD 站立模式；
- 继续操作前，请确认机器人已稳定站立。
步骤 2：进入关节桥接模式（joint bridge mode）
关节桥接模式支持通过关节指令对机器人进行控制，操作步骤如下：
- 当机器人处于 PD 站立模式时，按下遥控器的【LB 键 + 左十字键 Y 向（CROSS_Y_LEFT）】组合键；
- 机器人将进入关节桥接模式，此时可通过关节指令对其进行控制；
- 执行以下命令验证机器人状态：
bash
# 在主机端执行 ros2 topic echo /motion/motion_state - 继续操作前，请确认运动状态（motion state）显示为 “joint_bridge”。
步骤 3：运行强化学习（RL）示例程序
安全警告（SAFETY WARNING）
- 确保所有人员与机器人保持安全距离；
- 若机器人出现异常动作，请随时准备紧急停止（可按下急停按钮或使机器人进入被动模式）。
启动示例程序 执行以下命令启动示例程序：bash
# 在主机端执行
ros2 launch interface_example rl_basic_example.launch.py六，编译
几个脚本梳理：
1）同步代码到板级
在主机（host） 端执行以下命令：./scripts/sync_src.sh nezha
（说明：“nezha” 指 “哪吒” 目标板，是该机器人系统适配的硬件设备；sync_src.sh为代码同步脚本，用于将主机端的开发代码传输到目标板，确保两端代码一致性。）
2）构建工作空间
首先通过 SSH 连接到哪吒板（Nezha board），并进入工作空间目录：
cd ~/source/engineai_workspace
（说明：~/source/engineai_workspace是代码在目标板上的默认工作空间路径，cd命令用于切换到该目录。）
然后执行构建脚本，编译节点代码：
./scripts/build_nodes.sh
（说明：build_nodes.sh是用于编译机器人功能节点的脚本，“nodes” 指 ROS 2 框架中的 “节点”，是实现具体功能的可执行单元，编译后生成可运行的程序文件。）
3)运行 PlotJuggler 进行数据监控
在主机（host） 端编译interface_protocol功能包：
# in host
colcon build --packages-select interface_protocol
（说明：colcon是 ROS 2 的官方构建工具，--packages-select interface_protocol表示仅编译 “interface_protocol” 这一个功能包，该包通常包含机器人的数据通信协议相关代码。）
source install/setup.bash
（说明：source命令用于加载脚本文件，install/setup.bash是编译后生成的环境配置脚本，加载后主机才能识别并运行后续的 ROS 2 程序。）
ros2 run plotjuggler plotjuggler -n
（说明：ros2 run用于启动 ROS 2 功能包中的可执行程序，-n是 PlotJuggler 的参数，全称 “--no-config”，表示不自动加载之前保存的配置文件，便于用户重新选择需监控的数据话题。）
src/interface_protocol/pm_data_layout.xml
（说明：“layout file”（布局文件）包含数据图表的排列、待监控的话题选择等配置，加载后无需手动设置即可直接查看预设的机器人关键数据，如关节角度、电机电流等。）
check_format.sh
使用场景
这个脚本通常会集成到 CI/CD 流程中，在代码提交或 PR 创建时自动运行，确保提交的代码符合项目的格式规范。也可以在开发过程中手动运行，提前发现并修复格式问题。
依赖工具
脚本需要以下工具在系统中可用：
- clang-format (用于 C/C++ 格式化)
- yamllint (用于 YAML 文件检查)
- autopep8 (用于 Python 格式检查)
- git (用于检查文件变更)
如果需要修改检查规则，可以相应调整各工具的配置文件（如.clang-format、.yamllint 等）。
七，代码解析
interface_example
hold_joint_status.cc
joint_test_example.cc
rl_basic_example.cc
simulation
)
