.. include:: ../../../_includes/_warning_banner.rst

.. SPDX-FileCopyrightText: 2026 James Turner <james@flightgear.org>
.. SPDX-License-Identifier: GPL-2.0-or-later

Input Config Properties
=======================

``name``
    Define a name the device may preset as, the the system. For most
    devices is this manufacturer's official name (as defined in the USB
    registry), and the device's name. Some devices have shipped with
    multiple names in their lifecycle.

``vendor-id``
    Define the vendor ID of the device, as defined in the USB registry.
    This is a short number which is assigned to a manufacturer. Note
    that this accepted **hexadecimal** values, since this is how USB
    vendor IDs are nearly always represented.

``device-id``
    Define the device ID of the device, as defined in the USB registry.
    As for the vendor ID, this is interpreted as a hexadecimal value. See
    the documentation on :doc:`device identification
    </reference/xml-reference/input/identification>` for more details on
    how this is used.

``debug-events``
    Set to `true` to enable debug log output for the device. This can be
    useful when tweaking a configuration file, to see raw event values
    and understand how physical controls map to input events.

    Note this value can be toggled at runtime via the
    :fgprop:`/input/device[N]/debug-events` property.

``nasal``
    ``open``
        Defines Nasal code which is executed when the device is
        connected. This can be used to initialize helper functions or
        data, in the context of Nasal callbacks on reports.

    ``close``
        Defines Nasal code which is executed when the device is
        disconnected.

Common Properties
^^^^^^^^^^^^^^^^^



Axis Properties
^^^^^^^^^^^^^^^

``output-mode``
    Configures what value is passed when invoking :term:`bindings
    <binding>` for this event. The following values are supported:

    ``signed-normalized``
        The output value is a floating point value in the range [-1.0,
        1.0], where the center position is 0.0.

    ``unsigned-normalized``
        The output value is a floating point value in the range [0.0,
        1.0]. Note that in this mode, the ``center`` position is not
        used.

    ``direct``
        The output value is the raw input value, as read from the
        device. The range depends on the HID feature configuration, and
        could span for example 0..1023, or -16..15, depending on the
        exact hardware and configuration. This mode is useful for inputs
        such as rotary encoders, which generate a signed relative input,
        based on how fast they are moved.

``center``
    Define the center position of the output range. The default value is
    '0.0'.

``deadband``
    :todo:

``low-threshold``
    Specifies a value in the *output* range, below which the ``<low>``
    binding will be fired. For a ``signed-normalized`` axis, this is
    typically a value like '-0.9', so that the ``<low>`` binding is
    fired when the axis is at the bottoms of its range.

``high-threshold``
    Specifies a value in the *output* range, above which the ``<high>``
    binding will be fired.

``noise-threshold-bits``
    Specify how many input bits are ignored when considering if the axis
    has changed. This is necessary to reduce continuous firing of events
    on cheaper input hardware, where the low bits of the ADC are often
    meaningless. The default value is 0, and typical values would be 1-3
    bits, depending on the exact hardware.

Button Properties
^^^^^^^^^^^^^^^^^

``output-mode``
    Configures what value is passed when invoking :term:`bindings
    <binding>` for this event. The following values are supported:

    ``switch``
        The output value is 1 when the button is pressed, and 0 when
        it's released. Note that in this mode, the `release` bindings
        are ignored.

    ``button``
        The output value is 1 when the button is pressed, and 0
        otherwise. When the button is released, the `release` bindings
        are fired.

``repeatable``
    If set to true, the main bindings will be fired repeatedly, until
    the button is released.

``interval-sec``
    Specify the interval in seconds which `repeatable` bindings are
    fired at.

``invert``
    Invert the sense of a button, as seen by the hardware and reported.
    Especially useful for `switch` buttons, where the sense may be
    backwards.

``mod-long-press``
    Define bindings which are fired when the button is held down for an
    extended period of time. A default duration is defined at
    :fgprop:`/sim/input/long-press-sec` and can be set per button if
    needed.

``mod-double-press``
    Define bindings which are fired when the button is pressed twice in
    quick succession. A default duration between presses is defined at
    :fgprop:`/sim/input/double-press-sec`, and can be set per button if
    needed.