Configure joystick control

This guide will teach you how to configure your teleoperation interface to use a joystick for control.

Step 1: Navigate to device teleoperation settings

  1. In Formant, in the upper-left corner, open the menu and click Settings.
  2. Click Devices, and then click on the device you want to configure.
  3. Click on the Teleoperation tab to open the teleoperation configuration page.

Step 2: Add a joystick stream


Formant will send joystick coordinate data as a geometry_msgs/Twist stream.

  1. In the teleoperation configuration page, scroll down to Joystick and click the plus (+) icon.
  2. Click Add ROS Topic.
  3. Enter the ROS topic to which you want to post joystick coordinate data.
  4. Click Done to bring up the Joystick configuration screen.


You can also handle joystick input through the Agent SDK.

  1. In the teleoperation configuration page, scroll down to Joystick and click the plus (+) icon.
  2. Click Add from API.
  3. Enter the name of the function which handles joystick input. For an example of how to handle joystick input in the Agent SDK, see GitHub:
  4. Click Done to bring up the Joystick configuration screen.


For a complete reference for the Agent SDK, see Agent SDK Reference.

Step 3: Configure joystick settings

You can configure up to four axes across two joysticks. Each axis is mapped to a particular axis in a standard Twist message. A twist message has linear x,y,z axes, and angular x,y,z axes.

joystick configuration window

Enable toggleToggle the right or left joystick on or off. The right joystick maps to the arrow keys on your keyboard, and the left joystick maps to the WASD keys.
Twist DimensionSelect the twist dimension to which this axis maps.
Gamepad AxisIf using a gamepad, map the gamepad axis to the joystick axis.
ScaleSet the value the twist command should report when this axis is at 100%.
ExponentSet the exponential curve by which intermediate twist values (i.e., between 0 and max, or scale,) are calculated.

Step 4: Configure global settings

At the bottom of the Joystick configuration window, you'll see a list of global settings for both joysticks:

universal joystick settings

Disable Gamepad Trigger Axis MappingWhen set to Enabled, trigger buttons on your gamepad will be disabled.
Disable Gamepad Input and Keyboard InputWhen set to Enabled, joysticks will be controllable only by mouse input in the teleoperation interface.
Reduce Joystick Filter TimeoutWhen set to Disabled, twist messages will publish at 10 Hz for new values, and at 2 Hz for repeated values (i.e., holding down "forward").

When set to Enabled, twist messages will publish at 20 Hz for new values, and 10 Hz for repeated values.

Step 5: Preview your joystick output

You can use the Preview window to generate sample joystick data based on mouse, gamepad, or keypad input. Sample data will be shown in the Output section.

generating sample joystick data

Step 6: Verify your work in teleoperation mode

  1. In your device view, in the upper-right corner, click the three dots >> Teleop, or enter Shift + T.
  2. Verify that your joystick input is working properly.


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