Warning

This documentation is currently under development! It should not be relied upon at this time.

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 device 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 /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 bindings 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 bindings 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 /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 /sim/input/double-press-sec, and can be set per button if needed.