Slider configuration

Profile location, required YAML fields, mapping order, and current limitations.

Slider configuration

Profile location

The driver looks for profile.deejx.yml in the deejx directory under the XDG configuration root. On Linux this is normally ~/.config/deejx/profile.deejx.yml, or $XDG_CONFIG_HOME/deejx/profile.deejx.yml when that variable is set.

On first startup it creates the parent directory and copies the bundled example if no profile exists.

Important

The bundled example omits timeout, but the configuration type requires it. Add timeout: 1000 before expecting the profile to load successfully. No configuration fields have Serde defaults at this revision.

Example profile

This example describes two packet values: first an output-device volume control, then an application volume control. Adjust the port, audio targets, and mapping order for your hardware. The baud rate matches the checked-in firmware’s UART setting, although its transmit loop still needs implementation.

mappings:
  - pin: 34
    master: 0
    inverted: false
  - pin: 35
    app: "spotify"
    inverted: false
serial: /dev/ttyUSB0
baud_rate: 115200
timeout: 1000
quality: default

Connection fields

Field Meaning

Field	Meaning
`mappings`	Ordered list of slider mappings. Provide at least as many entries as the firmware sends values; the driver indexes this list directly.
`serial`	Serial device path. `/dev/ttyUSB0` is an example, not automatic device detection.
`baud_rate`	Must match the firmware. The checked-in ESP32 UART is set to `115200`; the bundled desktop example instead contains `9600`.
`timeout`	Serial read timeout in milliseconds. Required, for example `1000`.
`quality`	Required enum: `low`, `default`, or `high`. Parsed but not used for filtering in the current desktop loop.

mappings

Ordered list of slider mappings. Provide at least as many entries as the firmware sends values; the driver indexes this list directly.

serial

Serial device path. /dev/ttyUSB0 is an example, not automatic device detection.

baud_rate

Must match the firmware. The checked-in ESP32 UART is set to 115200; the bundled desktop example instead contains 9600.

timeout

Serial read timeout in milliseconds. Required, for example 1000.

quality

Required enum: low, default, or high. Parsed but not used for filtering in the current desktop loop.

Mapping targets

Each mapping requires pin and inverted, plus one target field below. Omit the target only if you intentionally want an unsupported unmapped entry.

Target Behavior

Target	Behavior
`master: 0`	Controls an output device by its PulseAudio index. Zero is an example index, not a special selector for the current default output.
`device: "output-name"`	Controls an output device by its PulseAudio name.
`app: "spotify"`	Matches active audio streams whose lowercased application name contains the configured string. Use a lowercase substring; matching is not an executable-path lookup. Multiple matching streams can be updated.
`midi: 10`	Accepted by the parser, but MIDI output is not implemented.
No target field	Accepted as an unmapped control, but control of unassigned applications is not implemented.

master: 0

Controls an output device by its PulseAudio index. Zero is an example index, not a special selector for the current default output.

device: "output-name"

Controls an output device by its PulseAudio name.

app: "spotify"

Matches active audio streams whose lowercased application name contains the configured string. Use a lowercase substring; matching is not an executable-path lookup. Multiple matching streams can be updated.

midi: 10

Accepted by the parser, but MIDI output is not implemented.

No target field

Accepted as an unmapped control, but control of unassigned applications is not implemented.

Warning

Mapping order determines which slider controls each target. The desktop loop does not use pin to route packet values and does not apply inverted. Keep these fields in the YAML because they are required by the parser, but do not rely on them to reorder or invert sliders. Specify only one target field per mapping.

Reloading and troubleshooting

Save the YAML file while the driver is running to request a reload. The watcher handles data-change notifications; editors that replace the file by renaming a temporary file may require a driver restart. Invalid YAML or missing fields can pause processing until a valid configuration is loaded.

If a slider has no effect, check that the application is currently producing an audio stream, that the lowercase name matches, and that mapping order agrees with the packet order. Small changes are ignored until the raw value differs by at least 64, with special handling at the endpoints. Move the slider after startup: the first packet initializes previous values without applying them.

See configuration parsing and reload behavior and mapping dispatch.