enigma (host library)

The Python side of Enigma: it enumerates the USB-HID boards, applies JSON configs (control names, LED schemes, thresholds), reads control-state changes, drives indicator LEDs, and publishes state to companion displays over WebSocket.

Install

pip install .

That pulls the core runtime dependencies: hid and pyusb (USB-HID access) and python-socketio[asyncio_client] (which brings in aiohttp) for the WebSocket client that publishes spec values to displays.

Two optional extras add subsystem-specific dependencies, installed only if you ask for them:

The audio packages have native prerequisites (PyAudio needs PortAudio), so they are kept out of the base install for anyone who only wants control-surface and display functionality.

How it works

EnigmaManager owns the boards and the displays. You hand it a ConfigManager pointed at your JSON config directory; it reads the configs, brings up every connected board, and from then on each update() tick polls hardware, runs your device logic, drives the indicator LEDs, and pushes changed spec values to any connected displays.

For a runnable end-to-end version, see examples/engine-sw/.

Package layout

The generated control classes (EngineControl etc.) aren't a module here: they are produced from the configs; their interface is the Control reference.

Code generation

The Spec, control, and audio classes your code imports are generated from the JSON configs. Regenerate after editing any config:

./mk.sh

mk.sh is a convenience wrapper over the three generators in enigma/tools/; see CODE_GENERATION.md for what each one does and the switches they take. The generators emit both Python code and reference docs.

Command-line tools

In enigma/tools/:

• enigma_cli.py: inspect and exercise connected boards from a shell
• hid_monitor.py: watch raw HID traffic to and from a board
• generate_controls.py / generate_devices.py / generate_audio.py: the code generators (mk.sh runs all three)
• gpro-daemon-*.sh: build, install, and manage the G Pro keyboard daemon

Documentation

Full reference documentation lives in enigma/docs/. Start with the design guide, then:

• Board configuration: SW14, QD04, AN08
• Device specs and control mappings
• Audio configuration and audio usage
• Displays: development, WebSocket protocol
• HID wire protocol
• API reference: Manager, Panel, Device, Control, Audio

Example

examples/engine-sw/ is a complete end-to-end slice: a Python app that defines a spec and publishes values, its JSON board and display config, a Flask browser display, and a Unity receiver. See examples/.

Elsewhere in the repo

• Repository overview: what Enigma is, top-level map
• Firmware: the C/C++ that runs on the boards
• Hardware: the PCB designs

License

MIT; see the repository root LICENSE. Source files carry SPDX identifiers.