Tips and tutorials

Tips and tutorials for beginners and experts alike

    Install docker based turtlebot 3 simulator

    This tutorial provides a step-by-step walkthrough of setting up and driving a turtlebot based simulator on a Linux machine. 


    • We will be utilizing docker containers using the turtlebot 3 simulation in gazebo. Please install docker before continuing.
    • The turtlebot container is currently only available for x86_64 systems.
    • To run this simulator we recommend launching a Linux cloud virtual machine with at least 4 cores and 16GB of RAM. You can run this locally if your system meets those requirements. For setting up a Simulator Virtual Machine please follow our simulator virtual machine tutorial.

    Step 1: Install Formant agent as standalone docker container

    Set the following environment variable on your desktop terminal

     export ROS_MASTER_URI=http://localhost:11311

    This ensures that the Formant agent detects the device as ROS based and pulls down the appropriate packages.

    From the Formant webapp add device, but use the following installation command to install Formant agent as standalone docker container. YOUR PROVISIONING TOKEN is a one time use key for provisioning the Formant Agent. Copy the token from the webapp.

    bash <(wget -qO - <YOUR PROVISIONING TOKEN>

    This script pulls down the latest Formant Agent container and runs the container in detached mode. If installation was successful you should see logs like below:

    Sourcing opt/ros/melodic/setup.bash.
    2021-01-19T00:33:34.966Z    INFO    Formant agent starting up...
    2021-01-19T00:33:34.966Z    INFO    Formant agent: 1.16.88
    2021-01-19T00:33:34.966Z    INFO    No credentials found, provisioning agent.
    2021-01-19T00:33:34.966Z    INFO    Attempting new agent installation with provisioning token
    2021-01-19T00:33:34.966Z    INFO    using provisioningToken from environment variables
    2021-01-19T00:33:35.139Z    INFO    trying to credential agent...
    2021-01-19T00:33:35.393Z    INFO    no agent configuration file found
    2021-01-19T00:33:35.393Z    INFO    missing configuration, syncing with cloud ...
    2021-01-19T00:33:35.559Z    INFO    received updated agent configuration from cloud, version: 2 local version: 0
    2021-01-19T00:33:35.559Z    WARN    buffer size must be at least 100MB, setting to 100MB
    2021-01-19T00:33:35.559Z    WARN    on-demand buffer size must be at least 100MB, setting to 200MB
    2021-01-19T00:33:35.564Z    INFO    Agent ID: xxxxxxxxxxxxxx, Agent Name: turtlebot.706
    2021-01-19T00:33:35.566Z    INFO    Starting agent health heartbeat
    2021-01-19T00:33:35.566Z    INFO    starting host metrics collector...
    2021-01-19T00:33:36.168Z    INFO    started host metrics collector
    2021-01-19T00:33:36.170Z    INFO    metrics.ROS    error getting system state from ROS master, is ROS running?
    2021-01-19T00:33:36.170Z    WARN    metrics.ROS    failed to update ros state: error executing request: Post http://localhost:11311: dial tcp connect: connection refused
    2021-01-19T00:33:36.176Z    INFO    agent started successfully
    2021-01-19T00:33:36.182Z    INFO    listening for ROS Bridge gRPC on: /var/lib/formant/ros_bridge.sock
    2021-01-19T00:33:36.182Z    INFO    listening for gRPC on: :5501
    2021-01-19T00:33:36.183Z    INFO    listening for gRPC on: /var/lib/formant/agent.sock
    2021-01-19T00:33:36.183Z    INFO    listening for http on: :5502
    2021-01-19T00:33:36.360Z    INFO    TF bridge: python    ROS Tf2 lookup transform node starting up...
    2021-01-19T00:33:37.807Z    INFO    ROS bridge: python3    Agent ROS bridge starting up...
    2021-01-19T00:33:37.891Z    INFO    Media encoder: python3    Agent media encoder starting up...
    2021-01-19T00:33:37.924Z    INFO    Media encoder: python3    Media encoder connecting to agent unix domain socket...
    2021-01-19T00:33:37.924Z    INFO    Media encoder: python3    Agent communication initializing ...
    2021-01-19T00:33:37.926Z    INFO    Media encoder: python3    Media encoder initialized.

    The ROS warnings are expected since that is bundled in the next step.

    Step 2: Install turtlebot simulator as standalone docker container

    The next step is to setup the simulator. This can be done with a single command:

    sudo docker run -it --net host --rm --name formant-turtlebot formant/turtlebot

    We aren't running this in detached mode (-d option) so we can check for errors and ensure things are working smoothly, and restart quickly if needed.

    If data is flowing correctly, you should see the following:

    [ INFO] [1610997557.299617213, 1.949000000]: odom received!

    If you would like to leave the turtlebot as a long-running container, kill the previous command using CTRL+C or equivalent on your system and run:

    sudo docker run -it --net host -d --name formant-turtlebot formant/turtlebot

    Which will run in detached mode. You can check the logs with:

    sudo docker logs formant-turtlebot

    Note: you can optionally add --device /device/snd to fix these warnings, however it is not required (and your machine may not have a soundcard, the AWS VM does not):

    [ WARN] [1610997554.214580653]: Request for map failed; trying again...
    ALSA lib confmisc.c:767:(parse_card) cannot find card '0'
    ALSA lib conf.c:4528:(_snd_config_evaluate) function snd_func_card_driver returned error: No such file or directory
    ALSA lib confmisc.c:392:(snd_func_concat) error evaluating strings
    ALSA lib conf.c:4528:(_snd_config_evaluate) function snd_func_concat returned error: No such file or directory
    ALSA lib confmisc.c:1246:(snd_func_refer) error evaluating name
    ALSA lib conf.c:4528:(_snd_config_evaluate) function snd_func_refer returned error: No such file or directory
    ALSA lib conf.c:5007:(snd_config_expand) Evaluate error: No such file or directory
    ALSA lib pcm.c:2495:(snd_pcm_open_noupdate) Unknown PCM default
    AL lib: (EE) ALCplaybackAlsa_open: Could not open playback device 'default': No such file or directory
    [ INFO] [1610997554.535005762]: waitForService: Service [/gazebo/set_physics_properties] is now available.
    [ INFO] [1610997554.559267119]: Physics dynamic reconfigure ready.

    Step 3: Configure teleoperation 

    The next step is to import the configuration for the simulation into Formant using the webUI. 

    1. Save the contents of config.json on your desktop. 
    2. Click on Configure device 1599583998796-1599583998796.png from the Formant web app.
    3. At the bottom of the General settings page, select Import from YAML and choose config.json

    This will setup the teleoperation (as well as observability streams, if your plan supports it). If things are configured properly you will be dropped into a real-time view through the robot:

    Step 4: Teleoperate the Turtlebot simulator

    You can use your keyboard arrow keys to control the simulation and drive the robot around the house. Additionally you can click the goal buttons to have it navigate to different parts of the house.  (Note some features displayed are part of our Starter and Premium offerings). For more information on teleoperation, see our teleoperation page.

    © 2020 Formant • 1999 Bryant St · San Francisco, CA 94110