microReticulumTbeam/exercises/205_sustained_link/README.md

# Introduction
Exercise 205 builds on Exercise 204 established identities and LoRa Link traffic. It keeps the same identity, announce, RTC/GPS, OLED, and machine-parseable TX/RX event style, but changes the link policy for longer multi-unit field runs.

All seven units, `AMY` through `GUY`, are supported. Every unit runs in transport mode and every unit attempts to open a Link to any other unit that announces.

# Behavior

The announce protocol is intentionally the same as the last Exercise 204 protocol:

```text
startup announce: immediate
second announce:  ANNOUNCEMENT_2 seconds after startup, default 300
repeat announce:  ANNOUNCEMENT_REPEAT seconds after that, default 3600
```

There is no simulated BOB/CY physical block in this exercise. `SIM_PHY_ENVELOPE` remains enabled so log records can report the physical sender slot, but `SIM_PHY_BLOCK_BOB_CY=0` for every environment.

Exercise 205 does not intentionally tear down Links after a message count. A Link is reused while it remains active. The app-level stale threshold is 12 hours. If a Link becomes stale or closes, the unit clears local state and attempts to recreate the outbound Link.

Each unit sends one Link message per active peer per minute at its allocated second:

```text
AMY: 04  BOB: 08  CY: 12  DAN: 16
ED:  20  FLO: 24  GUY: 28
```

The message payload uses board IDs and includes an iteration counter:

```text
BOB says Hi to CY iter=0
```

The outbound Link retry budget is:

```text
retry interval: 60 seconds
failure window: 3 minutes
max attempts:   3
```

After three failed attempts within the window, the peer is marked failed and no more Link requests are sent to that peer until another announce for that peer is received. A fresh announce resets the retry budget and starts over.

# Clock Gate

The unit checks the RTC and `/ex205/clock.txt` on the SD card. If the saved discipline marker is less than 24 hours old according to the RTC, LoRa/microReticulum starts immediately. If not, the OLED shows `Take outside` and serial prints `gps_gate ...` until GPS UTC/fix is available.

# Log Events

Substantive events retain the Exercise 204 style so multi-unit log parsing can correlate TX and RX:

```text
TX ANNOUNCE: Bob SF=7 BW=125.0 CR=4/5 TXP=14
RX PHY: phy=2 len=... RSSI=-73.5 SNR=9.2 SF=7 BW=125.0 CR=4/5 TXP=14 frames=...
RX ANNOUNCE: label=Cy hash=<destination hash> phy=Cy(2) RSSI=-73.5 SNR=9.2 SF=7 BW=125.0 CR=4/5 TXP=14
TX LINKREQUEST: opening link to Cy slot=19 attempt=1/3 SF=7 BW=125.0 CR=4/5 TXP=14
LINK ACTIVE: initiator link established to Cy hash=<link hash>
RX LINK: inbound link established hash=<link hash> phy=Bob(1) RSSI=-74.0 SNR=8.8 SF=7 BW=125.0 CR=4/5 TXP=14
TX LINK: BOB says Hi to CY iter=0 via=outbound hash=<link hash> status=2 SF=7 BW=125.0 CR=4/5 TXP=14
RX LINK: CY says Hi to BOB iter=0 | phy=Cy(2) RSSI=... SNR=... SF=7 BW=125.0 CR=4/5 TXP=14
LINK RETRY: no establishment after 60000 ms; retrying Cy attempts=1/3
LINK FAILED: peer=Cy attempts=3 window_ms=... waiting_for_announce=1
LINK RETRY RESET: fresh announce from Cy
```

`RX PHY` is emitted once per accepted LoRa frame before Reticulum decrypts or routes it. It is the broadest signal-strength record and includes frames that become announces, link setup packets, encrypted Link payloads, keepalives, or proofs. `RX PHY BAD` and `SIM PHY DROP` also include RSSI/SNR and radio settings when malformed or intentionally blocked frames are seen. `SF`, `BW`, `CR`, and `TXP` come from the firmware build flags; transmit power is fixed by `LORA_TX_POWER_DBM` and is not dynamically changed by Exercise 205.

The following `RNS...` prefixes are generated by the linked microReticulum tree when Arduino link instrumentation is enabled:

| Prefix | Source | Meaning |
| --- | --- | --- |
| `RNSLINKREQ` | `microReticulum/src/Link.cpp` | Incoming Link request validation accepted; shows the new link ID, owner destination, hops, status, initiator flag, interface, and whether the app has a link-established callback. |
| `RNSPROOF_DELAY` | `microReticulum/src/Link.cpp` | Link proof send path is applying the configured proof delay before transmitting the proof packet. |
| `RNSPROOF` | `microReticulum/src/Link.cpp` and transport proof probes | Link proof validation and proof forwarding diagnostics, including signature validity, state transitions, interface checks, and exceptions. |
| `RNSLRRTT` | `microReticulum/src/Link.cpp` | Link request round-trip-time packet handling. This is part of Link establishment and marks decrypt, active, and owner callback events. |
| `RNSLINKRX` | `microReticulum/src/Link.cpp` | Link-associated packet receive path. It logs packet context, decrypt success, app packet callback entry/return, no-callback cases, and LRRTT dispatch. |
| `RNSDEC` | `microReticulum/src/Link.cpp` | Link encryption/decryption token diagnostics, including encrypt attempts, decrypt attempts, and decrypt failure class. |

If `RNSLINKRX event=decrypt_ok` is followed by `event=no_packet_callback`, the encrypted Link payload was successfully decrypted but the application packet callback was not installed on that Link object. Current firmware asks the Link owner callback to bind late in that case, so the expected sequence is `late_owner_callback_enter`, `late_owner_callback_return callback=1`, `callback_enter`, and then the app-level `RX LINK: ...` line.

Reticulum library logging is set to warning level in this exercise. Heap, path-store, entries, and byte-count diagnostics are intentionally suppressed so serial logs remain focused on field-test results.

# Build, Upload, And Monitor

```bash
source /home/jlpoole/rnsenv/bin/activate
cd /usr/local/src/microreticulum/microReticulumTbeam

pio run -d exercises/205_sustained_link -e amy -e bob -e cy -e dan -e ed -e flo -e guy

for env in amy bob cy dan ed flo guy
do
  pio run -d exercises/205_sustained_link -e "${env}" -t upload
done
```

Monitor one unit:

```bash
pio device monitor -d exercises/205_sustained_link -e bob
```