2. Software System Overview

2.1 Basic Startup Mode

The robot's industrial control system consists of the MDU, HDU, and ADU. All of them run Ubuntu 24.04 and use systemd as the system service manager. At startup, the PM (Process Manager) and SM (State Manager) modules are launched first, and then PM and SM cooperate to start the remaining module processes. SM manages the enabling and disabling of process lists under different system modes. The configuration file paths for PM and SM are /agibot/software/v0/entry/launch/A3_ULTRA_DEFAULT.yaml (HDU, MDU, and ADU, with the yaml name varying by model) and agibot/software/v0/config/sm/sm_config.yaml (MDU). The former lists the default processes to start, while the latter specifies which functional groups are enabled in each system mode.

2.2 Module Function Overview

Module Type	Controller	Module Name	Description
Management Module	MDU	SM	Responsible for switching system states and managing process lists
	MDU & HDU & ADU	PM	Responsible for launching processes and querying process status
Public Service	MDU & HDU & ADU	setting	Provides basic robot controller settings such as WiFi and Bluetooth
		recordbag	Used for continuously recording bag files
		ota_service	Software update tool
	MDU	gateway	Forwards external requests to internal modules
	HDU	data_exporter	Provides batch log export and time-range log export functions
Functional Module	HDU	hal_audio	Audio hardware abstraction layer
		hal_hdu_camera	HDU camera hardware abstraction layer
		hal_imu	Hardware IMU abstraction layer
	MDU	hal_ethercat	Responsible for EtherCAT communication with the HDU, transmitting hardware status information and control commands
		hds	Health management module
		mc	Responsible for overall robot motion control and issuing motion-control commands
		motion_player	Provides motion playback capability
		skillpilot	Skill management module
		tf	Coordinate transformation service
	ADU	agivslam	AGI visual SLAM localization module
		embodied_agent	Unified management of robot interaction capabilities
		hal_depth_camera	HAL depth camera interface
		hal_lidar	HAL LiDAR interface
		hal_sipl	HAL NVIDIA SIPL camera framework interface
		legged_odometry	Legged odometry, providing leg motion state estimation
		mm	Map management module
		pnc	Planning and control module
		slam	SLAM navigation and localization module

2.2.1 System Modes

The modules activated and started in each system mode differ, as shown below (excerpt from sm_config.yaml):

python

  # System States
  system_modes:
    "Startup":
      next_mode_list: [ "Ready", "OTA", "Poweroff" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]

    "Poweroff":
      next_mode_list: []
      active_FG_list: []
      action_list:
        - [ open Poweroff ]

    "Reboot":
      next_mode_list: []
      active_FG_list: []
      action_list:
        - [ open Reboot ]

    # System ready state, will start business management modules and HAL
    "Ready":
      next_mode_list: [ "Manual", "EStop", "Poweroff" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ activate agent ]
        - [ activate motion_player ]
      # post_process:
      #   - level: 34
      #     action_list: [ [ forbid Manual ] ]

    # OTA state, will start the OTA functional group to complete OTA-related functions
    "OTA":
      next_mode_list: [ "Reboot", "Ready", "Poweroff" ]
      active_FG_list: [ "System", "HAL", "MoCap", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ deactivate agent ]
        - [ activate mc ]
        - [ deactivate motion_player ]

    # Manual state, will start remote control and MC functional groups
    "Manual":
      next_mode_list: [ "OTA", "Auto", "Reset", "EStop", "Poweroff", "MotionStream", "DataCollection", "FreeExploration", "Mapping", "Manipulator", "Lock" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ activate agent ]
        - [ activate mc ]
        - [ activate motion_player ]
      child_modes:
        - mode_name: "Safety"  # State entered by calling the enable script under tools
          extra_next_modes: [ "OTA", "Reset" ]
          action_list:
            - [ close Motion ]
            - [ close EStop ]
      post_process:
        - level: 47
          action_list: [ [ fallback mc ] ]
    
    # Lock state
    "Lock":
      next_mode_list: [ "Manual" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ deactivate agent ]
        - [ activate mc ]
        - [ deactivate motion_player ]
      post_process:
        - level: 47
          action_list: [ [ fallback mc ] ]

    # Reset state, used to restore factory settings
    "Reset":
      next_mode_list: [ "Reboot", "Poweroff" ]
      active_FG_list: [ "System", "OTA", "Gateway" ]
      action_list:
        - [ DIFF ]

    # Emergency stop state, used for emergency stop
    "EStop":
      next_mode_list: [ "Ready", "OTA", "Poweroff" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ activate agent ]
        - [ deactivate mc ]
        - [ activate motion_player ]

    # Real-time teleoperation state, used for real-time teleoperation
    "MotionStream":
      next_mode_list: [ "Manual", "EStop", "Poweroff", "DataCollection" ]
      active_FG_list: [ "System", "HAL", "EStop", "MoStream", "Gateway", "Motion", "OTA" ]
      action_list:
        - [ DIFF ]
        - [ activate recordbag0 ]
        - [ activate recordbag1 ]
        - [ activate agent ]
        - [ activate mc ]

  decision: # System decision layer
    Auto_transToReady: true  # If false, you need to call the one-click activation script at the appropriate time
    Auto_transToManual: true
    type: 1

