.. SPDX-FileCopyrightText: 2026 Kent Stevens (timeplt)
.. SPDX-License-Identifier: GPL-2.0-or-later

Configuring WINCTRL input devices
=================================

.. version-added:: 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 <https://wiki.flightgear.org/USB-HID/>`__
   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:

.. code-block:: xml

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

.. code-block::

                    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:

.. code-block::

                    # 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:

.. code-block::

                    # 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.:

.. code-block::

                    # 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:

.. code-block:: xml

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