docs/lora/foxmash-protocol.md

@@ -20,7 +20,7 @@ Pseudo-Byte-Stream:
 
 ### Structure:
 
-* **Byte 0: `"{ "` (0x7B)**
+* **Byte 0: `{` (0x7B)**
   * **Data Type Identifier (DTI):** Derived from the APRS & MeshCom protocol specification (see [APRS Protocol Reference](https://ui-view.net)).
   * **Reasoning:** This data type identifier is currently marked as `[Unused]` in the specification, and the character visually resembles a station icon.
 
@@ -33,5 +33,59 @@ Pseudo-Byte-Stream:
   * **Extended Notation (IDs ≥ 100):** If the station number exceeds 100, you may take any letters as described in https://aprs11/SSIDs.txt (e.g., `OE3TKT-S6` for any special 6th station).
   * **Backup / Hot-Standby Nodes:** To designate a station as a replacement node or an immediate hot-standby node, the hyphen is replaced by a tilde symbol (e.g., `OE3TKT~03`).
 
-* **Bytes 10–13: Telemetry Data (`nnnnnn`)**
+* **Bytes 10–13: Telemetry Data (`nnnnnn` / Timestamp)**
   * **Timestamp:** Signed 32-bit integer representing the number of milliseconds since the start of the competition day.
+
+* **Byte 14: Own Battery Level**
+  * **Value:** Unsigned 8-bit integer (`unsigned char`) representing the node's own battery capacity in percent (0 to 100%).
+      A value of `100` (0x64) means fully charged, while `0` means empty.
+      Values above 100 can be used to indicate charging or mains power (e.g., `255`).
+
+* **Bytes 15+: Heard Neighbor Nodes (Format: `xRSqxRSqxRSq...`)**
+  * Each neighbor node found in the mesh is represented by a multi-byte block containing its SSID, link quality, and battery status.
+  * **Bytes 15–16 (x):** Neighbor SSID (16-bit unsigned integer, e.g., `0x0003` for station number 3).
+  * **Byte 17 (R):** RSSI value + 164 stored as an `unsigned char` (e.g., `0x3A` = 58 ➡️ 58 - 164 = -106 dBm).
+  * **Byte 18 (S):** SNR value multiplied by 4 stored as a `signed char` (e.g., `0x42` = 66 ➡️ 66 / 4 = +16.5 dB).
+  * **Byte 19 (q):** Combined Quality and Battery Status Byte:
+    * **Bits 7–6 (Battery Status of the neighbor):**
+      * `00` = Normal (Battery OK / Powered)
+      * `01` = Low (Battery low, intervention recommended)
+      * `10` = Critical (Battery critical, node might shut down soon)
+      * `11` = Reserved
+    * **Bits 5–0 (Counter):** Moving average counter of how many times this station was heard within the last 30 minutes (Max value: 63). If this counter is ≥ 3, the neighbor is considered a stable link. Stations not heard at least once within 30 minutes are dropped from the list.
+
+## Checkpoint Messages (Posten)
+
+As soon as a participant checks in at a checkpoint using their RFID tag or identifier, they are registered at that node. The runner is assigned a timestamp and their ID (runner number). The mapping between the runner number and the RFID code is stored within the system. During the next available time slot, a checkpoint message is transmitted to the destination with QoS 2 (guaranteed packet delivery, duplicate detection, and filtering).
+
+Messages are sent to the destination and optionally to the start node simultaneously. Both nodes must have an SSID < 15, as the remaining bits in the address byte are reserved for protocol flags.
+
+This message packet is designed to be extremely short and efficient. It contains the node number, runner number, capture timestamp, and the current hop count.
+
+Pseudo-Byte-Stream:
+`vppMLzzzzRR`
+
+### Structure (Checkpoint Message):
+
+* **Byte 0: `(` (0x40)**
+  * **Data Type Identifier (DTI):** Special identifier designated for FoxMash checkpoint messages.
+
+* **Bytes 1–2: Own SSID (`pp`)**
+  * **Value:** 16-bit unsigned integer (`uint16_t`) of the transmitting checkpoint node.
+
+* **Byte 3: `M` (Target SSID, Hop Count & Flags)**
+  * **Bits 7–5 (Hop Count):** Dynamic routing counter. If the node sees the destination directly with good quality, this value is `0`. If no acknowledgment is received within 5 minutes, the permitted hop value is incremented by one. If the hop value exceeds the defined maximum, the packet is discarded.
+  * **Bit 4 (ACK Flag):** `0` for a standard data message, `1` for an acknowledgment packet (ACK).
+  * **Bits 3–0 (Target SSID):** The SSID of the destination node (Supports IDs from 0 to 15).
+
+* **Bytes 4–5: `L` (Runner Number)**
+  * **Value:** 16-bit unsigned integer (`uint16_t`) for unique participant identification (Supports IDs from 0 to 65,535).
+
+* **Bytes 6–9: `zzzz` (Timestamp)**
+  * **Value:** Signed 32-bit integer (milliseconds since the start of the day) capturing the exact time the runner checked in at the post. Also used to verify packet validity within the allowed time window.
+
+* **Bytes 10+: `RR` (Routing List / Optional)**
+  * **Value:** Optional list of intermediate nodes. For example, when utilizing three relay nodes, this field is structured as `RR RR RR`. It remains empty if a direct connection is established.
+
+### Acknowledgments and Retries
+The maximum number of retries is configurable (default: 4). Every checkpoint packet must be acknowledged. The acknowledgment uses the exact same format (`vppMLzzzzRR`), but with **Bit 4 in Byte 3 (`M`) set to `1`**. The return routing follows the identical path in the reverse direction based on the route recorded in the packet (source routing). Remit nodes detect and discard duplicate packets by matching the runner's unique timestamp.

docs/lora/foxmash-protocol_de.md

@@ -10,17 +10,16 @@ Dies geschieht, wann immer möglich, zu Zeiten, in denen kein Sendebetrieb des F
 Dies dient einerseits der Zeitsynchronisation der Nachbarknoten und andererseits der regelmäßigen, behördlich vorgeschriebenen Aussendung des Rufzeichens.
 Üblicherweise wird das Rufzeichen des Ausrichters bzw. Veranstalters des Peilwettbewerbs verwendet.
 
-## Bake
+## Bake (Broadcast)
 
 Setzt sich wie folgt aus den modifizierten AX.25-, APRS- und MeshCom-Protokollen zusammen:
 
 Pseudo-Byte-Stream:
-`{OE3TKT-03nnnnxxRSqyyRSqzzRSq`
-
+`{OE3TKT-03nnnnxxRSqxxRSqxxRSq`
 
 ### Struktur:
 
-* **Byte 0: `"{ "` (0x7B)**
+* **Byte 0: `{` (0x7B)**
   * **Data Type Identifier (DTI):** Abgeleitet aus der APRS- & MeshCom-Protokollspezifikation (siehe [APRS Protocol Reference](https://ui-view.net)).
   * **Begründung:** Dieser Datentyp-Bezeichner ist in der Spezifikation derzeit noch als `[Unused]` (unbenutzt) markiert, und das Zeichen sieht visuell wie ein Stationssymbol aus.
 
@@ -33,16 +32,75 @@ Pseudo-Byte-Stream:
   * **Erweiterte Notation (IDs ≥ 100):** Wenn die Stationsnummer 100 überschreitet, können beliebige Buchstaben verwendet werden, wie unter https://aprs11/SSIDs.txt beschrieben (z. B. `OE3TKT-S6` für eine beliebige spezielle 6. Station).
   * **Ersatz- / Hot-Standby-Knoten:** Um eine Station als Ersatzstation oder sofort einsatzbereiten Knoten zu kennzeichnen, wird der Bindestrich durch ein Tilde-Zeichen ersetzt (z. B. `OE3TKT~03`).
 
-* **Bytes 10–13: Telemetriedaten (`nnnnnn`)**
+* **Bytes 10–13: Telemetriedaten (`nnnnnn` / Zeitstempel)**
   * **Zeitstempel:** Vorzeichenbehaftete 32-Bit-Ganzzahl (Signed 32-Bit Integer), die die Millisekunden seit Beginn des Wettbewerbstages darstellt.
+  Dieser Zeitstempel dient gleichzeitig auch als Nachrichten-ID, und die gesamte Nachricht wird gehasht und damit kann festgestellt werden, ob sie doppelt ist.
 
+* **Byte 14: Eigener Batteriestand**
+  * **Wert:** Vorzeichenlose 8-Bit-Ganzzahl (`unsigned char`), die die eigene Batteriekapazität in Prozent (0 bis 100 %) darstellt. Ein Wert von `100` (0x64) bedeutet voll geladen, `0` bedeutet leer. Werte über 100 können optional für Netzbetrieb oder Ladevorgang reserviert werden (z. B. `255`).
 
-`xxRSqyyRSqzzRSq` soll so etwas sein: Gehörte Nachbarknoten im Mesh mit einem Byte das die Qualität der Linkverbinung beinhaltet. xx ist z.B. ein Knoten mit SSID xx, und q ist die Qualtität der Verbinung:
- q setzt sich zusammen aus: bit 7: 1 ... diese SSID (Nachbar) wurde in der letzten halben Stunde mindestens 3 mal empfangen.
- 0 wenn das nicht der Fall ist (weniger als 3 mal gehört in den letzten 30 Minuten), aber zumindest einmal gehört, ansonsten verschwindet er aus der Liste.
- bit 6-0 Zahler wie oft die Station gehört wurde (gleitender Wert pro 30 Minuten).
- R ist der negative RSSI-Wert in unsigned char. und S entspricht dem vierfachen SNR-Wert (signed char).
+* **Bytes 15+: Gehörte Nachbarknoten (Format: `xxRSqxxRSqxxRSq...`)**
+  * Jeder im Mesh gefundene Nachbarknoten wird durch einen Multi-Byte-Block dargestellt, der seine SSID, die Link-Qualität und den Batteriestatus enthält.
+  * **Bytes 15–16 (x):** Nachbar-SSID (16-Bit Unsigned Integer, z. B. `0x0003` für Stationsnummer 3).
+  * **Byte 17 (R):** RSSI-Wert + 164 als `unsigned char` (z. B. `0x3A` = 58 ➡️ 58 - 164 = -106 dBm).
+  * **Byte 18 (S):** Vierfacher SNR-Wert als `signed char` (z. B. `0x42` = 66 ➡️ 66 / 4 = +16.5 dB).
+  * **Byte 19 (q):** Kombiniertes Qualitäts- und Batteriestatus-Byte:
+    * **Bits 7–6 (Batteriezustand des Nachbarn):**
+      * `00` = Normal (Batterie OK / Netzbetrieb)
+      * `01` = Niedrig (Batterie schwach, Wartung empfohlen)
+      * `10` = Kritisch (Batterie kritisch, Knoten fällt bald aus)
+      * `11` = Reserviert
+    * **Bits 5–0 (Zähler):** Gleitender Zähler, wie oft diese Station in den letzten 30 Minuten gehört wurde (Maximalwert: 63). Wenn dieser Zähler ≥ 3 ist, gilt der Nachbar als stabiler Link. Stationen, die innerhalb von 30 Minuten kein einziges Mal gehört wurden, werden aus der Liste gelöscht.
 
- Beispiel: `0x00 03 9a 42 87...`
+Falls der eigne Knoten die Ziel/Start-Knoten nicht selbst sehen, so müssen
 
-Das bedeutet "0x00 03" ist die SSID mit der Zahl 3 (der Nachbar der gehört wird), 0x9a ist dezimal  154
+## Nachrichten von Posten
+
+Sobald eine Person am Postenschirm seine Kennung bekannt gibt wird er an diesem Knoten registriert.
+Ein Zeitstempel und seine ID wird zugewiesen (Läufernummer).
+Die Läufernummer und die entsprechende RFID-Nummer ist im System hinterlegt und es wird beim nächsten Zeitschlitz eine Posten-Nachricht an das Ziel verschickt.
+
+Das Ziel und der Start-Knoten ist dem System bekannt (muss nicht zwingend SSID 0 haben).
+Jedoch: Muss eine SSID < 15 haben, da wir die anderen bits für Flags verwenden.
+Eventuell wird an beide Knoten, Ziel und Start gleichzeitig verschickt.
+Die QoS ist dabei nicht mehr 0 sondern 2. (Sicherstellung der Paketzustellung und doppelte Pakete werden erkannt und weggeworfen).
+
+Dieses Nachrichtenpaket ist sehr kurz und effizient aufgebaut:
+
+Wir brauchen folgende Informationen: Knotennummer, Läufernummer, Zeitstempel, und der wievielte Hopp es ist.
+
+## Nachrichten von Posten
+
+Sobald sich ein Teilnehmer am Postenschirm per RFID/Kennung anmeldet, wird er an diesem Knoten registriert. Dem Läufer wird ein Zeitstempel und seine ID (Läufernummer) zugewiesen. Die Verknüpfung zwischen Läufernummer und RFID-Code ist im System hinterlegt. Beim nächsten verfügbaren Zeitschlitz wird eine Posten-Nachricht mit der Dienstgüte QoS 2 (Sicherstellung der Paketzustellung, Erkennung und Verwerfen von Duplikaten) an das Ziel übermittelt.
+
+Die Nachrichten werden an das Ziel und optional gleichzeitig an den Start-Knoten gesendet. Beide Knoten müssen eine SSID < 15 besitzen, da die verbleibenden Bits im Adress-Byte für Protokoll-Flags reserviert sind.
+
+Dieses Nachrichtenpaket ist extrem kurz und effizient aufgebaut. Es enthält die Knotennummer, die Läufernummer, den Zeitstempel der Erfassung sowie den aktuellen Hop-Zähler.
+
+Pseudo-Byte-Stream:
+`vppMLzzzzRR`
+
+### Struktur (Posten-Nachricht):
+
+* **Byte 0: `(` (0x40)**
+  * **Data Type Identifier (DTI):** Spezieller Bezeichner für FoxMash-Postenmeldungen.
+
+* **Bytes 1–2: Eigene SSID (`pp`)**
+  * **Wert:** 16-Bit vorzeichenlose Ganzzahl (`uint16_t`) des sendenden Posten-Knotens.
+
+* **Byte 3: `M` (Ziel-SSID, Hop-Limit / TTL & Flags)**
+  * **Bits 7–5 (Hop-Limit / TTL):** Startwert für die maximale Anzahl an erlaubten Hops (Time-to-Live). Der Startknoten setzt diesen Wert (z. B. auf 3). Jeder weiterleitende Zwischenknoten verringert (dekrementiert) diesen Wert um 1. Erreicht der Wert `0`, wird das Paket nicht mehr weitergeleitet und verworfen.
+  * **Bit 4 (ACK-Flag):** `0` für eine normale Nachricht, `1` für ein Bestätigungspaket (ACK).
+  * **Bits 3–0 (Ziel-SSID):** Die SSID des Zielknotens (Unterstützt IDs von 0 bis 15).
+
+* **Bytes 4–5: `L` (Läufernummer)**
+  * **Wert:** 16-Bit vorzeichenlose Ganzzahl (`uint16_t`) zur eindeutigen Identifikation des Teilnehmers (Unterstützt IDs von 0 bis 65.535).
+
+* **Bytes 6–9: `zzzz` (Zeitstempel)**
+  * **Wert:** Vorzeichenbehaftete 32-Bit-Ganzzahl (Millisekunden seit Tagesbeginn), die den exakten Zeitpunkt der Registrierung des Läufers am Posten festhält. Dient auch zur Gültigkeitsprüfung im Zeitrahmen.
+
+* **Bytes 10+: `RR` (Routingliste / Optional)**
+  * **Wert:** Optionale Liste der Zwischenknoten. Bei der Verwendung von beispielsweise drei Relaisknoten setzt sich das Feld aus `RR RR RR` zusammen. Bleibt leer, wenn eine Direktverbindung besteht.
+
+### Bestätigung und Wiederholungen (Retries)
+Die maximale Anzahl an Sendeversuchen (Retries) ist konfigurierbar (Standard: 4). Jedes Posten-Paket muss zwingend bestätigt werden. Die Bestätigung verwendet das exakt gleiche Format (`vppMLzzzzRR`), wobei jedoch **Bit 4 im Byte 3 (`M`) auf `1` gesetzt** ist. Das Antwort-Routing nutzt anhand des im Paket aufgezeichneten Pfades dieselbe Strecke in umgekehrter Richtung (Source Routing). Duplikate werden empfängerseitig anhand des eindeutigen Läufer-Zeitstempels erkannt und verworfen.