[Daemon] Section

Profile

This tells the daemon which profile to load when it starts up. Profiles are only loaded from the ~./config/opensd/profiles/ directory, so only specify the filename here. OpenSD also has other methods for loading profiles once the daemon is running, this setting is only for the default profile you wish to use.

Format:

Profile = <filename>

Example:

[Daemon]
Profile = default.profile

AllowClients

This setting enables or disables the use of the CLI and GUI utilities which connect to the daemon. If set to false, the daemon will not listen for clients. This can be useful if you want to "lock down" a configuration so it cannot be changed while it is running. The default is true.

Format:

AllowClients = <true | false>

Example:

[Daemon]
AllowClients = true

[Profile] Section

Name

The profile name as it will appear in the GUI and through the CLI query. Should be unique for each profile to avoid confusion.

Format:

Name = <profile_name>

Example:

[Profile]
Name = "My favourite gamepad profile"

Description

A breif description of the profile for use in the GUI and CLI query. Does not affect anything else, just intended as a hint for users.

Format:

Description = <description>

Example:

[Profile]
Description = "Just a profile I use for most applications."

[Features] Section

ForceFeedback

Enable or disables haptic / force-feedback events for the gamepad device. It’s worth mentioning that only the Gamepad device can receive force-feedback events; the Motion or Mouse devices will not receive these events.

Format:

ForceFeedback = <true | false>

Example:

[Features]
ForceFeedback = true

If unspecified, this value defaults to false.

MotionDevice

If this is set to true, an additional input device will be created which will report motion control data. Motion axes need to have thier ranges and bindings defined. If this is disabled, any Motion device bindings will be ignored.

Format:

MotionDevice = <true | false>

Example:

[Features]
MotionDevice = true

If unspecified, this value defaults to false.

MouseDevice

If this is set to true, an additional input device will be created which will be used to send mouse / trackpad events. Mouse events still need to have thier bindings defined. If this is disabled, any Mouse device bindings will be ignored.

Format:

MouseDevice = <true | false>

Example:

[Features]
MouseDevice = true

If unspecified, this value defaults to true.

LizardMode

The Steam Controller and the Steam Deck both have a kind of fallback "BIOS" mode which emulates some keyboard and mouse input using the gamepad. Valve refers to this as "Lizard Mode". This mode cannot be redefined. It sends events IN ADDITION to the gamepad events created by the OpenSD driver, so it should always be disabled. If you would like mouse or keyboard emulation, they should be configured with bindings. When OpenSD exits, Lizard Mode is re-enabled.

If this is set to false "Lizard Mode" will be disabled (recommended).

Format:

LizardMode = <true | false>

Example:

[Features]
LizardMode = false

If unspecified, this value defaults to false.

StickFiltering

The thumbsticks on the Steam Deck have a circular range but return square-ish data, which makes it feel odd and complicated to apply radial deadzones to. Because of this, OpenSD vectorizes the stick position and returns "cleaner", round stick ranges, as well as being able to create clean deadzone rescaling. If you disable this setting, axis ranges are still internally normalized and rescaled to the the uinput device, but no vectorization will be applied and any deadzones will be ignored.

If set to true thumbsticks will be filtered (recommended).

Format:

StickFiltering  = <true | false>

Example:

[Features]
StickFiltering  = true

If unspecified this value defaults to true.

TrackpadFiltering

Similar to StickFiltering, but matches the square shape of the trackpad. Filtering is only applied to absolute values. This setting must be enabled to apply deadzones to the trackpad absolute axes. Relative values (*PadRelX and *PadRelY) are unaffected, therefore deadzones do not affect mouse movement with the pads.

If set to true trackpads will be filtered (recommended).

Format:

TrackpadFiltering  = <true | false>

Example:

[Features]
TrackpadFiltering  = true

If unspecified, this value defaults to true.

[DeviceInfo] Section

This section is used to optionally configure the USB identification of each device OpenSD creates. While OpenSD has its own defaults, they can be overridden to make these devices appear as a different hardware. This can be useful when some very poorly written games only look for / support specific gamepads, rather than a universal API. Shame. Often, these games filter out all input devices which don’t match the device name string and/or the USB VID:PID. These settings enable the gamepad to mimic the appearance of a device which the software does recognise.

Format:

<device>    = <vid> <pid> <ver> <name>

