A framework for building physical interactive consoles that manages input, state, audio, and displays using custom USB-HID boards and a Python host library.

Stars

39

7-day growth

No data

Forks

3

Open issues

0

License

MIT

Last updated

2026-07-28

AI repository intelligence
FR-AI / ANALYSIS

Why it is worth attention

Powers a real starship-bridge simulator; provides a complete, reusable reference with hardware designs, firmware, and host library; integrates state, audio, haptics, and displays in one coherent system.

Who it is for

  • Developers building physical interactive installations
  • Hobbyists creating custom control panels or simulators
  • Escape room designers
  • Arcade game makers

Use cases

  • Building a starship-bridge simulator with physical controls
  • Designing an escape room puzzle with switches and indicators
  • Creating an arcade cabinet with custom input boards
  • Developing a museum interactive exhibit with multiple displays and audio

Strengths

  • End-to-end solution covering hardware, firmware, and host software
  • Coherent state management via Spec Vars across all components
  • Layered audio engine with priority callouts and haptic support
  • Flexible display integration via WebSocket (Unity, browser, etc.)

Considerations

  • Not actively maintained; issues and pull requests unlikely to be addressed
  • Only tested on macOS Tahoe (Apple Silicon); no cross-platform support guaranteed
  • Requires custom PCB boards (three implemented, others planned) – not a ready-to-use plug-and-play system

README quick start

Enigma

A framework for building physical interactive consoles: installations where an operator works a panel of real switches, knobs, indicators, and screens. It handles input, state, audio, and displays:

  • Control surfaces: custom USB-HID boards for switches, rotary encoders, and analog inputs, each control paired with an addressable-LED indicator. The board automatically manages all indicator animation and state management without host interaction.
  • State: one coherent application state kept in sync via "Spec Vars" across multiple independent HID devices and displays, so every panel, sound, and display reacts to the same source of truth.
  • Audio and haptics: a layered, multi-channel sound engine: independently volume-controlled classes (music, voice, ambient, effects, alerts), a priority voice-callout queue, and event- or threshold-driven playback. The same engine optionally drives haptic transducers alongside the speakers.
  • Displays: optional, and anything that can hold a socket open: a local game-engine screen (Unity, Unreal, Godot), a browser page, an LED matrix, or a small networked screen on a Raspberry Pi across the room. Application state is serialized and published over WebSocket to any number of them (or none), each subscribing to only the values it needs.

Enigma is the framework the Halcyon Dawn physical starship-bridge simulator is built on. It is published here as a complete, reusable reference: the host library, the board firmware, and the PCB designs.

While building it explicitly for use in my simulator frame, I also kept in mind somewhat broader needs, such as designing electronic escape room puzzles, arcade games, and so on. The expanded list of future boards includes functionality useful for those ventures, even if the Halcyon Dawn project didn't use them.

Status: published as-is, for reference and reuse. Not actively maintained. Issues and pull requests are unlikely to be reviewed, and Issues are disabled. New boards may be added occasionally, but there is no support commitment. Fork freely; that is what the license is for.

Platform: built and tested only on macOS Tahoe (Apple Silicon). No testing has been done on other platforms, and none is planned. It may or may not work elsewhere; that is left to you.

Layout

Related repositories

Similar projects matched by category, topics, and programming language.

lopopolo
Featured
lopopolo GitHub avatar

harness-engineering

Harness Engineering is a methodology for improving coding agent outputs by carefully crafting the environment around them—providing curated context, tools, and executable constraints that encode an organization’s nonfunctional requirements and cumulative lessons.

AI & Machine LearningAI Agents
2,390
slvDev
Featured
slvDev GitHub avatar

esp32-ai

A 28.9 million parameter language model runs on an $8 ESP32-S3 microcontroller entirely on-device, generating simple stories at about 9.5 tokens per second.

AI & Machine LearningLarge Language Models
1,960
littledivy
Featured
littledivy GitHub avatar

mimic

mimic captures traffic from any iOS or web app and automatically generates a Python client library that lets you call the app's API like a regular library.

AI & Machine Learning
1,482