一，綜述
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
??????????
)