Example:

[DeviceInfo]
Gamepad     = 0xDEAD 0xBEEF 0x0001 "OpenSD Gamepad Device"
Motion      = 0xDEAD 0xBEEF 0x0001 "OpenSD Motion Control Device"
Mouse       = 0xC475 0xF00D 0x0101 "OpenSD Mouse / Trackpad Device"

[Deadzones] Section

These values are double precision floating point and represent the percentage of the total axis range to ignore. A value of 0.05 would be a 5% deadzone. Deadzones are capped at 0.9 (90%). A value of 0 is considered disabled. If StickFiltering is disabled, LStick and RStick deadzones will be ignored. If TrackpadFiltering is disabled, LPad and RPad deadzones will be ignored.

Format:

<axis>      = <value>

Example:

[Deadzones]
LStick      = 0.1
RStick      = 0.1
LPad        = 0
RPad        = 0
LTrigg      = 0
RTrigg      = 0

Any undefined axis deadzone will default to 0 (disabled).

[GamepadAxes] Section

Gamepad absolute axes must have a defined range or they will not be created. Any Gamepad ABS_* events which are configured in the Gamepad Bindings section must be defined here first, or they will be ignored.

Internally, the axis values are normalized and rescaled between the actual hardware and the value seen by applications, so no clipping or "dead extremes" will occur. There is no "right" or "wrong" value here that you need to know, but it may be useful to precisely emulate other hardware so it can be detected as such by certain applications which try to guess what kind of device you have.

The Steam Deck hardware uses signed 16-bit integers (-32767 to 32767) for its thumbstick, trackpad, trigger and motion axes, so there’s no reason to use a larger or smaller range for those inputs, unless you are trying to emulate a specific device.

Hat-type <https://en.wikipedia.org/wiki/Joystick#Hat_switch> axes (ABS_HAT*) should typically use a range of -1 to 1 because of thier historical purpose, but this is not strictly enforced.

Triggers should typically have minumum value of 0 so that they rest at zero when released.

Format:

<abs_event>     = <min> <max> [fuzz] [res]

Example:

[GamepadAxes]
ABS_HAT0X       = -1        1
ABS_HAT0Y       = -1        1
ABS_X           = -32767    32767
ABS_Y           = -32767    32767
ABS_RX          = -32767    32767
ABS_RY          = -32767    32767
ABS_Z           = 0         32767
ABS_RZ          = 0         32767

[MotionAxes] Section

Motion control absolute axes, as with the gamepad device, must have a defined range or they will not be created. Any Motion ABS_* events which are configured in the Motion Bindings must be defined here first, or they will be ignored.

Internally, the axis values are normalized and rescaled between the actual hardware and the value seen by applications, so no clipping or "dead extremes" will occur. There is no "right" or "wrong" value here that you need to know, but it may be useful to precisely emulate other hardware so it can be detected as such by certain applications which try to guess what kind of device you have.

The Steam Deck hardware uses signed 16-bit integers (-32767 to 32767) for its thumbstick, trackpad, trigger and motion axes, so there’s no reason to use a larger or smaller range for those inputs, unless you are trying to emulate a specific device.

Format:

<abs_event>     = <min>     <max>

Example:

[MotionAxes]
ABS_X           = -32767    32767
ABS_Y           = -32767    32767
ABS_Z           = -32767    32767
ABS_RX          = -32767    32767
ABS_RY          = -32767    32767
ABS_RZ          = -32767    32767

[Bindings] Section

This should be a list of all the physical gamepad buttons/sticks/pads/motion inputs you want to bind to a virtual input event or command. Anything not specified here will be considered "unbound" and not emit any event.

There are currently four basic binding types: device bindings, Command bindings, Profile bindings and None.

Device bindings

Command bindings

Profile bindings

None

Input binding names which this document will refer to as input or <input>, are represent physical buttons, triggers, axes, etc. on the physical gamepad portion of the Steam Deck. They can be broken down into a several categories for simplicity:

Directional Pad

Buttons

Triggers

Thumbsticks

Trackpads

Accelerometers

Attitude / gyros

Input names prefixed with L or R indicate left and right controls (example: LStickLeft vs RStickLeft)

Additionally, trackpads are mapped out into several button layouts simultaneously. This means that when pressed, specific areas of the trackpad behave like individual buttons. There are several "maps" which can be used non-exclusively. These are

