Skip to main content

Software Architecture

This guide maps the AI Worker software environment: the robot PC, SSD storage, source repositories, Docker containers, startup services, and ROS 2 communication and control.

System Overview​

AI Worker runs its ROS 2 software in the ai_worker Docker container on the robot PC. The container uses host-mounted source and workspace directories, runs the robot drivers and controllers, and exchanges commands and state through ROS 2 with Zenoh RMW. An external PC can join that ROS 2 network for operation and visualization.

AI Worker system overview: User PC, Zenoh router, host storage, Docker container, and robot hardware.AI Worker system overview: User PC, Zenoh router, host storage, Docker container, and robot hardware.

Host Environment​

The host OS runs on the Jetson. The container OS and ROS workspace belong to each Docker image. Keep these environments separate when checking versions or installing development dependencies.

Host componentSG2 / BG2 environment
JetPack6.2
Jetson Linux36.4.3
Host OSUbuntu 22.04-based root filesystem

Storage & Directory Layout​

SSD and Docker Storage​

The robot's SSD is mounted at /mnt/ssd using its UUID in /etc/fstab. Docker's data-root is set to /mnt/ssd/docker in /etc/docker/daemon.json.

These storage relationships serve different purposes:

RelationshipReference pathsPurpose
SSD filesystem mountSSD device → /mnt/ssdMakes the SSD filesystem available to the host
Docker data directory/mnt/ssd/dockerDocker-managed image and container storage
Host repository bind mounts/mnt/ssd/ai_worker → ~/ai_worker
/mnt/ssd/cyclo_intelligence → ~/cyclo_intelligence
Makes SSD-backed repositories available in the home directory

Host Directory Map​

The following map shows the robot's repository locations and their host bind mounts.

  • ai_worker: Robot control and teleoperation software based on ros2_control.
  • cyclo_intelligence: Data recording, preparation, training guidance, and model inference.
/mnt/ssd/
├── ai_worker/ AI Worker repository
└── cyclo_intelligence/ Cyclo Intelligence repository

~/
├── ai_worker/ Bind mount of the SSD repository
└── cyclo_intelligence/ Bind mount of the SSD repository

Container Volume Map​

Paths below are relative to the host checkouts shown above. ~ denotes the account that owns the checkout. Actual checkout paths may differ if the containers were started from another location.

Host pathContainer pathPurpose
~/ai_worker/root/ros2_ws/src/ai_workerRobot source code
~/ai_worker/docker/workspace/workspaceRobot workspace files
~/cyclo_intelligence/root/ros2_ws/src/cyclo_intelligenceCyclo Intelligence source code
~/cyclo_intelligence/docker/workspace/workspaceCyclo Intelligence workspace files
~/cyclo_intelligence/docker/huggingface/root/.cache/huggingfaceHugging Face cache
/dev/devAccess to hardware devices
/dev/shm/dev/shmShared memory for processes
/tmp/.X11-unix/tmp/.X11-unixConnect GUI apps to the X11 server
/tmp/.docker.xauth/tmp/.docker.xauthAuthentication for the X11 server

The two /workspace paths belong to different host directories. A file in the ai_worker workspace is not automatically in the Cyclo Intelligence workspace.

warning

Files stored only in a container's writable layer are lost when the container is removed. Store important files in host-mounted directories. Host files remain available when the container is recreated as long as those files are retained.

Inspect mounts and data locations

On the robot host:

lsblk -f
findmnt /mnt/ssd
findmnt -T "$HOME/ai_worker"
findmnt -T "$HOME/cyclo_intelligence"
docker info --format '{{.DockerRootDir}}'
docker inspect --format '{{.Name}} {{json .Mounts}}' ai_worker cyclo_intelligence

For the complete device, display, ZED, configuration, and SDK mounts, inspect the reviewed robot Compose file and learning Compose file.

Containers & Services​

Container Inventory​

ContainerFunction
ai_workerRobot ROS workspace, hardware drivers, and robot/leader services
cyclo_managerManagement API and Docker/agent coordination
cyclo_manager_uiManagement web UI
zenoh_daemonZenoh router; Compose service name is rmw_zenoh
novnc-serverOptional remote desktop and GUI tools
cyclo_intelligenceImitation learning application

Management and Application Endpoints​

EndpointReference port / pathUsed for
SSHTCP 22Robot-host terminal
Cyclo Manager UI / APITCP 3000 / 8081Browser operation and API
Cyclo Intelligence UITCP 7080Imitation learning web UI
noVNCTCP 8090Optional GUI tools
Zenoh routerTCP 7447 in the external-PC connection exampleCross-host ROS communication
Container/host agentsUnix sockets under /var/run/robotis/agent_socketsLocal management; not a separate browser port

Control Flow​

Control Architecture​

The following diagram shows the AI Worker ROS 2 control structure. The controller update rate is configured at 100 Hz; mobile-base components apply to mobile models.

ROS 2 control structure

Why ros2_control?​

ros2_control separates controllers from hardware drivers, manages command/state interfaces, and provides the controller lifecycle used by the robot launch files. The configured controllers and their joint lists come from the selected model profile.

Motion Execution Pipeline​

Motion execution from leader, AI policy, or VR inputs through ROS 2 controllers to DYNAMIXEL actuators, with joint-state feedback and camera or LiDAR sensor input.Motion execution from leader, AI policy, or VR inputs through ROS 2 controllers to DYNAMIXEL actuators, with joint-state feedback and camera or LiDAR sensor input.

