eagle5.network/the_manual

The Manual

"Out of order? Even in the future, nothing works!"

Quick start

1. Plug the badge into USB-C with a data-capable cable. (Charge-only cables exist and ruin your day.)
2. Watch the blue wing pulse during USB enumeration. That's normal.
3. The badge enumerates as two CDC serial ports. Pick the lower-numbered one (see "Which port is which?" below).
4. Open a serial terminal on it at 115200 baud (e.g. screen /dev/cu.usbmodem1101 115200 on macOS, screen /dev/ttyACM0 115200 on Linux, or PuTTY on Windows).
5. Press Enter to wake the EAGLE-5 console. Type help.

Don't want to fight terminal apps? Open serial.eagle5.network in Chrome/Edge/Brave/Arc. It's a WebSerial terminal pointed at the badge, no install. The badge talks over USB only; there's no wireless pairing.

Which port is which?

Two USB-CDC interfaces, both labelled "Eagle 5" in Chrome's WebSerial picker. Tell them apart by port number: the OS always counts up in USB interface order.

Port number	Interface	What it speaks
Lower cu.usbmodemNNN1 · ttyACM0 · COM<n>	CDC #0	Eagle 5 Console (CLI): the human-facing eagle5 › prompt. Use this for help, status, antenna, radio, lights, transponder, etc.
Higher cu.usbmodemNNN3 · ttyACM1 · COM<n+1>	CDC #1	Eagle 5 KISS / Reticulum: binary KISS frames for use as an RNode TNC with Sideband, NomadNet, or your own Reticulum client. Don't type into this one; KISS framing expects bytes, not text.

The OS descriptors carry the real interface names. Verify with system_profiler SPUSBDataType (macOS) or lsusb -v (Linux). Chrome's picker just doesn't render them.

LED key

LED state	Meaning
Power-on greeting	Cold-boot sequence: headlights warm up, the four orange running lights cascade on, the logo flickers to life, brake comes up, blue thrusters spin up, and the wing tip glows red. Runs once, then settles to idle.
Blue wing pulse (USB plug-in)	Boot window is open for ~3 s. Double-press USR now to drop into the UF2 bootloader (flash mode). USB only; battery boots skip the window.
Idle constellation (default)	The resting state: bright headlights, four orange running lights, brake, a soft blue thruster breathe, the backlit logo, and a red wing-tip beacon double-flash every ~1.6 s. Engines ticking over.
Sweep → Schwartz yellow-green wing flare	Radio activity: a bright spot sweeps across the badge and the wing settles to a Schwartz yellow-green each time it finishes receiving or transmitting a LoRa packet. This is the RX/TX glow flare, overlaid on whatever mode is running. Toggle with lights radio on|off (on by default).
Flight	Engines lit: same constellation, thrusters firing with an afterburner shimmer, and the wing adds a white anti-collision strobe over the red beacon.
Ludicrous speed	A streak builds front→back and accelerates to a full-white "punch it" flash, then a white-and-blue frenzy. You've gone to ludicrous speed.
Meltdown	Systems fail one at a time, everything goes dark, then a slow cold-boot brings it all back online. Loops. (Locked badges only see this from the over-the-air "Eagle 5 under attack" event.)
Disco	Full party strobe on the beat; the wing snaps through colors. Showoff mode.
Mega Maid (inward / outward sweep)	Running lights sweep inward (suck) or outward (blow) with a greenish-white / white wing. Cosmetic; reach it from the CLI animation mega_maid_suck / _blow.
Park	Standby: only the orange running lights stay lit, with a very dim, slow white wing breathe. Headlights, brake, and thrusters off.
Red brake-LED blink (~0.5 Hz)	Low battery (LOW_BATT). Everything else is dark to save power.

A short USR tap cycles the light modes. Out of the box the cycle is idle → flight → ludicrous → park. Beat the Reticulum CTF and three victory blings unlock into the cycle (idle → flight → ludicrous → meltdown → police → plaid → schwartz → disco → park):

Victory bling	Meaning
Police	Modern lightbar: discrete red and blue wing bursts (never both at once, so never purple), amber running-light triple-flashes, and a white headlight takedown.
Plaid	"We've gone to plaid!" A fast but smooth flowing rainbow tartan.
Schwartz	A slow, mystical yellow-green energy that breathes and ripples while the LEDs twinkle like a night sky. May the Schwartz be with you.

Button shortcuts

One button (USR), one slide switch (PWR). PWR is the true hard reset; everything else rides USR via taps and multi-tap gestures.

Action	What it does
PWR toggle	Hard power cycle. The "off and on again" the hardware actually understands.
USR double-press within 3 s of USB power-on	Enter UF2 bootloader for drag-and-drop or web flash. Blue wing pulse means the window is open. (USB only; no boot window on battery.)
USR held while plugging in USB	Same UF2 bootloader, via the "hard entry" path (~100 ms of hold is enough).
USR short-tap (running)	Cycle the bling / wing light modes.

No screen-cycling gestures; the badge has no display.

EAGLE-5 console (CLI)

Type at the eagle5 › prompt over USB serial. Tab-completion works on most commands.

Core commands