Quadrant button maps

Orthogonal button maps

2x2 grid maps

3x3 grid maps

A full list of available input codes can be seen in the example profile section, as well as in default.profile file from your installation.

A detailed explanation of each of these inputs can be found in the Input Types section.

Gamepad Bindings

The Gamepad device binding is used to generate input events for a joystick / gamepad-type device. This generally means buttons (BTN_*) and absolute axis (ABS_*) events. KEY_* events are allowed, but many programs will not read KEY_* events from a joystick device, instead try binding key events to the Mouse device.

The syntax for bindings differs slightly depending on the event type. Absolute axis (EV_ABS) events are prefixed with ABS_ and key / button events (EV_KEY) are prefixed with KEY_ and BTN_ respectively. OpenSD supports most event codes. For a full list of event codes, see linux/input-event-codes.h <https://elixir.bootlin.com/linux/latest/source/include/uapi/linux/input-event-codes.h> from the Linux kernel.

When bound to a button-type input (example: the A button), the bind is triggered when the button is pressed. When bound to an axis-type input (example: LStickUp), the event is emitted when the axis is in a non-zero position and leaves the deadzone (if any).

For KEY / BTN events:

Format:

input = Gamepad <event_code>

Example:

[Bindings]
Menu = Gamepad BTN_START

For ABS events:

Format:

input = Gamepad <event_code> <direction>

When binding a button-type input like a DPad direction or, say, the B button to an ABS event, the button will push the axis to its maximum extent in the given direction. When binding an analog axis, like a thumbstick, to an ABS value, the range of motion is mapped to the axis value in the given direction.

Examples:

[Bindings]
# Button mapped to an axis
DPadUp          = Gamepad   ABS_HAT0Y   -
# Analogue stick mapped to an axis
RStickUp        = Gamepad   ABS_Y       -
RStickDown      = Gamepad   ABS_Y       +
# Analogue trigger mapped to an axis
LTrigg          = Gamepad   ABS_Z       +

A full list of gamepad input names can be seen in the example profile.

A detailed explanation of inputs can be found in the Input Types section of this documentation.

Motion Bindings

The Motion device binding is used to generate input events for a motion control-type device. While OpenSD does not strictly enforce this, the Linux kernel and uinput specify that motion control events should be emitted by separate devices. Not doing so can create a lot of "noise", especially when configuring controls within another application. As per this spec, the Motion device only supports EV_ABS type events. These events are prefixed with ABS_ (example: ABS_Z). For a full list of event codes, see linux/input-event-codes.h <https://elixir.bootlin.com/linux/latest/source/include/uapi/linux/input-event-codes.h> from the Linux kernel.

The syntax and behaviour for binding Motion device events is the same as binding ABS events with the Gamepad device in the previous section.

Also, the Motion device is a completely separate context and namespace from the Gamepad and Mouse devices, much in the same way that two players with identical controllers will have the same buttons, but very different meanings to the game. For example, pressing A on controller #1 does not affect player #2. Its up the the end-user’s software to decide the the context and meaning of the individual events.

Format:

input = Motion <event_code> <direction>

Examples:

[Bindings]
# Bind roll attitude to Motion device
RollPlus        = Motion    ABS_X       +
RollMinus       = Motion    ABS_X       -

A full list of motion contol input names can be seen in the example profile.

A detailed explanation of motion input be found in the Input Types Section of this document.

Mouse Bindings

The Mouse device binding is used to generate input events which will be interpreted as events coming from a pointer-type device such as a physical mouse. This binding type supports button / key and relative axis events. The Mouse device can also function a bit like a keyboard, so it’s advised to bind any key events to this device.

The syntax for bindings differs slightly depending on the event type. Relative axis (EV_REL) events are prefixed with REL_ and key / button events (EV_KEY) are prefixed with KEY_ and BTN_ respectively. OpenSD supports most event codes. For a full list of event codes, see linux/input-event-codes.h <https://elixir.bootlin.com/linux/latest/source/include/uapi/linux/input-event-codes.h> from the Linux kernel.

For KEY / BTN events:

input = Mouse <event_code>

Example:

[Bindings]
RPadPress       = Mouse BTN_LEFT
QuickAccess     = Mouse BTN_RIGHT

