5.6 系统模式与开发者模式

智元机器人X2 AimDK开发者模式 - 通过停用智元本身系统软件的能力，给用户让渡更多系统控制权限

机器人运行在某个系统模式下。开机后系统自动经历 Startup（启动）→ Ready（就绪）→ Business（正常运行）的迁移，稳态下处于 Business 模式。开发者如需接管部分系统能力，可主动切入下表中的开发者模式；完成开发后切回 Ready 或重启即可恢复原生功能。该模块遵循ROS 2标准，支持C++和Python两种编程语言，为开发者提供统一的切换接口。

模式	取值	说明	使用场景
`Ready`	`Ready`	开机启动完成后的就绪状态，随后自动进入 `Business`	开发完成后切回此模式或重启，可恢复原生功能
交互开发模式（Linux）	`Develop_Audio_Linux`	停用智元`hal_audio`节点	解除对系统音频设备的占用，开发者可以自行打开`/dev`节点，处理原生音频流
交互开发模式（ROS）	`Develop_Audio_ROS`	停用智元`agent`节点	开发者可以通过订阅ros topic的方式获得原声音频流，进行交互开发
自主开发模式	`Develop_Nav`	停用智元全部的自主能力，包括：导航、建图、规划、感知	开发者可以自行开发机器人的导航、建图、规划、感知功能
运控开发模式	`Develop_MC`	停用智元原生运动控制	开发者可以直接给`ethercat`模块发送数据进行机器人全身控制

除上述可由开发者主动切入的模式外，系统还存在以下模式：

正常运行模式：Business（开机后自动进入的稳态模式，机器人正常运行业务功能）
高优先级模式（可随时切入，优先级高于普通模式，通常由系统自动触发，普通开发流程无需主动切换）：
- EStop（急停）：进入后锁定系统，仅能通过 EStopRelease 退出
- OTA（升级）
- Poweroff（关机）
- Reboot（重启）

**注意: 完成开发后，务必将机器切换回Ready 状态，或者整机重启，确保脱离开发者模式。

5.6.1 查询系统状态

系统状态话题

话题名称	数据类型	描述	QoS	频率
`/aima/sm/system_state`	`SmSystemState`	系统状态（周期发布）	`BEST_EFFORT`+`TRANSIENT_LOCAL`	1Hz

订阅 /aima/sm/system_state 话题，获取系统状态。该话题以 1Hz 频率周期发布。

SmSystemState ros2-msg @ sm/msg/SmSystemState.msg

# 系统状态
# 话题名称: /aima/sm/system_state

MessageHeader header                 # 消息头
string cur_state                     # 当前系统模式名称（如 "Ready", "Develop_Audio_Linux" 等）
SystemStatus cur_status              # 系统当前情况（cur_status.value：
                                     #   0 (IN_INITIAL 初始化中)
                                     #   1 (IN_READY 就绪)
                                     #   2 (IN_MOVE 迁移中)
                                     #   3 (IN_ROLLBACK 回退中)
                                     #   4 (IN_FALLBACK 降级中)
                                     #   5 (IN_FALLBACK_MOVE 异常迁移中)）

查询系统模式服务

服务名称	数据类型	描述
`/aimdk_5Fmsgs/srv/GetSystemState`	`GetSystemState`	查询系统模式

GetSystemState ros2-srv @ sm/srv/GetSystemState.srv

# 查询系统状态
# 服务名称: /aimdk_5Fmsgs/srv/GetSystemState

CommonRequest header                 # 请求头

---

CommonResponse header                # 响应头
string cur_state                     # 当前系统模式名称
SystemStatus curr_status             # 系统当前情况（枚举值同上）

5.6.2 进入开发者模式

服务名称	数据类型	描述
`/aimdk_5Fmsgs/srv/MigrateSystemState`	`aimdk_msgs/srv/MigrateSystemState`	进入开发者模式

MigrateSystemState ros2-srv @ sm/srv/MigrateSystemState.srv

# 进入开发者模式
# 服务名称: /aimdk_5Fmsgs/srv/MigrateSystemState

CommonRequest header                 # 请求头
string state                         # 请求切换的系统状态

---

CommonResponse header                # 响应头

警告

异步语义说明

MigrateSystemState 返回 SUCCESS 仅表示迁移请求已被接受并开始执行，不表示迁移已完成。实际模块启停由系统异步执行，耗时数秒至数十秒。

已在目标模式：如果当前已在目标模式，服务返回 SUCCESS（非 FAILURE），但 message 字段会包含 “will skip” 提示跳过。

建议：调用后通过轮询 GetSystemState 服务确认迁移完成（cur_state == 目标模式 且 curr_status.value == IN_READY）。

迁移期间查询：迁移过程中 GetSystemState 返回的 cur_state 仍为源模式，直到迁移完成才会切换为目标模式；期间 curr_status.value 为 IN_MOVE。

备注

迁移行为说明

限制条件：

启动期：系统启动期间（cur_state 为 Startup 或 curr_status 为 IN_INITIAL），除高优先级模式（EStop、OTA、Poweroff、Reboot）外，其余迁移请求均被拒绝。此阶段调用 GetSystemState 服务会返回 FAILURE，需等待系统初始化完成。
系统繁忙：当前处于 IN_MOVE、IN_FALLBACK_MOVE 或 IN_ROLLBACK 状态时，非高优先级迁移请求会被拒绝。
优先级不足：当前处于高优先级模式（如 EStop）时，低优先级迁移请求会被拒绝。
EStop 锁定：进入 EStop 模式后系统被锁定，仅能迁移到 EStopRelease 离开。注意：EStop 由系统在检测到紧急情况时自动触发，用户无法通过 SDK 主动触发。

模式切换规则：

未配置模式：迁移到系统未配置的模式会被拒绝。
机型差异：Develop_* 系列开发模式仅旗舰版支持，人人造不支持。

迁移行为：

自动迁移：系统启动后自动从 Startup 迁移到 Ready，再迁移到 Business。Business 为正常运行模式。
内部模块切换：除用户主动调用外，OTA、任务管理等内部模块在特定场景下会自动切换系统模式（如 OTA 升级前切入 OTA 模式）。
迁移失败：迁移异常会进入 FALLBACK 态（curr_status.value == IN_FALLBACK），系统会自动检测目标模式条件是否满足并尝试恢复。用户也可主动重新发起迁移请求。

5.6.3 编程示例

详细的编程示例和代码说明请参考：

C++ 示例：进入开发者模式
Python 示例：进入开发者模式

5.6.4 技术细节

备注

字段名拼写差异：话题消息 /aima/sm/system_state 中字段名为 cur_status（单 r），服务 /aimdk_5Fmsgs/srv/GetSystemState 响应中为 curr_status（双 r），两者语义相同但拼写不一致。编程时请注意使用正确的字段名。

5.6.5 安全注意事项

警告

请勿使用本节未提及的系统模式
模式切换需要确保机器人处于安全状态
完成开发后务必切换回Ready或者进行整机重启
系统模式可能被内部事件自动切换：OTA 升级前会自动切换到 OTA 模式，电池电量不足时会自动切换到 Poweroff 模式，生产测试重启会切换到 Reboot 模式。请关注健康诊断系统（HDS）诊断码和语音播报（TTS）提示