Adding a New Joystick to AUV Workbench

• This help page describes the Joystick Controller Configuration Tool to allow workbench users to configure a new device, save the settings, and report them back for inclusion in the codebase.
• The goal of adding a new joystick has been an advanced task for AUV Workbench developers. Hopefully this tool simplifies the process satisfactorily.
• Discussion of details is welcome on the AuvWorkbench mailing list. The NPS team will help ensure that your data integration proceeds correctly.

Testing the joystick

• Windows has a joystick utility which can calibrate joysticks, and displays currently plugged in joysticks and the values of its components. This can be accessed through Windows Run -> "joy.cpl".

Joystick Controller Configuration Tool

A number of joystick devices are already preconfigured in the workbench. If no match is not found for your device, follow the listed steps to run the configuration panel.

1. The new joystick controller must be plugged into your computer prior to tool launch.
2. Open the editor from the workbench through the menu: Tools -> Joystick Configuration Generator
3. Confirm the editor is editing the right configuration file. It defaults to the current user's top-level file configuration/c_joystick.xml
   It is also possible to edit the master configuration template configuration/templates/c_joystick.xml
4. Select the controller to configure from the list at the bottom left side.
5. Select the workbench action to link to from the list at the bottom right side.
6. Trigger the component (i.e. by moving the axis or pressing the button).
   A mapping should come up in the table.
7. Repeat steps 3-5 until all desired mappings are generated.
   If you wish to delete a mapping, right click on the table entry or left click the entry and press the "Delete Mapping" button at the bottom left.
8. Save the mappings by clicking "Save Modifications" at the bottom right.
9. Restart the workbench in order to use the new configuration

Troubleshooting

• We cannot guarantee all controller names are unique; therefore, conflicts may arise.
• Because the workbench uses native libraries to read the joystick, different operating systems may report control identifiers differently. If a configuration file were created on a different operating system and the workbench is not responding to joystick movements, try generating the configuration file again on the target OS.
• The AUV Workbench must be closed and reopened in order for the new configurations to take effect.
• The device you wish to configure must be plugged in at the launch of the tool. In order to add a newly plugged in device, reopen the configuration window

Configuration design

The joystick mappings of joystick controls to workbench actions in Joystick Mode are defined in the configuration file c_joystick.xml.

For example, this is a joystick mapping in a configuration file:
<event joystickTag="x" workbenchEvent="DEVICE_STEERING" />

• The workbenchEvent above must correspond to one of the enumerations for vehicle actions in Java class avcl.joystick.JoystickEvent.CommandType
• The joystickTag corresponds to the id of the component. This is determined by getComponent().getIdentifier().getName() in the avcl.joystick.Joystick class.

The joystickTag and workbenchEvent values must correspond exactly to the above constraints, or else the workbench will not be able to parse the correct mappings for your new device. Because this can be complicated, a tool is built into the Workbench which determines the identifier of the control and possible workbench actions.

TODO

• Describe how to run common joystick test utilities for Mac OSX and Linux.
• List AVCL missions and X3D scenes of interest
• List X3D scene and missions of interest
• While Point of View (POV) controls are picked up by the configuration tool, the workbench does not yet support them.
• Software development: explanation of enumeration schemes used to achieve coherent definition and consistent functionality for diverse joystick devices.

Back to the Help page index, the AUV Workbench: Introduction page, or online to AUV Workbench home page.