🚀 Getting Started

Install the bridge on a ROS 2 robot and watch it come online in the console.

Prerequisites

The bridge ships as one package per ROS 2 distribution, each in its own apt suite. All three suites are served today.

Each date is that distribution’s own end of life, from the ROS 2 release schedule. A suite stops receiving versions when its distribution does.

You also need:

• curl, gnupg and ca-certificates on the robot. The ros:<distro> images ship none of the three; the block below installs them.
• A console account at https://console.fleetless.dev.

1. Create the robot

In the console, open Robots and create one. That mints a Fleetless token (frt_…) binding one bridge process to exactly this robot. The token is shown once and never read back, so copy it before you leave the page.

A lost token is replaced by rotating it on the robot’s Overview, which stops the robot until the new one reaches it.

2. Install the bridge

The packages are served signed from apt.fleetless.dev. Substitute your own distribution for humble; the suite name and the package name change together, and nothing else does.

export ROS_DISTRO=humble          # or jazzy, or lyrical
sudo apt-get update
sudo apt-get install -y curl gnupg ca-certificates
curl -fsSL https://apt.fleetless.dev/key.gpg \
  | sudo tee /usr/share/keyrings/fleetless.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/fleetless.gpg] https://apt.fleetless.dev $ROS_DISTRO main" \
  | sudo tee /etc/apt/sources.list.d/fleetless.list
sudo apt-get update
sudo apt-get install -y "ros-$ROS_DISTRO-fleetless-bridge"

Each suite carries only its own distribution’s package. Mismatch the suite and the package name and apt answers Unable to locate package, rather than installing the wrong thing. The package is Architecture: all and serves amd64 and arm64 from one build.

3. Start it

source /opt/ros/$ROS_DISTRO/setup.bash
source ~/your_ws/install/local_setup.bash   # see the warning below
export FLEETLESS_TOKEN=frt_...
ros2 launch fleetless_bridge bridge.launch.py

Environment variables

Set them in the launch file or in the environment. The launch file restarts the process five seconds after it dies, so a crash loop backs off visibly in the log instead of flooding it. Bandwidth shaping is a fleetless.yaml section now: see low_bandwidth.

What you should see

The robot turns connected in the console within a few seconds. Started without a token, the bridge stops instead, with a sentence rather than a stack trace:

FLEETLESS_TOKEN is not set. Create the robot in the Fleetless console and
pass its token via the launch file or environment.

Latest bridge package: 6.1.0.

Your organisation’s Fleetless users get a mail when a version is deprecated, two weeks before it stops, when a robot is refused for it, and when a newer bridge package is published. Upgrading is an ordinary apt upgrade:

sudo apt-get update
sudo apt-get install --only-upgrade "ros-$ROS_DISTRO-fleetless-bridge"

Exit codes

A supervisor cannot read log messages, so the exit code says what happened.

Code 2 is deliberate. A bridge that kept retrying a rejected token would hammer the cloud and hide the real problem, and one that reconnected after being superseded would trade the robot back and forth with its replacement forever. Everything else is retried with a jittered exponential backoff from 1 s up to 30 s.

A protocol version the cloud refuses waits one to two minutes before that exit, so the launch file’s respawn retries every couple of minutes and a fresh process picks up an upgraded package by itself.

Next

• Exposing a Robot — the document that decides which topics, services, actions and cameras the robot’s API carries.
• Create an App — the client your users sign into, and the robots it is allowed to reach.
• The App Starter — a working dashboard on @fleetless/sdk, ready to clone.