AI Worker controller profiles configure a 100 Hz update rate. That is a configuration target, not a measurement of timing on every robot. The ROS middleware transports messages; the controller loop and hardware interface handle joint execution.

Step-by-Step​

  1. A leader, AI policy, or VR workflow produces commands for the selected robot.
  2. ROS 2 transports command messages through the configured RMW and Zenoh network.
  3. The selected controllers consume their command interfaces in the read → update → write loop.
  4. The hardware interface and SDK exchange commands and state with the actuators.
  5. Joint states and sensor topics return to the operation, visualization, and recording workflows.

Controller Configuration & Joint Mapping​

The reviewed follower launch remaps the standard trajectory inputs to these topic names. The two arms below include the standard one-joint grippers; optional hands use their matching configuration. Mobile-base control applies to SG2/W2.

ControllerRoleReference topic
arm_l_controllerLeft arm and standard gripper/leader/joint_trajectory_command_broadcaster_left/joint_trajectory
arm_r_controllerRight arm and standard gripper/leader/joint_trajectory_command_broadcaster_right/joint_trajectory
head_controllerHead pan/tilt/leader/joystick_controller_left/joint_trajectory
lift_controllerVertical lift/leader/joystick_controller_right/joint_trajectory
joint_state_broadcasterJoint state feedback/joint_states
swerve_drive_controllerSG2/W2 mobile base/cmd_vel in the operation workflow

Controller YAML Example​

Minimal controller-manager and left-arm configuration

This is an illustrative extract with a single /** parameter scope. It omits other controllers and model-specific parameters; use the complete source profile for deployment.

/**:
controller_manager:
ros__parameters:
use_sim_time: False
update_rate: 100 # Hz

arm_l_controller:
type: joint_trajectory_controller/JointTrajectoryController

arm_r_controller:
type: joint_trajectory_controller/JointTrajectoryController

head_controller:
type: joint_trajectory_controller/JointTrajectoryController

lift_controller:
type: joint_trajectory_controller/JointTrajectoryController

joint_state_broadcaster:
type: joint_state_broadcaster/JointStateBroadcaster

swerve_drive_controller:
type: ffw_swerve_drive_controller/SwerveDriveController

arm_l_controller:
ros__parameters:
joints:
- arm_l_joint1
- arm_l_joint2
- arm_l_joint3
- arm_l_joint4
- arm_l_joint5
- arm_l_joint6
- arm_l_joint7
- gripper_l_joint1
command_interfaces:
- position
state_interfaces:
- position
- velocity
allow_nonzero_velocity_at_trajectory_end: true

Debugging & Safety​

Debugging & Visualization Tools​

Tool / TopicDescription
ros2 control list_controllersList loaded controllers and their status
/joint_statesReal-time joint position and velocity feedback
RViz23D view of robot model (URDF), TF, and movement

Safety & Fault Handling​

Joint limits, controller constraints, and hardware communication error handling depend on the selected robot configuration and software version. These mechanisms do not replace the robot's emergency stop or the operating precautions in Setup Hardware.

Middleware​

AI Worker uses ROS 2 Jazzy with Zenoh RMW for communication between robot-side nodes, Docker containers, and external PCs. ROS 2 provides the application interfaces; rmw_zenoh_cpp and the router provide the configured communication layer.

What is rmw_zenoh?​

rmw_zenoh is the ROS 2 RMW (ROS Middleware) implementation for Zenoh. The implementation package is rmw_zenoh_cpp, and it maps the ROS 2 middleware API onto Zenoh APIs. Existing ROS 2 publishers, subscribers, services, clients, parameters, and command-line tools can keep using normal ROS 2 interfaces while Zenoh handles discovery and transport.

Zenoh is a pub/sub/query protocol designed to move data efficiently across local processes, robot networks, edge computers, and cloud systems. For AI Worker, this means the robot control software can use normal ROS 2 topics while Zenoh provides a lightweight communication layer that is easier to route across containers and hosts than multicast-heavy DDS discovery.

Main Components​

ComponentRole
rmw_zenoh_cppROS 2 RMW implementation selected by RMW_IMPLEMENTATION=rmw_zenoh_cpp.
rmw_zenohdZenoh router executable packaged with rmw_zenoh_cpp. It provides discovery information and host-to-host routing.
Zenoh sessionCommunication session used internally by ROS 2 contexts. Publishers, subscribers, services, and clients share the session.
Zenoh router configurationControls how routers listen, connect, and bridge communication between containers, the robot, and remote PCs.

How Communication Works​

  • ROS 2 nodes continue to publish and subscribe to normal topics such as /joint_states, /tf, or controller command topics.
  • rmw_zenoh_cpp converts the ROS 2 middleware calls into Zenoh operations.
  • A local Zenoh router is normally started so nodes can discover each other.
  • On the same host, message data can use direct peer-to-peer paths instead of forcing every sample through the router.
  • Across multiple hosts, configure the external PC container as a Zenoh client connected to the robot's Zenoh router endpoint.

External PC Control​

An external PC can communicate with the robot's ROS 2 nodes by connecting its Zenoh client to the robot's Zenoh router. For connection settings and verification, see External ROS 2 Communication.