Command protocols
Every Hurra firmware target speaks the same two command protocols. They are
selected at build time with make (Hurra binary, the default) or
make PROTOCOL=ferrum (Ferrum ASCII). The host-side hurra-app
talks the Hurra binary protocol and can bridge it to Ferrum or KMBox Net for
existing tools.
Hurra binary
The default, high-throughput protocol. TinyFrame framing:
- SOF byte
0x68 - 1-byte ID, 1-byte LEN, 1-byte TYPE
- CRC16
- little-endian payloads
Driven by hurra-app / hurra-bridge. Targets ≥8k commands/sec at 4 Mbps
over the serial link. On Hurra v2 the firmware boots at 4 Mbaud; on Hurra v3
the command USART boots at 921600 baud (WCH-LinkE VCP ceiling).
Message types
System and control:
| TYPE | Code | Meaning |
|---|---|---|
PING |
0x00 |
Liveness check |
VERSION |
0x01 |
Firmware version string |
STATS |
0x02 |
Telemetry / counters |
INIT |
0x03 |
Initialize session |
REBOOT |
0x04 |
Reboot the device |
BAUD |
0x05 |
Change link baud rate |
SCREEN |
0x06 |
Screen geometry |
HUMAN |
0x1A |
Humanization level |
Mouse:
| TYPE | Code | Meaning |
|---|---|---|
MOUSE_MOVE |
0x10 |
Relative move |
MOUSE_MOVE_SMOOTH |
0x11 |
Smoothed move |
MOUSE_SILENT_MOVE |
0x12 |
Move without buttons |
MOUSE_MO |
0x13 |
Combined mouse report |
MOUSE_CLICK |
0x14 |
Click |
MOUSE_WHEEL |
0x15 |
Wheel |
MOUSE_GETPOS |
0x16 |
Read position |
INVERT_X / INVERT_Y |
0x17 / 0x18 |
Axis inversion |
SWAP_XY |
0x19 |
Swap axes |
MOUSE_MOVE_DUR |
0x1B |
Duration-stepped move (KMBox Net automove) |
MOUSE_MOVE_BEZIER |
0x1C |
Bézier move (KMBox Net) |
Buttons:
| TYPE | Code | Meaning |
|---|---|---|
BTN_LEFT |
0x20 |
Left button |
BTN_RIGHT |
0x21 |
Right button |
BTN_MIDDLE |
0x22 |
Middle button |
BTN_SIDE1 / BTN_SIDE2 |
0x23 / 0x24 |
Side buttons |
Keyboard:
| TYPE | Code | Meaning |
|---|---|---|
KB_DOWN |
0x40 |
Key down |
KB_UP |
0x41 |
Key up |
KB_PRESS |
0x42 |
Key press (down + up) |
KB_ISDOWN |
0x43 |
Query key state |
KB_MASK |
0x44 |
Mask / block keys |
Ferrum ASCII
A \r\n-terminated text protocol for compatibility with legacy Ferrum tooling.
Built with make PROTOCOL=ferrum; runs at 115200 baud (reset to 115200 on
every power cycle).
TX: km.version()\r\n
RX: kmbox: Ferrum\r\n
TX: km.move(10, -5)\r\n # write — no reply
TX: m(2, 0)\r\n # alias for km.move
Supported command families include km.move (and the m(...) alias),
km.buttons, and km.catch (returns catch_xy / catch_result). As of
hurra-app v0.2.0 the bridge's Ferrum framing emits command echo, a
>>> prompt suffix, and case-insensitive boolean parsing, matching the Ferrum
Software-API expectations so unmodified Ferrum clients connect cleanly.
Reference: https://ferrumllc.github.io/print.html.
Which one do I use?
- Use Hurra binary (the default) with
hurra-appfor the fastest, highest-rate command channel. This is what you want for new work. - Use Ferrum ASCII only when you have an existing Ferrum-speaking tool you
cannot change — or run the default Hurra firmware and let
hurra-bridgeexpose a Ferrum-compatible virtual COM port for you, which keeps the fast binary link to the device while presenting the legacy interface to your tool.