This guide will teach you how to perform a standard installation of the Formant agent onto a target device.

📘

This guide describes installation via a convenience script to an Ubuntu device. It is highly recommended to install the Formant agent this way.

If you need to use another installation tool like Docker or Apt, see Install the Formant agent via Docker or Agent installation with Apt.

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.

Supported architectures and operating systems

This guide assumes that the target is an Ubuntu 16.04, 18.04, 20.04, or 22.04 device. Formant supports the following Debian versions:

• bionic
• focal
• stretch
• buster
• bullseye

Formant supports amd64 and arm64 architectures.

🚧

32-bit arm architectures are no longer officially supported for standard installations. If you need to install the Formant agent on a 32-bit arm target, please reach out to our customer success team via the Intercom messenger in the bottom-right corner of this page, or at [email protected].

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.

Admin privileges and ability to install packages

You'll need administrator privileges on your device and the ability to install packages via apt. To make sure this is configured correctly, ensure that you can run the following command on your device:

sudo apt update

Install ROS (required for ROS compatibility)

If you plan to use your device with ROS, you'll have to install ROS on your device before installing the Formant agent. For installation instructions, see ROS: Installation.

If you prefer to install the agent and its dependencies via Docker, see Install the Formant agent via Docker.

Step 1: Create a device

Follow Steps 1 and 2 of Create a device to add a new device to your Formant organization.

Step 2: Install the Formant agent

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. SSH into your robot's terminal.
2. Copy the installation command from Formant, paste it into your robot terminal, and run it.

📘

The installation command contains a unique provisioning token which expires after 72 hours.

3. (Required for custom ROS message types) Enter the absolute path to your ROS catkin workspace. You will be prompted for this during installation. Configuring your catkin workspace path will allow Formant to ingest data using custom ROS message types. If you are not using a ROS catkin workspace, skip this step without entering a path by pressing the down arrow key to select <Ok> and then pressing Enter.

📘

You can add a catkin workspace later by editing the environment variables for your Formant agent. For more information, see Environment variables for the agent.

Step 3: Verify successful installation

If the Formant agent has been installed and connection established, Formant will begin to ingest telemetry for default streams like CPU, Network, Memory, and Disk. Verify that these streams have live telemetry data in the device's telemetry page:

In Formant, on the home screen, open the menu in the upper-left corner. Click on the name of your device.

You should see live data from your device in the Observe tab.

Your device is now running the Formant agent, and you're ready to use the Formant platform!

Managing the agent installation

Environment variables

You can configure your Formant agent further via environment variables. For more information, see Environment variables for the agent.

The Formant agent service

The agent runs as a systemctl service called formant-agent. There is another systemctl service called formant-sidecar which manages automatic over-the-air (OTA) updates from the Formant web app.

Enabling and disabling the agent running on startup

By default, after installation, the formant-agent service is enabled to run on startup.

To set the agent to run on startup:

sudo systemctl enable formant-agent

To disable the agent from running at startup:

sudo systemctl disable formant-agent

Starting and stopping the agent

To start the agent:

sudo systemctl start formant-agent

To stop the agent:

sudo systemctl stop formant-agent

To restart the agent:

sudo systemctl restart formant-agent

Retrieving agent logs

You can read the Formant agent log by running the following command on your device:

journalctl -feu formant-agent

Uninstalling the Formant agent

You can remove the Formant agent from your device by running the following command:

sudo apt remove --purge formant-agent formant-sidecar

Troubleshooting

You can check that the Formant agent is running properly by running the following command on your device:

sudo systemctl status formant-agent

If you encounter an error in this process, or you still don't see your device online, see Troubleshooting an agent installation.

If you're still stuck, download your Formant agent log and reach out to our Customer Success team for support. You can reach us via the Intercom messenger in the bottom-right corner of this page, or at [email protected].

See also

• Install the Formant agent via Docker
• Environment variables for the Formant agent
• Troubleshooting an agent installation

👋

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].