This guide will teach you how to install the Formant agent to your device via Docker.

🚧

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.

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

You'll need to have Docker installed to your device to 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 (ROS 2)

Following from the instructions in Step 2 of Create a device: you will see a command which installs the Formant agent to your device.

1. Generate the installation command from the web application and paste it in the target device's terminal, but do not run it yet. Copy the provisioning token which is generated. Note the installation command contains of a provisioning token that is unique to the device and expires after 72 hours.
2. Download but do not run the installation script:

wget https://app.formant.io/install-agent.sh

3. Identify the Docker container tag you want to install. You can do this by either:
   1. Referring to our Docker registry here: Docker Hub: Formant Agent, or
   2. Using the install script to show available tags, such as:

./install-agent.sh --show-tags | grep ros2

...which might show you a result like:

1.240.1-ros2-humble-arm64
1.240.1-ros2-humble
1.236.1-ros2-humble-arm64
1.236.1-ros2-humble

4. Run the installation script with the following flags, such as:

./install-agent.sh --method docker --ros 2 \
--ros-workspace /path/to/colcon_ws \ 
--tag 1.240.1-ros2-humble \
YOUR-PROVISIONING-TOKEN

📘

Script help

You can get help on the installation script:

Shell

./install-agent.sh --help

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 pag

Managing a Docker installation

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

👋

If you notice an issue with this page or need help, please reach out to us! Use the 'Did this page help you?' buttons below, or get in contact with our Customer Success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].