For REL events:

[Bindings]
RPadRelX        = Mouse REL_X
RPadRelY        = Mouse REL_Y

Please see the Trackpad input type section of this documentation for a better explanation of how {L|R}PadRel{X|Y} relative inputs work.

Command Bindings

The Command binding allows you to execute external programs or scripts by forking them off as a child process. These processes run concurrently, do not return any usable exit code, and will not interrupt the driver.

Format:

input = Command <wait_for_exit> <repeat_delay_ms> <command_to_execute>

Example:

[Bindings]
QuickAccess     = Command   true    0   rofi -show run

Profile Bindings

The Profile binding type allows you to switch to a different profile using just the gamepad input. Profiles are loaded from the user profile directory. There is a 2 second delay after profile switching before the profile can be changed again, to prevent undesirable rapid cycling. If a profile fails to load, the process will be aborted and the profile currently in use will remain so.

Format:

input = Profile <profile_name>

Example:

[Bindings]
L5      = Profile   left_hand_mouse.profile

Directional Pad

The directional pad is just a set of four buttons which are diametrically exclusive — you can press up and left simultaneously but you cannot press left and right simultaneously.

Naming Convention

Descriptions

Use

A common configuration, as seen in the example profile, might look like this:

[Bindings]
DpadUp              = Gamepad   ABS_HAT0Y   -
DpadDown            = Gamepad   ABS_HAT0Y   +
DpadLeft            = Gamepad   ABS_HAT0X   -
DpadRight           = Gamepad   ABS_HAT0X   +

Buttons

These are pretty straightforward. As you probably expect, buttons have two states. They’re true when pressed and false when released. The Steam Deck borrows common names for most buttons, but also adds a few of it’s own. It’s debatable how to organize or classify these, so I’ll just sorta go by the legacy naming standards.

Naming conventions

Descriptions

Use

Thumbsticks

The thumbsticks on the Steam Deck are associated with six different inputs in OpenSD. As you would expect, there is an X/Y axis pair for each stick, but there are also touch and pressure (well, sorta) sensors located on the top of each one. The directional axes are broken into halves such that each direction can emit different events if desired.

Axis values from thumbsticks are normalized internally so they can be rescaled to the defined ABS event ranges. The hardware returns signed 16-bit integer values for axis values in the HID reports. The "pressure sensor" component has a very short numerical range, but is quite sensitive.

If Stick Filtering is enabled the full axis is internally normalized as a unit vector and a radial deadzone may be applied.

Naming convention

Descriptions

Use

# Left Stick
LStickUp            = Gamepad   ABS_Y       -
LStickDown          = Gamepad   ABS_Y       +
LStickLeft          = Gamepad   ABS_X       -
LStickRight         = Gamepad   ABS_X       +
# Right Stick
RStickUp            = Gamepad   ABS_RY      -
RStickDown          = Gamepad   ABS_RY      +
RStickLeft          = Gamepad   ABS_RX      -
RStickRight         = Gamepad   ABS_RX      +

You’re also able to treat each axis half like a button if you bind it to a key or button event code, in which case it will trigger the binding when the stick leaves the center / deadzone. You can use the deadzone in this case to determine how far the stick must be pushed from center before the binding is triggered.

Triggers

Triggers are pressure sensors that are also treated a bit like a thumbstick’s half-axis, with the difference being there’s no complement half. Triggers have a resting position of the defined axis minimum limit and move toward the maximum limit when actuated. Typically the minimum limit is zero, so the axis does not return non-zero values when released / resting, but you can do any weird thing you want.

Axis values from triggers are normalized internally so they can be rescaled to the defined ABS event ranges. Internally, the HID reports return trigger values as unsigned 16-bit integers.

Triggers also have a binary button component: L2 and R2. Information about these buttons can be found in the Buttons section.

Linear deadzones can be applied to triggers, if desired in the Deadzones Section of a profile.

Naming convention

Descriptions

Use

Trackpads

At the core, trackpads are absolute axis devices have with an X / Y pair, as well as a pressure sensor Z-axis and a slightly tactile button. A number of inputs can be extrapolated from the data those basic types provide. That includes touch sensors, press / button sensors, pressure / force sensors, absolute coordinates, relative movement tracking as well as the ability to map out regions of the pad and treat them as individual buttons. OpenSD trackpads have the most input bindings out of all the components.

