Skip to content

hurra-app — host bridge

Host-side adapter for the Hurra binary protocol.

The primary product is hurra-bridge — a small daemon that talks to the firmware over the real serial link and exposes a friendlier endpoint to your tools. The underlying libhurra library (used internally by the bridge) is also available for C/C++ projects that want to drive the Hurra protocol directly.

  • Targets: macOS, Linux, Windows.
  • Real-link baud: 4 Mbps default, matching the firmware's Hurra-build default — so --baud is usually unnecessary.

Download hurra-bridge

Endpoints

At startup the bridge shows an interactive menu and asks which endpoint to expose:

Select endpoint:
  1) Virtual COM port  (Ferrum-compatible)
  2) KMBox Net         (UDP)

A terminal (TTY) is required to make this selection. Running the bridge non-interactively — piped, redirected, or in CI — causes it to exit with an error (No terminal to choose an endpoint).

Option 1 — Virtual COM port (Ferrum)

The bridge exposes a PTY (Unix) or virtual COM port pair (Windows) that Ferrum-speaking tools connect to. Existing Ferrum tools (e.g. ferrum_aim_test.py) work unchanged against Hurra firmware.

Option 2 — KMBox Net (UDP)

The bridge emulates the device side of the KMBox Net UDP protocol. Clients that already speak KMBox Net connect by pointing at the host machine's IP and the UDP port set by --km-port (default 16896). If --km-mac is set, clients must present that 4-byte MAC on connect; the default 0 accepts any client.

What works over KMBox Net now: mouse move, left / right / middle buttons, wheel, the combined mouse report, the full keyboard report, and reboot.

Recognized but pending firmware support (the bridge ACKs but does not yet act): automove (smoothed move), bezier move, monitor (physical-input streaming), and mask/unmask (blocking physical input). These features live on the device by design and require new firmware support; they are not emulated on the host.

Quickstart — macOS / Linux

The bridge owns the real serial port and exposes a pseudo-terminal that Ferrum-speaking tools connect to. A symlink at $HOME/.hurra-bridge.tty points at whatever PTY slave the kernel allocated, so clients can hardcode a stable path.

# Terminal 1 — bridge (4 Mbaud default; add --baud N only to override).
# --device is optional on Unix: with exactly one serial port present, the
# bridge auto-detects it.
./hurra-bridge --device /dev/cu.usbmodem01
#
#   ✓ Serial device   /dev/cu.usbmodem01 @ 4 Mbaud
#   ✓ Virtual port    /dev/ttys004
#     └ linked at     /Users/you/.hurra-bridge.tty
#   ✓ Firmware        responding
#
#   Ready. Point your Ferrum tool at /Users/you/.hurra-bridge.tty

# Terminal 2 — point any ferrum-speaking tool at the symlink
~/code/Hurra-v2/tools/ferrum_aim_test.py --port ~/.hurra-bridge.tty

Output is colorized with a live status line when stderr is a terminal. When piped or redirected (not a TTY), or when NO_COLOR is set or --no-color is passed, the bridge prints plain, greppable lines instead.

Build from source

cmake -S . -B build
cmake --build build

Produces:

  • build/hurra-bridge — bridge daemon (primary product)
  • build/libhurra.a — static library (or hurra.lib on Windows)
  • build/hello — minimal smoke-test for the library

On Unix you can also just make, a thin wrapper around the two CMake commands.

Source and full docs: github.com/VoltCyclone/hurra-app.