Command	What it does
help	List public commands. Some easter-eggs are intentionally hidden.
status	Show hardware + radio + identity status (incl. this badge's own RNode device identity hash, distinct from the RNS identity your host client uses on the mesh).
radio listen	Print every LoRa packet heard (raw frames + RSSI/SNR).
radio listen stop	Stop the listener.
radio sniff <hex_sync> [sf [freq bw [cr]]]	Listen on a foreign LoRa sync word with optional modem params (a foreign capture needs them; 0x2B is just an illustrative legacy sync word). radio sniff stop restores RNS.
prompt smart	Default. Compact eagle5 ⚡ › prompt; cursor color tracks radio state.
prompt minimal	Collapse the prompt to e5 ›. Useful when ANSI gets weird in screen.
prompt telemetry	Legacy verbose status strip (EAGLE-5 · USB · HELIX · …). Not the default.
transponder	Print this badge's squawk + Schwartz seal, presented to the finale to unlock victory blings over-air.
ctf · ops	Read-only probe. Reports whether this badge's victory blings are unlocked (CTF: UNLOCKED) or not (CTF: LOCKED). The badge does not submit flags; you submit those on the CTFd web scoreboard.

Recovery: how to un-brick

1. Soft entry to DFU: on USB power (the boot window only opens on USB, not battery), double-press USR within 3 seconds while the blue wing pulse is showing. A FTHR840BOOT volume mounts. Drag any valid .uf2 onto it.
2. Hard entry to DFU: if the boot-window doesn't trigger, hold USR while plugging in USB. About a second of hold is plenty (~100 ms is the real threshold). Same volume mounts.
3. Web flasher: from a Chrome-based browser, visit flash.eagle5.network, connect the badge via WebSerial, upload the latest UF2. No drag-and-drop required.
4. SWD nuke: if you have a Pico Probe / JLink / similar, attach to the SWD test points and reflash the bootloader directly. This is the only way out of a corrupted bootloader, which is rare enough that we won't link the procedure here. Ask at the badge desk.

The badge is a modem: you need a client

Eagle 5 is an RNode TNC, a radio modem. It speaks LoRa to the mesh and KISS over USB to whatever client you point at it. Reticulum runs on the connected client (laptop, Pi, or an Android phone on a USB-OTG cable), not the badge. To send a message, browse a BBS, post to a wall, or receive CTF flags over LXMF (which you then enter on the CTFd web scoreboard), you need one of the clients below.

Compatible clients

Client	Platform	What it gives you
Sideband ↗	Android (Play Store), F-Droid, Linux desktop, terminal	The primary phone client. LXMF messenger + Nomadnet browser + RNS identity manager. No iOS build yet: iPhone users use the laptop path.
Nomadnet ↗	Linux/macOS terminal, Pi	The canonical BBS browser + LXMF + page server. What Mr. Coffee and Mr. Radar use. Best from a laptop or a Pi over SSH.
rBrowser ↗	Web app (any browser)	Purpose-built web nomadnet browser: a small Python/Flask server that renders the BBS in your browser. Connects via its own rnsd. The laptop BBS reader.
rnsd ↗ + CLI tools	Linux/macOS/Windows (Python)	The reference RNS daemon. Pair with rncp (file copy), rnpath (route trace), rnstatus (mesh status), rnx (remote exec), or your own Python application. Required for several X-tier CTF challenges.
lxmd ↗	Linux/macOS terminal	Bare LXMF daemon (no BBS UI). For headless setups, automation, or building your own messenger.
Eagle 5 web tooling	Chromium browser	Browser-based serial terminal (serial.eagle5.network) + firmware flasher (flash.eagle5.network). No install, WebSerial-only.

Connecting Sideband (Android, USB)

1. Connect the badge to your phone with a USB-OTG cable.
2. Open Sideband → Settings → Add Connection → USB RNode and grant the USB permission prompt.
3. The badge becomes your phone's tethered RNode; all your RNS traffic rides its LoRa.

From there you can browse the Mr. Coffee and Mr. Radar BBSes, post to the Open Channel, and hit any CTF challenge the badge can hear over LoRa. No iOS USB-host support, so iPhone users take the laptop path. There's no wireless connection to the badge.

Connecting to a Pi anchor over WiFi (optional)

Want IP bandwidth for big BBS pages, file transfers, or faster CTF play? Join the venue WiFi:

Field	Value
SSID (2.4 GHz)	hth.mesh
SSID (5 GHz)	hth5.mesh
Password	Ask at the badge desk (or earn it in-mesh).

Once on hth.mesh, point your Reticulum client (Nomadnet, Sideband, etc.) at Mr. Coffee's destination over a TCPClientInterface. The BBSes will load at IP speed instead of LoRa speed.

Troubleshooting

"Badge appears dead"

Suspects, in order: (1) PWR switch is OFF. (2) AAAs drained or installed backward. Pop them out, check polarity, re-seat. (3) Charge-only USB cable (looks identical to a data one); swap it. (4) Firmware crashed at boot. Flip PWR OFF, hold USR, flip PWR ON to land in DFU.

"Serial prompt is jumping around / overwriting lines"

Your terminal isn't handling the badge's ANSI sequences well. Run prompt minimal at the EAGLE-5 prompt. Restores sanity on most clients (screen, picocom, Hyper, etc.).

"Radio appears up but nothing happens"

Two common causes: (a) you're out of LoRa range of any anchor or other badge; walk closer to Mr. Coffee or Mr. Radar. (b) The antenna selector PE4259 is in the wrong state. Try antenna ufl if you have a whip plugged in, or antenna helix for the stock copper coil.

"BBS browse hangs"

Path discovery on LoRa can take 10-30 seconds. Be patient. If it never resolves, the anchor may be offline or out of range; check announce stream in your client.

Where the code lives

• Firmware (Eagle 5 fork of RNode): private repo, will open-source post-con
• Web flasher: flash.eagle5.network
• Reticulum (upstream): github.com/markqvist/Reticulum ↗
• RNode firmware reference: github.com/markqvist/RNode_Firmware ↗

---

← reticulum  ·  next: ctf