Deep dive

From remote debugging to data discovery, learn how Formant works from top to bottom.

    Configure Formant agent on robot

    Formant agent configuration on a robot can be modified from the Formant web application or with fctl. A few common use cases for changing an agent’s configuration are:

    • Modify what data it should ingest into telemetry
    • Modify tags it applied to the device datapoints or stream datapoints
    • Modify the streaming rate for the entire device
    • Modify or configure teleoperation streams

    Any changes to the agent’s configuration are versioned, saved to the cloud, and synchronized to the agent the next time it has internet access. 

    To modify a device's Formant agent configuration, either click on the Settings  icon of the device channel or do the following:

    From the burger menuselect Settings ⇒ Devices ⇒ Click on  next to the device name

    This takes you to the robot's configuration, which you can then edit. 

    There are 3 fundamental aspects or sections to configuring an agent installed on the robot:

    1. Configuring the general settings: This is primarily configuring the general settings of a robot, such as over-the-air (OTA) update or enabling or disabling the SSH capability of a device or adding tags to group the device.

    2. Configuring the robot telemetry data streams:  This configuration dictates what data should be ingested and at what frequency/rate from a robot. 

    3. Configuring the robot teleoperation: This configuration dictates what/how you want to teleoperate a robot, including the joystick configuration as well as image or localization configuration.

    General Settings

    This section specifies the general settings that apply to the robot.

    Name 

    Specify the robot name. Be sure to specify a name that is meaningful to your team, as it will be displayed in the UI. You will also be able to search using this name.

    Disk buffer size (default: 100MiB)

    This specifies the amount of disk space used by the robot to buffer datapoints. This space is used as a buffer when the robot is unable to stream telemetry data to the cloud because of network connectivity issues or any other reason. The higher this value, the less likely that the system will throw away data due to poor connectivity. 

    Throttle rate (default: 5Hz)

    This specifies the rate limit on all streams for this device. The default value is 5Hz, which is the highest rate at which data will be streamed from this device. A value of 0Hz means that no data, except health data, will be streamed from this robot. 

    SSH (default: on)

    This specifies whether SSH access through Formant should be enabled or disabled on a device. 

    Tags 

    This specifies the tags associated with the device as a key:value pair. For more information on adding tags to the device, please see adding tags to devices.

    Application Configuration (advanced setting)

    The Formant Agent may be configured with a set of key-value pairs that are accessible to your application via the Formant Agent API. This application configuration is synchronized to the agent so it is accessible offline.

    Please check out the documentation on application configuration for more details. 

    Configure Telemetry Streams

    Administrators can configure ROS streams as well as files & directories to be ingested from the robot from the Formant Web Application. If there are streams that come from non-ROS applications, you can use the Formant APIs to push data into Formant Cloud. 

    Configure ROS Streams

    There are 3 different types of ROS streams that can be configured from the Web Application:

    1. ROS localization streams: topics related to robot’s localization like point cloud, odometry, map, etc.
    2. ROS transform streams: topics related to transforms like /tf
    3. All other ROS topics (topics related to image, numeric, text, or location)

    ROS localization Streams

    Specify the topics that will provide the robot’s location with respect to its environment. The following topics are ingested as a single telemetry stream. All but odometry topic is optional.

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Odometry topic 

    Specify the odometry topic that estimates the position and velocity of the robot (e.g. nav_msgs/Odometry).

    Map topic 

    Specify the map topic (e.g. /map)

    Point cloud or laser scan topics

    Specify the point cloud or laser scan topics (separated by comma) to be visualized as part of the localization stream. We use PCD formant for point clouds.

    Path topic 

    Specify the ROS topic that indicates the path (e.g. nav_msgs/Path) of the robot.

    Goal topic

    Specify the goal topic to display the goal of the robot.

    World reference frame

    Specify the world reference frame. This is used to visualize one's localization state without ingesting the entire /tf topic. Must be the name of a frame published on /tf that is a parent frame of both map and odometry topics.

    ROS transform streams

    This ingests /tf and /tf_static topics as a telemetry stream. 

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Base reference frame

    The base reference frame must be included in /tf or /tf_static (e.g. base_link).

    All other ROS topics 

    Specify text data, numeric data, location or image ROS topics you want to ingest using this section.

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Name of ROS Topic

    Specify the ROS topic, as it appears, that you want to ingest

    ROS message path (optional field): 

    If the ROS topic has subtopics, specify the message path. This is not very common.

    Configure Files & Directories

    File Tail Stream

    This interface lets you ingest new lines from a file as telemetry streams. This is useful for ingesting logs or specific log lines from a file.  Ingest new lines as a telemetry text data points. This will show up as textual lines within a text-based module. 

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Filename

    Specify the absolute directory path on the device. This file must be read-accessible to the agent process.

    Regular Expression

    You can filter the lines that you want ingested as part of the file by using regular expression. Lines in the file that match this regular expression will be ingested. Regular expression syntax can be found here.

    Directory Watch Stream

    This interface lets you ingest new files as telemetry streams. This is useful for watching directories for files and ingesting them as they appear. Watch a file and ingest new files as telemetry data points of type file, image or point cloud. 

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Directory name

    Specify the absolute directory path on the device. This directory must be read-accessible to the agent process.

    Extension

    You can filter the files that you want ingested as part of the watch by specifying file extensions. 

    File extensions must start with a period (.). For example, .png. 

    Visualization Type

    Choose the visualization type you want this file to be ingested as: "File", "Ïmage" or "Point Cloud". 

    The File type ingests each new file in the directory as a file data point. You can then download the file from this module.

    Image ingests each new file as an image data point (supports .jpg and .png files). 

    Point Cloud ingests each new file as a point cloud data point (supports .pcdfiles).

    Configure Custom Streams (non-ROS streams)

    Custom streams are ingested directly into the Formant cloud using the gRPC or HTTP APIs. You can delete the stream, add tags and/or modify the stream throttle value directly from the Formant UI.

    Teleoperation Configuration

    Administrators can configure teleoperation for ROS based robots from the Formant Web Application. If your robot is not ROS based, you can use the Formant APIs to transmit teleoperation streams and then configure it using the following. 

    There are primarily 3 parts to configuring teleoperation:

    1. Essentials: Configure the camera/image streams that you want to see and the joystick you will be using
    2. Advanced: Configure navigation topic, buttons (commands)  and status topics that you want to use
    3. View: Configure how you want these  to appear on the screen

    Essential configuration

    The following topics form the essentials of teleoperation. 

    Camera/Image stream

    Click on IMAGE  to add new image streams. You can add up to two images.

    If compatible image topics are detected on your robot, they are displayed as minicards on the popup. Click on the minicard to add that as the teleoperation image. 

    ROS based image topics

    Image topics with type sensor_msgs/Image will be streamed with H264 video compression. The Formant agent will accept the following values for the "encoding" property of Image messages:

     rgb8 rgba8 bgr8 bgra8 mono8 mono16 yuv422

    If your "encoding" value is unsupported, you may be able to adjust the "encoding" property of the image message, without changing the underlying data. In some cases, you will need to transform both the data and the "encoding" property to supported values. Please contact us if you run into these issues.

    Joystick

    Click on JOYSTICK  to add new joysticks. You can add up to two joysticks.

    If compatible joystick topics are detected on your robot, they are displayed as minicards on the popup. Click on the minicard to add that as the joystick. 

    Once you have added a joystick, you can configure it by clicking on the  edit button.

    Joystick configuration

    Any joystick, including gamepads (e.g. DualShock 4 or Xbox One controllers) that is detected by your machine's OS and supported by the HTML gamepad API (basically anything) can be used for teleoperating. Joysticks are detected automatically as soon as any button is pressed. 

    You can also use the following keyboard shortcuts to joystick your robot. 

    1. WASD control left joystick's up, left, down, right 
    2. Arrow keys control the right joystick

    Position: The joystick can be configured to be positioned on the right side or left side.

    Twist dimension: Twists can be configured to be angular x,y,z or linear x,y,z. Each twist command streams generates a corresponding software joystick. 

    Twist messages will be sent to the device when clicking, dragging, and unclicking the software joystick.

    The joystick will send Twist values with linear.x and angular.z components between [-1.0, 1.0].

    Twist: {
      linear: {
        x: float64, // [1.0, -1.0]
        y: float64, // always zero
        z: float64  // always zero
      },
      angular: {
        x: float64, // always zero
        y: float64, // always zero
        z: float64  // [1.0, -1.0]
      }
    }

    Gamepad axis: Index of the input axis on a connected gamepad, as detected by the browser. (eg. 0 == Left thumbstick horizontal axis )

    Scale: Multiplication factor applied to the joystick input. To invert, use a negative value.

    Expo: Exponent applied to the joystick input before the scale factor. For linear output, set this value to 1.

    The formula for a joystick's output value is:

    Abs(JoystickInput ^ Expo) * Scale * Sign(JoystickInput).

    Advanced configuration

    Localization/Navigation

    Specify the topics that will provide the robot’s navigation with respect to its environment. The following topics are ingested as a single telemetry stream. All but odometry topic is optional.

    Telemetry stream name

    Specify a friendly name for the ROS topic that you want to ingest. This name will be displayed on all interfaces that your users and operators will be using. 

    Odometry topic 

    Specify the odometry topic that estimates the position and velocity of the robot (e.g. nav_msgs/Odometry).

    Map topic 

    Specify the map topic (e.g. /map)

    Point cloud or laser scan topics

    Specify the point cloud or laser scan topics (separated by comma) to be visualized as part of the localization stream. We use PCD formant for point clouds.

    Path topic 

    Specify the ROS topic that indicates the path (e.g. nav_msgs/Path) of the robot.

    Goal topic

    Specify the goal topic to display the goal of the robot.

    World reference frame

    Specify the world reference frame. This is used to visualize one's localization state without ingesting the entire /tf topic. Must be the name of a frame published on /tf that is a parent frame of both map and odometry topics.

    Buttons

    Buttons publish boolean messages to the robot. This is useful for setting up real-time commands to the robot. You can configure up to 5 buttons for display.

    Status

    Status subscribes to boolean messages from the robot. This is typically used to convey the state of robot in real-time.

    View configuration

    There are 3 streams that can be viewed while teleoperating a robot. The view configuration is used to configure the view that appears under each box

    Primary view: This is the primary view that consumes the entire view area (black color above). It can be one of real-time image stream, telemetry image stream or localization.

    Sidebar view 1:  It can be one of real-time image stream, telemetry image stream or localization.

    Sidebar view 2:  It can be one of real-time image stream, telemetry image stream or localization.



    Did you know?

    You can manage configuration using Formant command-line utility called fctl. See installing fctl for more details

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