As with the Thumbsticks, directional axes are broken into halves such that each direction can emit different events if desired. These halves can be mapped on to a whole ABS event code, or use separately.

Trackpads support radial deadzones for absolute axis inputs, and can be configured in the Deadzones Section of a profile.

Relative trackpad input, such as LPadRelX or LPadRelY, are not affected by deadzones and return data suitable for pointing devices like mice. These return the difference in positional movement calculated between HID frames. Some filtering is always applied to this process to reduce jitter and a small amount of intertia is also applied. The typical value range returned by these inputs is usually between -5 and +5. Binding RelX and *RelY inputs to anything other than REL_ event codes on the Mouse device is probably not useful.

Touchpads are non-multitouch devices so they only relay a single X / Y coordinate pair. I’ve read that, at a hardware level, they are supposedly multi-touch capable, but I don’t have any information on reading that data yet. If true, it will probably be supported in a future version.

OpenSD provides multiple "button maps", any of which can be used non-exclusively with each other. These "button maps" break the full area of the trackpad into logical sections which, when pressed (as opposed to being merely touched) act as individual buttons. If so desired, trackpads can be used to create "button clusters", which can be used to emulate a Directional Pad, arrow keys, run scripts, launch applications, etc. For the sake of readability, button maps are described separately below the main input descriptions.

Naming convention

Descriptions

Quadrant Button Map

The quadrant map (PadPressQuad*) provides a way to treat each touchpad as being composed of four non-overlapping triagular quadrants, as depicted in the figure 1 below. Each button is inherently exclusive to the others in this map since the X / Y coordinate can only fall inside of one of these regions at a time. This means that this map will not detect any overlapping presses, like a and b when you press in the upper-left region.

Fig. 1

┌─────────────┐
│ \         / │
│  \   a   /  │
│   \     /   │
│    \   /    │
│     \ /     │
│ b    X    c │
│     / \     │
│    /   \    │
│   /     \   │
│  /   d   \  │
│ /         \ │
└─────────────┘

Orthogonal Button Map

The orthogonal map (PadPressOrth*) works similarly to a Directional Pad. As you can see below in figure 2, it demonstrates how the "a", "b", "c" and "d" regions represent orthogonal directions which are not strictly exclusive as they are with the Quadrant Button Map. If a diagonal corner is pressed, it triggers both orthogonally adjacent buttons. For example, pressing the upper-middle of the pad only triggers "a", but pressing the upper-left of the pad will trigger both "a" and "b".

Fig. 2

┌─────┬─────┬─────┐
│     │     │     │
│  ab │  a  │  ac │
│     │     │     │
├─────┼─────┼─────┤
│     │     │     │
│  b  │     │  c  │
│     │     │     │
├─────┼─────┼─────┤
│     │     │     │
│  db │  d  │  dc │
│     │     │     │
└─────┴─────┴─────┘

2x2 Grid Button Map

This button map divides the pad into regions along the center axes, resulting in four square buttons in each corner, as depicted in figure 3. Buttons are naturally exclusive, so only one can be pressed at a time. Buttons are enumerated left-to-right, top-to-bottom.

Fig. 3

┌────────┬────────┐
│        │        │
│        │        │
│   a    │    c   │
│        │        │
│        │        │
├────────┼────────┤
│        │        │
│        │        │
│   c    │    d   │
│        │        │
│        │        │
└────────┴────────┘

3x3 Grid Button Map

This button map divides the pad into thirds along both axes, resulting in a 3x3 grid of nine square buttons, as depicted in figure 4. These buttons are naturally exclusive to one another, so only one can be pressed at a time. Buttons are enumerated left-to-right, top-to-bottom.

Fig. 4

┌─────┬─────┬─────┐
│     │     │     │
│  a  │  b  │  c  │
│     │     │     │
├─────┼─────┼─────┤
│     │     │     │
│  d  │  e  │  f  │
│     │     │     │
├─────┼─────┼─────┤
│     │     │     │
│  g  │  h  │  i  │
│     │     │     │
└─────┴─────┴─────┘

PROJECT HOME

<https://gitlab.com/open-sd/opensd>

AUTHOR

seek ( <https://gitlab.com/seek-dev>)

SEE ALSO

opensdd(1)