Setup Guide

Flash Jetpack to microSD

I recommend Jetpack 5.x (e.g. 5.1.5 as of May 2025) — Jetpack 6.x has caused WiFi card issues. Image: Jetpack SDK 5.1.5.

Format the SD card with the SD Association formatter, then flash with Balena Etcher. Alternatively use NVIDIA SDK Manager (native Ubuntu or VMware Workstation VM with enough disk and USB passthrough to the Jetson).

Replace WiFi card

The default card does not support roaming (needed for mesh). Use an Intel AC9260 on the bottom of the Jetson (screwdriver).

First boot

Power on with a monitor, connect to Wi‑Fi so you can SSH in.

Basic packages

sudo apt update
sudo apt install nano

SPI on 40-pin header (MCU)

cd /opt/nvidia/jetson-io
sudo python3 jetson-io.py

Manually configure the header: activate SPI1 and I2S. Reboot when done.

Load spidev at boot

The Jetson must load the spidev kernel module at boot for MCU communication over SPI. Use spidev_setup.sh from the Jetson directory in the Robot repo (run on the Jetson host, outside Docker):

cd ~
wget "https://raw.githubusercontent.com/satomm1/Robot/main/Jetson/spidev_setup.sh"
chmod +x spidev_setup.sh
sudo ./spidev_setup.sh

The script writes spidev to /etc/modules-load.d/spidev.conf, loads the module immediately if possible, and backs up any existing config. Reboot when prompted, then verify:

sudo reboot
# after reboot:
ls /dev/spidev*

Serial / USB (optional)

If /dev/ttyUSB0 has issues: sudo apt remove brltty

Wiring

Jetson ↔ main board (SPI1)

Connect the main board’s 6-position Molex (first five positions) to the Jetson 40-pin header with dupont wires. Match SPI1 on the Jetson to the PCB labels:

Full main-board wiring (motors, power, buttons) is in the Electrical README.

Jetson ↔ microphone board (I2S2)

Use the PIC32 board’s 6-pin connector (not the 5-pin header). Set the switch to the upward position. Connect to Jetson I2S2 (pin numbers may vary with your header config):

Microphone assembly, PIC32 firmware, and Jetson audio software: Microphone README and mattbot_record (noetic).

Pull pre-built ml_ros image

On the Jetson, after Docker is installed:

docker pull ghcr.io/satomm1/ml_ros:latest

Verify:

docker images ghcr.io/satomm1/ml_ros:latest

No docker login is required — the package is public on GHCR. To refresh after an image update, run docker pull ghcr.io/satomm1/ml_ros:latest again.

Start the container (example):

sudo docker run --runtime nvidia --network=host -v ~/workspaces/catkin_ws:/workspace/catkin_ws -v ~/gemini_api:/gemini_code -v /dev/bus/usb:/dev/bus/usb -v /dev/video0:/dev/video0 -v /dev/video1:/dev/video1 -it --device=/dev/ttyUSB0 --device=/dev/spidev0.0 --rm --privileged --name ros_noetic ghcr.io/satomm1/ml_ros:latest

Inside the container: source /opt/ros/noetic/setup.bash

ROS workspace

cd /workspace/catkin_ws
mkdir -p devel src
catkin_make
source devel/setup.bash
cd src

Inside the container, download and run clone_repos.sh from the /workspace/catkin_ws/src directory. It clones the mattbot packages and third-party ROS repos (all on the noetic branch) and downloads robot_env.sh, startup_script.py, and cyclonedds.xml:

cd /workspace/catkin_ws/src
wget "https://raw.githubusercontent.com/satomm1/Robot/main/Jetson/clone_repos.sh"
chmod +x clone_repos.sh
./clone_repos.sh

Repositories cloned: mattbot_bringup, mattbot_dds, mattbot_record, mattbot_image_detection, mattbot_mcl, mattbot_navigation, mattbot_teleop, mattbot_database, ros_astra_camera, rplidar_ros, twist_mux, slam_gmapping.

cd /workspace/catkin_ws
catkin_make
source devel/setup.bash

Configure Cyclone DDS peer discovery in cyclonedds.xml (downloaded by clone_repos.sh above). This file disables multicast and uses an explicit peer list for WiFi mesh discovery:

nano /workspace/catkin_ws/src/cyclonedds.xml

You must update the <Peer Address="…"/> entries so they list the actual IP addresses of every robot and device that should participate in DDS discovery on your network:

