Install the Formant agent on a ROS1 device by running the Docker-based installer.

Prerequisites

System requirements

The Formant agent is an extremely lightweight tool which sets up data pipelines on your device. The base footprint of the agent itself on a device is minimal. Depending on your application, you can configure the agent and your device to store and transfer large amounts of data (e.g., video cache and streaming), which will require greater memory and CPU capability.

Install Docker to your device

Install Docker on the target device before you install the Formant agent.

Create a device

Follow the instructions in Create a device to add a new device to your Formant organization.

Internet connectivity

The target device must have connectivity to app.formant.io and api.formant.io.

You can run the following script on your device terminal to output the robot's details and verify prerequisites:

bash <(wget -qO - https://app.formant.io/device-check.sh)

Terminal access

To install the Formant agent on the target device, you must have terminal access to the device and the ability to run commands.

Step 1: Install the Formant agent

Follow the instructions in Create a device to generate a provisioning token for the target device. The provisioning token is unique to the device and expires after 72 hours.

Run the installer with Docker and ROS1 enabled:

bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 <YOUR PROVISIONING TOKEN>

To ingest custom ROS message types, pass your catkin workspace path with --ros-workspace:

bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 --ros-workspace /home/ubuntu/catkin_ws <YOUR PROVISIONING TOKEN>

📘

Ensure the ROS master is running

The Formant agent needs to communicate with the ROS master running on your device in order to properly ingest ROS data.

You can check that the ROS master is running by using a command like rostopic list.

Step 2: Verify successful installation

If the Formant agent has been installed and connection established, Formant will begin ingesting telemetry for default streams like CPU, Network, Memory, and Disk.

1. In Formant, in the upper-left corner, open the menu. Under the Observe tab, click on the name of your device.
2. Verify that these streams have live telemetry data in the device's telemetry page.

Managing a Docker installation

🚧

Docker installations of the Formant agent do not support automatic, over-the-air (OTA) agent updates.

To update the Formant agent, you will have to update the formant-agent Docker image on your device.

Updating or re-running after provisioning

To update the agent or re-run the installer after provisioning, omit the provisioning token. The script detects existing credentials at /var/lib/formant/credentials.toml and skips provisioning.

bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1

Browsing available image tags

List available image tags when you need to pin a specific agent version or find the right image for your ROS distribution and architecture.

# List all available tags
bash <(wget -qO - https://app.formant.io/install-agent.sh) --show-tags all

# Filter by keyword
bash <(wget -qO - https://app.formant.io/install-agent.sh) --show-tags melodic

Install a specific agent image tag

To pin the installation to a specific image tag, pass --tag:

bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 --tag 1.228.1-ros-melodic-arm64 <YOUR PROVISIONING TOKEN>

Passing extra Docker arguments

Pass optional arguments to the Docker run command with --extra-args. For example, mount an additional volume and set a custom environment variable:

bash <(wget -qO - https://app.formant.io/install-agent.sh) --method docker --ros 1 \
    --extra-args "-v /data/robot:/data/robot -e MY_VAR=value" \
    <YOUR PROVISIONING TOKEN>

Enabling and disabling the agent running on startup

By default, after installation, the agent runs on startup.

To set the agent to run on startup:

docker update --restart=yes formant-agent

To disable the agent from running on startup:

docker update --restart=no formant-agent

Starting and stopping the agent

By default, the agent will be enabled and run on startup.

To start the agent:

docker start formant-agent

To stop the agent:

docker stop formant-agent

To restart the agent:

docker restart formant-agent

Retrieving agent logs

docker logs -f formant-agent

Uninstalling the Formant agent

This command stops any running formant-agent containers and removes the formant-agent image:

docker rm -f formant-agent

To remove the agent credentials as well, run:

rm -rf /var/lib/formant

See also

• Install the Formant agent
• Environment variables for the agent
• Troubleshooting an agent installation
• Error invoking Docker in Formant terminal