5.6 System Modes and Developer Modes

AimDK Developer Mode for AgiBot X2 - By disabling the capabilities of AgiBot’s native system software, it grants users greater system control privileges.

The robot runs in a system mode. After power-on the system automatically migrates through Startup → Ready → Business, settling in Business under steady state. Developers who need to take over certain system capabilities can actively switch into one of the developer modes listed below; switch back to Ready or reboot after development to restore the native functions. This module follows ROS 2 standards, supports both C++ and Python, and provides a unified switching interface for developers.

Mode	Value	Description	Use cases
`Ready`	`Ready`	The ready state after startup completes; subsequently enters `Business` automatically	Switch back to this mode or reboot after development to restore native functions
Interaction Development Mode (Linux)	`Develop_Audio_Linux`	Disable `hal_audio`	Release the occupation of the system audio device. Developers can manually open the `/dev` to handle the raw audio stream.
Interaction Development Mode (ROS)	`Develop_Audio_ROS`	Disable `agent`	Developers can obtain the raw audio stream by subscribing to ROS topics for interactive development.
Navigation Development Mode	`Develop_Nav`	Disable all autonomous capabilities of AgiBot X2, including: navigation, mapping, planning, and perception.	Developers can independently develop the robot’s navigation, mapping, planning, and perception functions.
Motion Control Development Mode	`Develop_MC`	Disable AgiBot X2 native motion control.	Developers can directly send data to the `ethercat` module for full-body robot control.

In addition to the modes above that developers can switch into actively, the system also has the following modes:

Normal operation mode: Business (the steady-state mode entered automatically after startup, where the robot runs its business functions)
High-priority modes (can be entered at any time, take precedence over normal modes, usually triggered automatically by the system; ordinary development workflows do not need to switch them manually):
- EStop (emergency stop): locks the system on entry; can only be exited via EStopRelease
- OTA (upgrade)
- Poweroff (shutdown)
- Reboot (restart)

**Note: After completing development, be sure to switch the robot back to the Ready state or perform a full reboot to ensure exiting developer mode.

5.6.1 Check system status

System State Topic

Topic Name	Data type	Description	QoS	Frequency
`/aima/sm/system_state`	`SmSystemState`	System state (periodic)	`BEST_EFFORT`+`TRANSIENT_LOCAL`	1Hz

Subscribe to the /aima/sm/system_state topic to get the system state. This topic is published periodically at 1 Hz.

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

# System state
# Topic name: /aima/sm/system_state

MessageHeader header                 # Message header
string cur_state                     # Current system mode name (e.g., "Ready", "Develop_Audio_Linux", etc.)
SystemStatus cur_status              # Current system status (cur_status.value:
                                     #   0 (IN_INITIAL initializing)
                                     #   1 (IN_READY ready)
                                     #   2 (IN_MOVE moving)
                                     #   3 (IN_ROLLBACK rolling back)
                                     #   4 (IN_FALLBACK degrading)
                                     #   5 (IN_FALLBACK_MOVE degrading and moving))

Query System Mode Service

Service name	Data type	Description
`/aimdk_5Fmsgs/srv/GetSystemState`	`GetSystemState`	Check system status

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

# Query system state
# Service name: /aimdk_5Fmsgs/srv/GetSystemState

CommonRequest header                 # Request header

---

CommonResponse header                # Response header
string cur_state                     # Current system mode name
SystemStatus curr_status             # Current system status (enum values as above)

5.6.2 Migrate to Develop mode

Service name	Data type	Description
`/aimdk_5Fmsgs/srv/MigrateSystemState`	`aimdk_msgs/srv/MigrateSystemState`	Migrate to Develop mode

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

# Enter developer mode
# Service name: /aimdk_5Fmsgs/srv/MigrateSystemState

CommonRequest header                 # Request header
string state                         # Target system state to switch to

---

CommonResponse header                # Response header

Warning

Asynchronous Semantics

A SUCCESS return from MigrateSystemState only indicates that the migration request has been accepted and started — it does not mean the migration is complete. Module start/stop is executed asynchronously by the system, taking several to tens of seconds.

Already in target mode: If the system is already in the target mode, the service returns SUCCESS (not FAILURE), but the message field will contain a “will skip” prompt.

Recommendation: After calling, poll the GetSystemState service to confirm the migration is complete (cur_state == target mode and curr_status.value == IN_READY).

Querying during migration: While a migration is in progress, GetSystemState still returns the source mode for cur_state; it only switches to the target mode after the migration completes. During this period curr_status.value is IN_MOVE.

Note

Migration Behavior

Restrictions:

Startup-period restriction: During system startup (cur_state is Startup or curr_status is IN_INITIAL), all migration requests are rejected except those targeting high-priority modes (EStop/OTA/Poweroff/Reboot). Calling GetSystemState during this period returns FAILURE; wait for system initialization to complete.
System busy: When the system is in IN_MOVE, IN_FALLBACK_MOVE, or IN_ROLLBACK state, non-high-priority migration requests are rejected.
Insufficient priority: When the system is in a high-priority mode (e.g., EStop), low-priority migration requests are rejected.
EStop lock: After entering EStop mode the system is locked; it can only leave by migrating to EStopRelease. Note: EStop is automatically triggered by the system when an emergency is detected; users cannot trigger it via the SDK.

Mode Transition Rules:

Unconfigured mode: Migration to a mode not configured by the system is rejected.
Model differences: The Develop_* family of developer modes is supported only on the X2 Ultra; the EDU model does not support them.

Migration Behavior:

Auto migration: After startup the system automatically migrates from Startup to Ready, then to Business. Business is the normal operating mode.
Internal module switching: In addition to user-initiated calls, internal modules such as OTA and task management automatically switch the system mode in specific scenarios (e.g., switching to OTA mode before an OTA upgrade).
Migration failure: An abnormal migration enters the FALLBACK state (curr_status.value == IN_FALLBACK); you may retry by sending a new migration request.

5.6.3 Programming example

For detailed programming examples and code explanations, please refer to:

C++ examples: Developer Mode
Python examples: Developer Mode

5.6.4 Technical Details

Note

Field Name Spelling Difference: The field name in topic /aima/sm/system_state is cur_status (single r), while in service /aimdk_5Fmsgs/srv/GetSystemState response it is curr_status (double r). Both have the same semantics but different spellings. Please use the correct field name when programming.

5.6.5 Safety precautions

Warning

Do not use system modes not mentioned in this section.
Mode switching must ensure the robot is in a safe state.
After completing development, be sure to switch back to Ready mode or perform a full system reboot.
The system mode may be automatically switched by internal events: before an OTA update the system switches to OTA mode; when the battery is low it switches to Poweroff mode; a production-test reboot switches to Reboot mode. Monitor Health Diagnostic System (HDS) diagnostic codes and Text-to-Speech (TTS) prompts.