microReticulumTbeam/exercises/204_established_identities/README.md

# Introduction
Exercise  204 builds upon Exercise 203 where two units generate ids, announce, and then establish a LINK and exchange messages.  In Exercise 204, we add:
    OLED display
    use of established identities
    configuration of units as transports
    Allow for multiple units to be communicating

# Identities
We have 7 units: AMY...GUY.  The following command creates identities for use in this exercise.

    # Activate the Python environment that has Reticulum & pio installed
    source ~/rnsenv/bin/activate
    cd /usr/local/src/microreticulum/microReticulumTbeam/exercises/204_established_identities
    mkdir identities
    cd identities
    for n in AMY BOB CY DAN ED FLO GUY
    do
        rnid -g "./${n}.identity"
        rnid -i "./${n}.identity" -p > "./${n}.identity_info.txt"
    done

## Example run
```bash
(rnsenv) jlpoole@jp /usr/local/src/microreticulum/microReticulumTbeam/exercises/204_established_identities/identities $ for n in AMY BOB CY DAN ED FLO GUY
    do
        rnid -g "./${n}.identity"
        rnid -i "./${n}.identity" -p > "./${n}.identity_info.txt"
    done
[2026-05-28 11:26:29] New identity <c95d06fb622a80b4d80389fc7fe55d16> written to ./AMY.identity
[2026-05-28 11:26:33] New identity <5769e13e1214e62b96e43c17bd47085e> written to ./BOB.identity
[2026-05-28 11:26:38] New identity <92ce7c2eb62820c2e4476308350cc69d> written to ./CY.identity
[2026-05-28 11:26:42] New identity <d0524d8f1d98fc39f13772655640ea30> written to ./DAN.identity
[2026-05-28 11:26:46] New identity <4ad998c481ff6c71d1acb8cbaf111e1f> written to ./ED.identity
[2026-05-28 11:26:51] New identity <5671752180661e6af4bfe49e962f23dd> written to ./FLO.identity
[2026-05-28 11:26:55] New identity <051cfb95faa527b68368d24efb40f689> written to ./GUY.identity
(rnsenv) jlpoole@jp /usr/local/src/microreticulum/microReticulumTbeam/exercises/204_established_identities/identities $ 
```

# Implementation notes

`platformio.ini` defines environments for `amy`, `bob`, `cy`, `dan`, `ed`, `flo`, and `guy`.  The pre-build script `scripts/set_build_identity.py` embeds the matching `identities/<BOARD>.identity` file into the firmware and also stamps `FW_BUILD_UTC` for the OLED splash screen.

At boot the OLED shows:

```text
Exercise 204
Build
<build utc>
<BOARD>
<node label>
```

The splash is held for 10 seconds so the full build stamp can be read.

The unit then checks the RTC and `/ex204/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.  A successful GPS discipline writes a fresh marker and then starts LoRa.  Marker writes replace the old file, and marker reads use the last valid line so stale appended clock data cannot keep forcing GPS discipline.

All units run with `reticulum.transport_enabled(true)`. Path learning remains enabled, but `RNS_PERSIST_PATHS` is intentionally not defined for this exercise. Live announces are sufficient for the single-hop field test, and disabling persistent paths avoids ESP32 LittleFS `/path_store_*.dat` compaction errors during dense multi-unit announce traffic.

Each unit tracks up to six peers, so a full seven-unit field run can form one Link per ordered pair.  The lexicographically lower node initiates each pair to avoid both ends opening duplicate Links at the same time; for example `Bob` initiates to `Cy`, `Dan`, `Ed`, `Flo`, and `Guy`, while `Amy` initiates to everyone.  If an outbound link request is sent but no link becomes active, the initiator retries after 90 seconds.  This matters in field use because the first request can be missed while units are being moved, reset, or connected to monitors.

Announces and application traffic are scheduled from the RTC so all nodes do not transmit at once. Announces run once per minute at `02,06,10,14,18,22,26` for `Amy..Guy`; Link payloads run twice per minute:

```text
Amy: 04,34  Bob: 08,38  Cy: 12,42  Dan: 16,46
Ed:  20,50  Flo: 24,54  Guy: 28,58
```

Follow-up note: DAN/ED field testing showed the software version/build stamp was not visible on the OLED even though `FW_BUILD_UTC` is compiled into the splash text. Recheck the OLED startup/status path on the next firmware modification; do not rebuild solely for this note.

# Build, upload, and monitor

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

pio run -d exercises/204_established_identities -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/204_established_identities -e "${env}" -t upload
done
```

After both units have a fresh clock marker, monitor them:

```bash
pio device monitor -d exercises/204_established_identities -e bob
```

Expected first-run clock gate:

```text
SD ready
No saved clock marker; GPS discipline required
Waiting for GPS UTC before LoRa startup
gps_gate time=0 fix=0 sats=-1 pps_ms=0
```

Expected LoRa/link traffic after the clock gate:

```text
Local Identity: <identity hash>
Local SINGLE destination: <destination hash>
TX ANNOUNCE: Bob
RX ANNOUNCE: label=Cy hash=<destination hash>
TX LINKREQUEST: opening link to Cy
LINK ACTIVE: initiator link established
TX LINK: Hi from Bob iter=0 to=Cy
RX LINK: Hi from Cy iter=0 to=Bob | RSSI=... SNR=...
```