Integrating with Formant Cloud

Introduction

Formant provides a internet-based network layer to optionally connect the MoveIt Studio interface to a remote robot. The communication is achieved by installing a Formant Agent on the server-side and by using a Toolkit on the client-side. This integration is optional and additional fees may apply from Formant.

Installing the server-side Formant agent

  1. Log in to https://app.formant.io

  2. Go to the Settings page (click on the hamburger menu in the top left corner, and find the Settings button at the bottom).

  3. Select the Devices page from the sidebar. Then, click on Add device and give it a unique name.

  4. In Advanced settings, select the configuration studio_v1.

  5. Follow the on-screen instructions that require us to run a command on the terminal as root. When asked, DO NOT install ROS tools as they are not required.

Test the connection

Follow the next steps to test if the Formant agent is configured and running correctly on the local host.

  1. Open the page https://app.formant.io

  2. Go to the Observe tab and choose the computer where the Formant agent has been installed. We should be able to see information about the computer CPU, location, and other values streamed from the computer to the Formant web application.

Should we experience any issue, check the Formant log using the following command:

journalctl -feu formant-agent

Manual startup

The Formant agent runs automatically at the computer startup. If we want to control this default behavior, we can execute any of the following commands.

To stop the Formant agent, we can type:

sudo systemctl stop formant-agent.service

To disable it entirely, we can type:

sudo systemctl disable formant-agent.service

Then, we can start it up manually by typing:

sudo systemctl start formant-agent.service

Uninstall

To completely uninstall the Formant agent, run the following command:

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

Reprovisioning an existing machine

Provisioning a machine creates the link between the device on Formant’s web page and the actual hardware. We can follow this process if we need to reprovision or re-install the machine.

  1. Log in to https://app.formant.io

  2. Click on the three horizontal lines in the upper left-hand corner of the page to open the sidebar menu.

  3. Click on the Settings button at the bottom of the menu.

  4. Click on Devices on the left-hand side of the page.

  5. Find the device to reprovision, and click on the three dots on the right-hand side of the page across from the device’s name.

  6. From the menu that appears, select Reprovision.

  7. Click OK to continue.

  8. Copy the command that appears, and run it in a terminal on the device to reprovision.

  9. See the Test Connection section to confirm that the reprovisioned device is working correctly.

Camera stream configuration

MoveIt Studio allows for custom camera stream configurations, such as adding a third camera stream or removing the default two. In order to change camera configurations in MoveIt Studio:

  1. Log in to https://app.formant.io and open the page for the device you want to edit

  2. Click on the ellipses icon in the upper right-hand corner of the page to open the pop-up.

  3. Click on the Configure device option.

  4. Navigate to the Teleoperation tab at the top of the page.

  5. Here you can add and remove camera streams under the IMAGE section.

To add a stream: 1. Click the IMAGE + button. 2. Click the option Add from API 3. Name the stream following the naming convention camera_stream# (eg: camera_stream3) 4. Turn the switch for Enable encoding ON 5. Click Done

To delete a stream: 1. Click the trash-can icon next to the camera stream name under the IMAGE section.

Optional steps

Add export FORMANT_DISABLE_TERMINAL=true to /var/lib/formant/.bashrc to prevent the computer from Formant terminal access without a password.

If this is a personal computer, also set FORMANT_PORT_FORWARDING=false (do not change for robot computers).

Docker

To install Formant on a Docker image, read first Formant Docker Install Readme.

If installing on a docker image, edit the provisioning command to use install-agent-docker.sh instead of install-agent.sh.

Additionally, sharing the formant folder between the host and the docker will help to keep persistent credentials. This can be done by adding:

-v /var/lib/formant:/var/lib/formant \

to docker configuration. Additionally, the Formant Agent must be installed on the host machine.

How to start Moveit Studio agent and the Formant layer

As described in Moveit Studio Bridge README.md, there is a server-side application component, the Bridge, that uses the Formant agent to connect the Agent to the web application.

Therefore, to connect the robot to the web application, we must start the Agent and the Bridge running two commands on two separate terminals:

$ agent_robot.app
$ studio_bridge.app
$ rest_api.app

Alternatively, we can start the bridge together with the main agent_robot.app by adding the following to the config/site_config.yaml in the config package:

optional_feature_params:
  use_formant_bridge: True

Running MoveIt Studio in the Formant app

Running MoveIt Studio inside the Formant web application is only possible when the computer is connected to the Internet.

  1. Login to https://app.formant.io

  2. Select the robot to connect from the Device list on the left.

  3. Select the web UI to use from the Dashboard dropdown menu, next to the robot name,

Using the Formant Command Line Tool (fclt)

To install, use the Formant script:

bash <(curl -s https://app.formant.io/install-fctl.sh)

You can then use ssh <user>@<device_name>.formant to ssh into the robot computer. This only works if the formant agent is running on the robot computer.

If the device cannot be found, make sure we have the following correctly entered in the ~/.ssh/config file:

Host *.formant
 ProxyCommand fctl port-forward $(echo %h | sed "s/\.formant$//") -r 127.0.0.1 -p %p