Docs / deejx

users and developers / 0.1.1

Build and hardware setup

Build the Linux driver, prepare the profile, and understand the experimental ESP32 firmware.

Build and hardware setup

Before you start

The current working audio implementation is the Linux PulseAudio client. Have a PulseAudio-compatible server running in your user session, a Rust toolchain that supports edition 2024, and the development libraries required by the driver dependencies. On Linux those include PulseAudio and libudev development files; package names vary by distribution.

For hardware development, the included firmware targets an original ESP32 with analog sliders or potentiometers and a USB serial connection. Use the board’s 3.3V supply and GND for the potentiometer endpoints, with each wiper connected to a suitable analog input. Do not feed a 5V slider signal into an ESP32 GPIO.

Build the desktop driver

git clone https://github.com/DcZipPL/deejx.git
cd deejx
cargo build --release --package deejx-driver

The executable is target/release/deejx-driver. The desktop driver is the only enabled member of the root Cargo workspace; this command does not build the firmware or a companion UI.

Before running, create the Linux profile at ~/.config/deejx/profile.deejx.yml (or the matching XDG location) using the complete configuration example. Set the actual serial port and ensure your user can access it.

./target/release/deejx-driver

The driver runs in the foreground and logs configuration and connection errors. Stop it with Ctrl+C. It retries an unavailable serial port every 500 milliseconds. Run it in your normal audio user session rather than using root as a workaround for serial permissions.

Firmware status and toolchain

Warning

The checked-in firmware is unfinished: the ADC sampling and UART packet transmission inside its main loop are commented out. It also contains incomplete ADC setup code. The following commands describe the repository’s intended development workflow, not a verified flash-and-run installation procedure.

firmware/rust-toolchain.toml selects the esp toolchain. Set up the matching Espressif Rust environment and espflash before trying the firmware build. The repository’s justfile expects a local ~/export-esp.sh environment script; it is not supplied by this project.

cd firmware
# Load your installed Espressif Rust environment first.
cargo build
espflash flash ./target/xtensa-esp32-none-elf/debug/firmware

The configured inputs are GPIO34 and GPIO35. Some local variable names refer to pin 32 even though the assigned peripheral is GPIO34; use the actual GPIO assignments when inspecting the code. Confirm the order of values that your completed firmware transmits before arranging desktop mappings.

Serial packet format

The desktop reader expects a binary packet, not a line of text:

Part Encoding

Header

One byte: 0xAA.

Count

One byte containing the number of slider values.

Values

count unsigned 16-bit values in little-endian order.

Checksum

One byte: XOR of the count byte and every value byte, excluding the header.

The desktop audio code uses 2047 as its raw full-scale value. Use compatible value scaling and make sure the desktop mappings list covers every received value. Invalid checksums are skipped with a warning.

Troubleshooting

  • Profile does not load: include every required field, especially timeout, and check YAML indentation.

  • Serial connection keeps retrying: check the device path, cable, user permissions, and whether another process has the port open.

  • Port opens but nothing happens: the checked-in firmware does not send data. Confirm that your firmware emits valid packets and uses the same baud rate as the desktop profile.

  • Wrong slider controls an application: mappings use packet position; changing pin alone does not change routing.

  • Windows build fails: the Windows audio controller is not implemented in this revision.

See firmware source, packet decoding, and build recipes for the revision described here.