• Include this Jetson’s IP address (the same value you set for ROS_IP in robot_env.sh).
• Add the IP addresses of any other robots or machines running ROS on the mesh.
• Remove any placeholder entries that do not correspond to a real device.

The default file assumes the wlan0 interface; change <NetworkInterface name="…"/> only if your WiFi interface has a different name (run ip link or ifconfig to check).

Edit robot_env.sh with this Jetson’s IP address, robot ID, MCU SPI number, camera type, and robot height. CYCLONEDDS_URI is already set to point at cyclonedds.xml — leave that line unchanged unless you move the file.

nano /workspace/catkin_ws/src/robot_env.sh

Replace the placeholder values on these lines (leave export and the variable names unchanged):

export ROS_IP=              # this Jetson's WiFi IP address
export ROBOT_ID=              # unique integer for this robot (match MCU robot ID)
export MCU_SPI=               # 1 or 3 — SPI used for MCU comms (SPI1 on header → usually 1)
export CAMERA_TYPE=           # astra_pro_plus, astra, or astra_pro
export ROBOT_HEIGHT=          # short or tall
export ROBOT_CAR=             # true for car configuration, false otherwise

Use the arrow keys to move the cursor. Type each value after the =. Save and exit nano: Ctrl+O, Enter, then Ctrl+X.

Add these lines to ~/.bashrc so ROS and robot settings load in every shell:

nano ~/.bashrc

Append at the bottom of the file:

source /workspace/catkin_ws/devel/setup.bash
source /workspace/catkin_ws/src/robot_env.sh

Save and exit nano (Ctrl+O, Enter, Ctrl+X), then reload:

source ~/.bashrc

Test with roscore. For the Astra camera, outside the container:

cd ~/workspaces/catkin_ws/src/ros_astra_camera
./scripts/create_udev_rules
sudo udevadm control --reload && sudo udevadm trigger

Save changes (with container running):

sudo docker commit ros_noetic ghcr.io/satomm1/ml_ros:latest

This tag matches the Jetson host service and GHCR image name.

Gemini container (optional)

Pull the pre-built image from GitHub Container Registry (ghcr.io/satomm1/gemini:latest). No docker login is required — the package is public on GHCR.

docker pull ghcr.io/satomm1/gemini:latest

Verify:

docker images ghcr.io/satomm1/gemini:latest

To refresh after an image update, run docker pull ghcr.io/satomm1/gemini:latest again.

Clone the API repo and start the container:

cd ~ && git clone https://github.com/satomm1/gemini_api.git
sudo docker run -v ~/gemini_api:/gemini_code -v ~/Desktop/audio:/audio -w /gemini_code -it --rm --privileged -p 5000:5000 --name gemini ghcr.io/satomm1/gemini:latest

Inside: . start_scripts.sh

Get the install script

On the Jetson (recommended):

cd ~
wget "https://raw.githubusercontent.com/satomm1/Robot/main/Jetson/jetson-host-install.sh"
chmod +x jetson-host-install.sh

From your development machine (if you have the Robot repo cloned):

scp Jetson/jetson-host-install.sh YOUR_USER@JETSON_IP:~/
ssh YOUR_USER@JETSON_IP 'chmod +x ~/jetson-host-install.sh'

Run the installer

On the Jetson:

sudo ./jetson-host-install.sh

The installer writes /opt/robot/host_service.py and enables the robot-host-service systemd unit so the service starts on boot. Re-running the installer replaces the service file and restarts it.

Verify

curl -s http://127.0.0.1:8081/status

Expected response (example): {"host_service": true, "docker_running": false, "container": "ros_noetic"}

Pull images and start the stack

From the dds_robot_platform repo root:

docker compose pull
docker compose up -d

docker compose up -d alone also pulls missing images. This starts InfluxDB, Ignite, GraphQL, and the idle dds container.

Alternatively: GUI Local Stack → Docker → Start (runs docker compose up -d via WSL on Windows). Requires compose.yaml and dds/dds_env.sh.

To tear down the stack:

docker compose down

Start and stop DDS scripts (in container)

After Docker is up, start DDS inside the dds container:

docker exec -d dds ./start_scripts.sh

Alternatively: GUI Local Stack — verify repo path, start Docker, then DDS → Start (DDS stays disabled until Docker is running).

When finished, stop DDS scripts:

docker exec dds ./stop_scripts.sh

Or DDS → Stop in the GUI Local Stack panel.

Verify DDS scripts (optional)

docker exec dds bash -lc "pgrep -af python"

You should see the publisher/subscriber scripts (entry_exit.py, heartbeat_publisher.py, goal_publisher.py, etc.).