Setup Guide for AI Worker

This guide will walk you through the process of setting up your AI Worker hardware and software environment.

Hardware Setup

INFO

• The term Follower refers to the body of the AI WORKER robot
• Please check the type of robot you are using.

Powering On the FFW_BG2 Follower

1. Toggle the Power Supply Switch to the right.
2. Insert the Key Switch and turn it to the 12 o'clock position.
3. Press and hold the Power Button for 3 seconds. When you hear a beep, the system is powered on. (You should see the robot’s head light up at this point.)

Hardware Ports (FFW_BG2 Follower)

The back of the Follower body includes several ports for system access and external connections. These include:

• LAN Port: Used to access the robot PC via SSH or remote desktop.

• USB Ports: For connecting peripherals such as a keyboard, mouse, or USB drive.

• HDMI Port: Allows direct video output for connecting a monitor.

Accessing the Robot PC via SSH

AI Worker supports mDNS, allowing you to connect without manually checking the IP address.

1. Connect the SBC (robot PC) to the same network as your user PC using a LAN cable.

2. On your user PC terminal, use the following command to connect via SSH:

 ssh robotis@ffw-SNPR48A0000.local

Replace SNPR48A0000 with the serial number printed on the back of the robot body.

Software Setup

AI WORKER relies on two main repositories:

• ai_worker: Provides support for controlling DYNAMIXEL actuators using ros2_control and enables teleoperation functionality.
• physical_ai_tools: A set of tools for imitation learning, including data collection, training, model inference, and visualization utilities.

The software setup instructions below are intended for development on a user PC. Note that the robot PC on the AI WORKER is already pre-configured with the same setup.

DANGER

⚠️ On the AI Worker Orin: Do not run apt upgrade command. Upgrading packages may cause conflicts and break robot functionality.

Prerequisites

• Operating System: Ubuntu environment
  (The AI WORKER software runs inside a Docker container based on Ubuntu 24.04 (ROS 2 Jazzy). Therefore, the Ubuntu version of the user PC does not need to match and is not critical.)
• Container Engine: Docker Engine
  • Follow the official Docker installation guide
  • Complete the post-installation steps
  • Required steps:
    1. Install Docker Engine using the repository method
    2. Add your user to the docker group
    3. Enable Docker to start on boot
    4. Verify installation with docker run hello-world
• Version Control: Git
• Graphics Support:
  • NVIDIA Graphics Driver
    (In Docker-based environments, the container is generally isolated from the host system. However, the graphics driver version on the host can have a direct impact on performance and compatibility—especially when using GPU acceleration. We recommend using the following driver version(s) for best results)
    • Install nvidia-driver-570-server-open for CUDA 12.8
    • Verify installation with nvidia-smi
  • NVIDIA Container Toolkit
    • Follow the official installation guide
    • Required steps:
      1. Configure the production repository
      2. Install nvidia-container-toolkit
      3. Configure Docker runtime using nvidia-ctk
      4. Restart Docker daemon
    • For detailed configuration, see the Docker configuration guide

---

Configuration

Docker Volume Management

The Docker container uses the following volume mappings for data persistence and hardware access:

volumes:
  # Hardware and System Access
  - /dev:/dev                    # Hardware device access
  - /tmp/.X11-unix:/tmp/.X11-unix:rw  # X11 display
  - /tmp/.docker.xauth:/tmp/.docker.xauth:rw  # X11 authentication

  # Development and Data Storage
  - ./workspace:/workspace       # Main workspace directory
  - ../:/root/ros2_ws/src/ai_worker/  # AI Worker source code
  - ./lerobot/outputs:/root/ros2_ws/src/physical_ai_tools/lerobot/outputs  # Model outputs
  - ./huggingface:/root/.cache/huggingface  # Hugging Face cache

⚠️ Important: Data Persistence

• Container data is volatile and will be lost when the container is removed
• Always store important data in the mapped volumes:
  1. Use /workspace for development files
  2. Save model outputs to the mapped output directory
  3. Keep source code changes in the mapped ai_worker directory
  4. Store downloaded models in the huggingface cache

Container Management

1. Initial Setup

   # Clone the repository
   cd ~/  # or your preferred directory
   git clone -b jazzy https://github.com/ROBOTIS-GIT/ai_worker.git
   cd ai_worker

2. Container Operations

   # Start container
   ./docker/container.sh start
   
   # Enter running container
   ./docker/container.sh enter
   
   # Stop container
   ./docker/container.sh stop

Docker Command Guide

The container.sh script provides easy container management:

Available Commands

• help: Display help message
• start: Start container
• enter: Enter running container
• stop: Stop container

Usage Examples

./container.sh help                 # Show help
./container.sh start                # Start container
./container.sh enter                # Enter container
./container.sh stop                 # Stop container

SW Update Guide

Follow these steps to update AI Worker or Physical AI Tools packages:

• Navigate to package directory

cd /path/to/ai_worker_package
# or
cd /path/to/physical_ai_tools_package

• Switch to jazzy branch

git checkout jazzy

• Update to latest code

git pull

• Restart container

./docker/container.sh stop
./docker/container.sh start

WARNING

Data in areas without volume mapping will be lost during container restart. Make sure to save important data before restarting.