2.2.2 Module Disabling Method (Caution)

If you need to replace certain functional modules for secondary development, you need to configure the system to disable those modules.

Modules are managed by either A3_ULTRA_DEFAULT.yaml or sm_config.yaml. Modules managed by the former are started by default at boot and are not managed by sm afterwards, remaining resident; modules managed by the latter are switched between different system modes.

To disable modules managed by A3_ULTRA_DEFAULT.yaml (that is, some entries in default_apps), simply remove them from default_apps.
To disable modules managed by sm, add a deactivate line in the corresponding system mode to disable the specified module.
Before making any changes, back up A3_ULTRA_DEFAULT.yaml and sm_config.yaml in the relevant directory.

For example, to disable the motion_player module, follow these steps: First, back up A3_ULTRA_DEFAULT.yaml (MDU) and sm_config.yaml.

bash

cp /agibot/software/v0/entry/launch/A3_ULTRA_DEFAULT.yaml \
   /agibot/software/v0/entry/launch/A3_ULTRA_DEFAULT_backup.yaml

cp /agibot/software/v0/config/sm/sm_config.yaml \
   agibot/software/v0/config/sm/sm_config_backup.yaml

In A3_ULTRA_DEFAULT.yaml (MDU), remove the motion_player module from the default_apps list:

diff

@@ -22,7 +22,6 @@ process_manager:
     "health_monitor0",
     "recordbag0",
-      "motion_player",
     "hds",
     "setting0",
     "mc",
     # "pnc",
     # "uwb_fusion",
     "hal_ethercat",
     "hal_elink",
     "skillpilot",
     "ota_master",
     "gateway",
     "ota_service0",

Then in sm_config.yaml (MDU), remove motion_player from the group in SystemManagerModule, set MoCap config to empty, and remove activate/deactivate operations for motion_player in each state:

diff

@@ -14,7 +14,7 @@ SystemManagerModule:
-      group: [motion_player, mc, hal_ethercat, poweroff0, reboot0, setting0, recordbag0, health_monitor0, hds, gateway, ota_master, ota_service0]
+      group: [mc, hal_ethercat, poweroff0, reboot0, setting0, recordbag0, health_monitor0, hds, gateway, ota_master, ota_service0]

diff

@@ -36,7 +36,7 @@ SystemManagerModule:
   "RC":
     [ "rc" ]
   "MoCap":
-      [ "motion_player" ]
+      []
   "MoStream":
     [ "motion_streamer" ]

diff

@@ -78,7 +78,6 @@ SystemManagerModule:
  "Ready":
    next_mode_list: [ "Manual", "EStop", "Poweroff" ]
    active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
    action_list:
      - [ DIFF ]
      - [ activate recordbag0 ]
      - [ activate recordbag1 ]
-      - [ activate motion_player ]
@@ -93,7 +93,6 @@ SystemManagerModule:
  "OTA":
    next_mode_list: [ "Reboot", "Ready", "Poweroff" ]
    active_FG_list: [ "System", "HAL", "MoCap", "Gateway", "Motion", "OTA" ]
    action_list:
      - [ DIFF ]
      - [ activate recordbag0 ]
      - [ activate recordbag1 ]
      - [ deactivate agent ]
      - [ activate mc ]
-      - [ deactivate motion_player]
@@ -105,7 +105,6 @@ SystemManagerModule:
  "Manual":
    next_mode_list: [ "OTA", "Auto", "Reset", "EStop", "Poweroff", "MotionStream", "DataCollection", "FreeExploration", "Mapping", "Manipulator", "Lock" ]
    active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
    action_list:
      - [ DIFF ]
      - [ activate recordbag0 ]
      - [ activate recordbag1 ]
      - [ activate agent ]
      - [ activate mc ]
-      - [ activate motion_player ]
@@ -126,7 +126,6 @@ SystemManagerModule:
  "Lock":
    next_mode_list: [ "Manual" ]
    active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
    action_list:
      - [ DIFF ]
      - [ activate recordbag0 ]
      - [ activate recordbag1 ]
      - [ deactivate agent ]
      - [ activate mc ]
-      - [ deactivate motion_player ]
@@ -148,7 +148,6 @@ SystemManagerModule:
  "EStop":
    next_mode_list: [ "Ready", "OTA", "Poweroff" ]
    active_FG_list: [ "System", "HAL", "EStop", "MoCap", "Gateway", "Motion", "OTA" ]
    action_list:
      - [ DIFF ]
      - [ activate recordbag0 ]
      - [ activate recordbag1 ]
      - [ activate agent ]
      - [ deactivate mc ]
-      - [ activate motion_player ]