USB-HID

[draft]

USB-HID (Human Interface Device) is one of the methods to connect input devices to FlightGear.

Linux access rights for devices

HID devices under linux have usually restricted access rights, e.g. normal users are not allowed to access them directly. As you should not run FlightGear as root user, you most likely need to create a few udev rules to allow normal users to access the device files.

First, use lsusb to get a list of all detected USB devices. The output should look similar to this:

Bus 003 Device 004: ID 294b:1901 Honeycomb Aeronautical Bravo Throttle Quadrant
Bus 003 Device 006: ID 06a3:0763 Saitek PLC Pro Flight Rudder Pedals
Bus 003 Device 002: ID 294b:1900 Honeycomb Aeronautical Alpha Flight Controls
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 006 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 005 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Find the lines containing your relevant input devices (joysticks, yoke, throttle, pedals, ...) and note the IDs. The format is <vendor-id>:<device-id>. For simplicity, this example uses only the vendor-id. On Ubuntu, you can add for example the following file under /etc/udev/rules.d to allow r/w access to members of the input user group. Of course, you have to add/modify the lines to match the vendor-ids of your devices.

# /etc/udev/rules.d/40-usb-flightgear.rules
#
# To add your user to the input group try:
# sudo usermod --append --groups input <username>

# Honeycomb
SUBSYSTEMS=="usb", ATTRS{idVendor}=="294b", GROUP="input", MODE="0664"
# saitek
SUBSYSTEMS=="usb", ATTRS{idVendor}=="06a3", GROUP="input", MODE="0664"

To activate the new rules, try udevadm control --reload-rules && udevadm trigger

If this does not help, a reboot will do.

Developing Configuration files for input devices

Gathering data

Add the following parameters to your FlightGear command line or via the launcher Settings>Additional Settings

--log-class=input
--log-level=debug

This will create a lot of debug output for the input systems in which you can find all events supported by your devices

Creating a config file

The configuration files shall be stored in FGDATA/Input/Event/<Vendor>/<Model>.xml

As a starting point you can copy this example. Replace the data as needed.

<?xml version="1.0"?>
<PropertyList>
  <!-- next two must be single word, no special characters! -->
  <vendor-id>honeycomb</vendor-id>
  <model-id>bravo</model-id>

  <!-- 
  the name as seen e.g. in lsusb or the debug output of flightgear 
  multiple <name></name> lines are allowed to match name variants
  -->
  <name>Honeycomb Aeronautical Bravo Throttle Quadrant</name>

  <!-- 
  during development, set this to true to get more debug output
  do not forget to set it to false, when you finalize your config file
  -->
  <debug-events type="bool">false</debug-events>

  <nasal>
    <open>
      <![CDATA[
      #print("Honeycomb Bravo Nasal (event) open");
      #bravo = input_helpers.honeycomb.bravo.new(cmdarg());
      ]]>
    </open>
    <close>
      <![CDATA[
      #print("Honeycomb Bravo Nasal (event) close");
      #if (ishash(bravo) and isfunc(bravo['close']))
      #  bravo.close(cmdarg());
      ]]>
    </close>
  </nasal>
  <!-- events shall follow here -->
</PropertyList>

Example for an axis event:

  <event>
    <desc>Lever 0</desc>
    <name>abs-x-translate</name>
    <min-range>-1023</min-range>
    <max-range>1023</max-range>
    <binding>
      <command>property-scale</command>
      <property>/input/honeycomb/bravo/lever[0]</property>
    </binding>
  </event>

Example for a button event:

  <event>
    <name>button-1</name>
    <desc>AP mode HDG</desc>
    <repeatable>false</repeatable>
    <binding>
      <command>property-assign</command>
      <property>/input/honeycomb/bravo/buttons/hdg</property>
      <value>1</value>
    </binding>
    <mod-up>
      <binding>
        <command>property-assign</command>
        <property>/input/honeycomb/bravo/buttons/hdg</property>
        <value>0</value>
      </binding>
    </mod-up>
  </event>

Status of OS support

Linux: Supported

MacOS: supported?

Windows: not yet supported?