Configuring WINCTRL input devices

Added in version 2024.1.8.

The WINCTRL devices run with the USB-HID subsystem and input_helpers. Several configuration files are provided in FGDATA for some devices but many more exist. A generic helper class is provided to allow more devices to be added, or override an existing configuration.

Note

See the usb-hid wiki for more details on the Input subsystem while the online docs are improved.

Example generic configuration

Copy the $FGDATA/Input/HID/WINCTRL/GENERIC-WINCTRL.xml to your $FGHOME/Input/HID/newdevice.xml and update the values where indicated in the comments.

First update the model-id, model-name, and <name> tags to match your usb device:

<PropertyList>
    <vendor-id>4098</vendor-id>
    <!-- give valid device id -->
    <model-id>6969</model-id>
    <vendor-name>winctrl</vendor-name>
    <model-name>generic</model-name>
    <!-- give a valid name -->
    <name>USBDEVICE WINCTRL</name>
    <debug-events type="bool">false</debug-events>
    <hid-debug-raw type="bool">false</hid-debug-raw>
    <nasal>
        <open>

This section sets up the input_helper device to activate leds or more complicated functions. First change the device ids to the correct ones for the usb device.:

logprint(LOG_DEBUG,"WINCTRL GENERIC Nasal (event) open");
generic = input_helpers.winctrl.new("generic",cmdarg(),device);
# define correct dev1/dev2 address
# usually the hex usb-device id flipped: bb70, dev1=0x70,dev2=0xbb
generic._dev['dev1'] = 0x69;
generic._dev['dev2'] = 0x69;

Then, configure a unique name for the device:

# give device a unique path name
generic.path = "input/winctrl/new-draims-panel";

Setup the LED addresses so they can be used in flightgear, panel and ledBRT are already configured by default but can be overwritten:

# assign more led addresses
# 0x00 and 0x01 are assigned
generic._led['led4'] = 0x03;
generic._led['led5'] = 0x04;
# create leddy type for all leds
foreach (var l; keys(generic._led)) {
    var devs = [generic._dev.dev1,generic._dev.dev2];
    var prop = generic.path~"/leds/"~l;
    generic.leds[l] = input_helpers.leddy.new(l,devs,generic._led[l],prop);
    append(generic.listeners,generic.leds[l].autoReport(generic._device));
}
# this allows LED to illuminate
generic.leds.ledBrt.set(255);

Now the device should be able to light up and toggle LEDS! You can start fgfs and browse them in debug->browse internal properties: then under input/winctrl/new-draims-panel/leds/. You can change the values with 0-255 to see that they react. If you don’t see anything, verify the device addresses and your LED locations match what what the device is expecting.

Once the devices are working, you can set a listener to match the LED value to different aircraft properties.:

# add some _ledWatchProps
generic._ledWatchProps["panel"] = props.globals.getNode("/controls/lighting/main-panel-norm", 1);
generic._ledWatchProps['led4'] = props.globals.getNode("/some/led/warning/property",1);

# run the watchLEDs listener for the _ledWatchProps
generic.watchLEDs();

Last, or maybe first if buttons are more important, configure the button mappings at the end:

    <!-- HID BUTTONS, create events for all of your buttons -->
    <event>
        <name>button-1</name>
        <desc>button 1</desc>
        <repeatable>false</repeatable>
        <binding>
            <command>property-assign</command>
        <property>/input/winctrl/generic1/buttons/button01</property>
        <value>1</value>
        </binding>
        <mod-up>
            <binding>
                <command>property-assign</command>
                <property>/input/winctrl/generic1/buttons/button01</property>
               <value>0</value>
            </binding>
        </mod-up>
    </event>
</PropertyList>

Troubleshooting

Finding the LED addresses and device IDs can take some time. Several other projects online have used these to work with other flight simulators and other projects. They may have clues that work with the existing devices

Beware, winctrl devices are known to change device names and functionality across firmware updates.

More complicated devices

See the other helper files in $FGDATA/Nasal/input_helpers/winctrl/ to get an idea how to setup LCD screens and other features.