MeshCore FUOTA Entwurf zur PrüfungDraft for review

So kommt ein Update von Repeater zu Repeater

Einer in deiner Gegend installiert das neueste signierte Release-Paket per USB oder BLE-OTA und wird Seed. Seine direkten Nachbarn holen den Patch, prüfen jede Seite und geben sie weiter. Ab Werk wendet dein Repeater das Update nach 7 Tagen an im Code geprüft, auf Befehl auch sofort.

How an update gets from repeater to repeater

Someone in your area installs the latest signed release package by USB or BLE OTA and becomes the seed. Its direct neighbours pull the patch, check every page and pass it on. By default your repeater applies the update after 7 days checked in the code, or at once on command.

Das Prinzip

  1. Seed werden. Einer in deiner Gegend installiert das neueste signierte Release-Paket von GitHub.
    • Das geht per USB oder per BLE-OTA vom Rechner, vom Handy ungetestet.
    • Sein Repeater ist damit der Seed, der erste Knoten mit dem neuen Release.
    • Er bietet das Update seinen direkten Nachbarn an.
  2. Nur den Unterschied holen. Wer das Update braucht, holt den Patch: nur den Unterschied zu seiner Version.
    • Über Funk geht nur dieser Delta-Patch (bsdiff + heatshrink).
    • Der Release-Schlüssel (Ed25519) signiert das Manifest: die Liste aller Teile des Updates mit ihren Prüfsummen. Ohne gültige Signatur passiert nichts.
    • Der Knoten fragt einen Nachbarn an, der das Update angeboten hat. Nur dieser antwortet.
  3. Prüfen, weitergeben, anwenden. Jeder Repeater prüft jede 4-KB-Seite gegen das Manifest.
    • Erst dann gibt er sie weiter, schon während er den Rest holt (Pipelining). Falsche Daten kommen nie weiter als einen Hop (Funksprung).
    • Dein Repeater wendet im A/B-Verfahren an. Slot A hält das laufende Image, Slot B das neue. Der Loader Stage-0 tauscht die Slots beim Start.
    • Startet die neue Firmware nicht, läuft nach 3 Probestarts ohne Bestätigung wieder die alte gemessen.

Was in jedem Schritt gilt

  • FUOTA steht für Firmware Update Over the Air. Seine Pakete gehen an direkte Nachbarn, in einem eigenen Pakettyp (0x0E).
  • Kein Knoten leitet ein solches Paket ohne Pfad weiter, auch kein normaler Repeater (ohne FUOTA). MeshCore verwirft unbekannte Typen.
  • Nur hinter normalen Repeatern (ohne FUOTA) laufen Anfrage und Daten auf einem festen Pfad. Ein Anbieter flutet dort sein Angebot als Gruppen-Nachricht. Hat er die ganze Kampagne, flutet er in der ersten Woche höchstens einmal am Tag. Dasselbe gilt eine Woche lang nach jeder Anfrage, die er hört. Sonst flutet er höchstens einmal je Woche im Code geprüft. Auch ein Retract geht einmal als Flut raus. Mehr dazu: Wer was weitergibt (früher Abschnitt 6).
  • Update-Daten fluten nie.
  • Jeder Knoten sendet Update-Pakete nur im harten Airtime-Budget (Sendezeit). Ab Werk sind das 0,3 % im Code geprüft.
  • Ein Update darf darum Tage dauern, und der normale Verkehr merkt davon wenig. Mit dem Release-Takt (0,3 %) brauchte ein Knoten 12,6 h für 174 Fragmente gemessen. Das war ein einzelner Lauf am Testaufbau. Im Nachweislauf vom 9. November 2026 war das RAK4631 nach 9 h 21 min fertig. Der FakeTec brauchte 9 h 35 min gemessen.

The principle

  1. Become the seed. Someone in your area installs the latest signed release package from GitHub.
    • That works by USB or by BLE OTA from a computer, untested from a phone.
    • Their repeater is then the seed, the first node with the new release.
    • It offers the update to its direct neighbours.
  2. Pull only the difference. A node that needs the update pulls the patch: only the difference from its version.
    • Only this delta patch (bsdiff + heatshrink) travels over radio.
    • The release key (Ed25519) signs the manifest. It lists every part of the update with its checksum. Without a valid signature nothing happens.
    • The node asks one neighbour that has offered the update. Only that neighbour answers.
  3. Check, pass on, apply. Every repeater checks each 4 KB page against the manifest.
    • Only then does it pass the page on, even while pulling the rest (pipelining). Wrong data never travels further than one hop (one radio link).
    • Applying uses the A/B method. Slot A holds the running image, slot B the new one. The loader Stage-0 swaps the slots at boot.
    • If the new firmware does not start, the old one runs again after 3 test boots without confirmation measured.

What holds in every step

  • FUOTA stands for Firmware Update Over the Air. Its packets go to direct neighbours, in a packet type of their own (0x0E).
  • No node forwards such a packet without a path. That includes a normal repeater (without FUOTA). MeshCore drops unknown types.
  • Only behind normal repeaters (without FUOTA) do request and data travel along a fixed path. A provider floods its offer there as a group message. With the whole campaign, it floods at most once a day in the first week. The same holds for a week after each request it hears. Otherwise it floods at most once a week checked in the code. A retract also goes out once as a flood. More: Who passes on what (formerly section 6).
  • Update data never floods.
  • Every node sends update packets only within a hard airtime budget (time on air). By default that is 0.3 % checked in the code.
  • An update may therefore take days, and normal traffic notices little of it. At the release pace (0.3 %), a node needed 12.6 h for 174 fragments measured. That was a single run on the bench. In the proof run of 9 November 2026, the RAK4631 took 9 h 21 min. The FakeTec took 9 h 35 min measured.
Der Seed in der Mitte bekommt das Release per USB. Seine Nachbarn holen es Seite für Seite (der Ring), danach deren Nachbarn. Orange ist die alte Firmware, Türkis die neue.
The seed in the middle gets the release by USB. Its neighbours pull it page by page (the ring), then their neighbours. Orange is the old firmware, teal the new one.

Ablauf eines Updates

Die gemessenen Zeiten stammen vom Testaufbau (SF7, 10 % Budget). Im Mesh gelten SF8 und 0,3 % Budget (Standard). Diese Zeiten stehen unter Last im Mesh. Die Alpha-Prüfung lief mit den Funkwerten des HanseMesh (SF8, 62,5 kHz, 1 dBm) gemessen. Das Budget war das Release-Budget von 0,3 % gemessen.

How an update runs

The measured times come from the bench (SF7, 10 % budget). In the mesh, SF8 and a 0.3 % budget apply (default). Those times are under Load on the mesh. The alpha check ran with the HanseMesh radio settings (SF8, 62.5 kHz, 1 dBm) measured. The budget was the release budget of 0.3 % measured.

Release-Build, offline signiertPatch und Manifest bauen Je Modell und Quell-Version entsteht ein Patch. Das Manifest hat 292 B plus 8 B je 4-KB-Seite, mit Angebots-Ticket im Code geprüft. Es nennt Ziel-Gerät, Build-Nummer, Größen und die SHA-256 von Quell-Image, neuem Image und Patch. Je Seite trägt es die ersten 8 Byte ihrer SHA-256. Dazu kommt ein Flag für das überlappende Anwenden. Dabei überschreibt das neue Image Patch-Seiten, die der Knoten schon gelesen hat. Der Release-Build spielt den Apply-Code des Geräts vorher auf dem Rechner durch. Das Flag setzt er nur, wenn das sicher ist. Am Ende steht das Angebots-Ticket: Ziel, Build, Patch-Größe, Quelle und Hash des Manifests. Jedes Angebot trägt es. Der Release-Schlüssel signiert Manifest und Ticket offline, getrennt vom Build. Die Build-Umgebung hat den privaten Schlüssel nie.
Irgendein Betreiber, per USB oder BLENeuestes Release-Paket installieren Das signierte Release-Paket enthält das neue Image und die Kampagne von der Vorversion. Sie besteht aus Manifest und Patch. Wer es per UF2, seriellem DFU oder BLE installiert, wird Seed. Beim Start prüft die Firmware die Kampagne wie eine geholte und bietet sie an. Alle anderen holen sie per Funk gemessen. Im Paket liegt die Kampagne am Anfang von Slot B. Der UF2-Bootloader schreibt nicht bis ans Ende von Slot B. Darum verschiebt die Firmware sie beim Start dorthin. Mehrere Seeds schaden nicht: Die Kampagne zählt über ihre ID. Am Testaufbau lädt ein USB-Befehl Manifest und Patch auch einzeln.
Jeder Knoten mit geprüftem ManifestAnbieten Das Angebot trägt das signierte Ticket (ID, Größe, Ziel, Build, Quell-Präfix). Dazu nennt es die Zahl geprüfter Seiten. Das Intervall verdoppelt sich von 10 s bis auf 2 Tage im Code geprüft. Der Knoten sendet in der zweiten Hälfte des Intervalls. Hört ein Knoten vorher ein gleiches Angebot, schweigt er (Trickle). Das gilt nur in Intervallen unter 1 h im Code geprüft. Danach bietet jeder Knoten einmal je Intervall an. So bekommt auch ein Nachbar ein Angebot, der die anderen nicht hört.
NachbarAngebot prüfen Er nimmt ein Angebot nur an, wenn Ziel-Gerät und Quell-Präfix passen. Außerdem muss die Build-Nummer höher sein. Das Quell-Präfix sind die ersten 8 Byte der SHA-256 des laufenden Images. Passt ein Angebot nicht, bleibt der Knoten still. Sonst prüft er die Signatur des Tickets. Ein gefälschtes Angebot verwirft er hier. Während eines Probestarts zieht er nicht. Du merkst: Ist das Netz schon aktuell, fließen keine Daten.
NachbarManifest holen Das Manifest kommt in 2 bis 4 Fragmenten. Der Knoten prüft die Signatur (Ed25519 über die CryptoCell), Ziel, Quelle, Build und Platz. Dazu prüft er, ob dieses Update hier schon gescheitert ist. Fällt eine Prüfung durch, holt er kein einziges Patch-Fragment. Nur was signiert ist und hier nie passen kann, sperrt der Knoten über Neustarts. Sonst ruht die Kampagne 10 min im Code geprüft.
NachbarPatch holen Die Anfrage nennt den niedrigsten Block mit Lücken. Der Block hat 16 Fragmente im Code geprüft, eine Bitmap nennt die fehlenden. Sie geht an genau einen Nachbarn, den zuletzt gehörten, dessen Angebot den Block abdeckt. Nur er antwortet. Kommt nichts, nennt die nächste Anfrage einen anderen Anbieter. Kennt der Knoten keinen weiteren, fragt er alle (Kennung 0xFFFF). Ein MeshCore-Schlüssel beginnt nie mit 0xFF. Fragmente landen direkt im Flash.
NachbarJede Seite sofort prüfen Ist eine 4-KB-Seite vollständig, prüft der Knoten sie gegen ihren Hash aus dem Manifest. Falsch: Er löscht die Seite und holt sie neu. Richtig: Er darf sie ab sofort weitergeben.
Derselbe KnotenWeitergeben, während er noch holt Er bietet an, sobald sein Manifest geprüft ist, mit der Zahl geprüfter Seiten. Fragt ein Nachbar nach einer Seite, die er noch nicht hat, merkt er sich das. Sobald die Seite fertig ist, bietet er sofort an.
Derselbe KnotenVollständig: wann er anwendet Ab Werk wendet er an, wenn die Kampagne 7 Tage komplett war im Code geprüft. Dieser Standard heißt fuota auto delay. Die Laufzeit zählt über Neustarts. Ein Retract (signierter Rückruf) in diesen 7 Tagen stoppt das Anwenden. Nach fuota auto off wartet er auf dein fuota apply <build>. Mit fuota auto now wendet er sofort an. Das gilt, wenn der Patch hinter das neue Image passt. Sonst wartet er ein Fenster ab, in dem er weitergibt. Es endet frühestens nach einer Mindestzeit. Dann muss eine Weile niemand nach dem Patch gefragt haben. Zudem darf nichts mehr auszuliefern sein. Die Werte für das Feld sind ein Vorschlag offen. Am Testaufbau sind es 120 s und 180 s im Code geprüft. Du merkst: fuota info zeigt Build, Auto-Apply und den Stand des Updates.
Derselbe KnotenNeues Image in Slot B bauen Der Knoten prüft die SHA-256 über den ganzen Patch. Dann baut er das neue Image in Slot B (10,2 s beim Release-Image gemessen). Er prüft die SHA-256 des Ergebnisses gegen das Manifest. Danach schreibt er den Tausch-Auftrag in die Status-Seite und startet neu.
Stage-0Prüfen, tauschen, Probestart Vor dem Tausch prüft Stage-0 Slot B (neu) und Slot A (alt) gegen den Auftrag. Dabei prüft es Vektortabelle und SHA-256. Dann tauscht es seitenweise, jeder Schritt steht im Journal (30 bis 39 s gemessen). Danach prüft es Slot A erneut gegen den Soll-Hash. Der Probestart läuft mit Watchdog (30 s im Code geprüft). Lehnt Stage-0 einen Auftrag ab, etwa wegen eines unbekannten Auftragsformats, startet die alte Firmware. Das Image ist dann gesperrt gemessen, außer wenn Slot B nicht mehr zum erwarteten Hash passte im Code geprüft.
Neue FirmwareBestätigen oder zurück 60 s gesunde Hauptschleife und ein Funk-Lebenszeichen (ein Paket empfangen, eines gesendet) bestätigen die neue Firmware im Code geprüft. Nach 3 Probestarts ohne Bestätigung tauscht Stage-0 zurück (Rückfall) gemessen. Gesperrt wird nur dieses eine Image, und erst nach dem Rückfall. Dafür muss mindestens ein Probestart mit einem Fehler-Neustart enden. Der Watchdog zählt gemessen. Ebenso zählen Reset-Taste, Software-Reset (auch per Befehl), Lockup, Debugger und NFC-Wecken im Code geprüft. Ein Probestart ohne erfasstes Ende zählt auch so im Code geprüft. Der Knoten merkt sich die letzten 4 gescheiterten Images. Solange ein Image dazugehört, installiert er es nicht wieder und bietet es nicht an. Fehlte nur das Lebenszeichen oder fiel nur der Strom aus, bleibt das Image erlaubt. Ein Spannungseinbruch zählt als Stromausfall. Der Knoten versucht es später neu. Erst der 3. Stromausfall-Rückfall sperrt es im Code geprüft. Du merkst: Ein gesperrtes Image blockiert spätere Releases nicht. Ein Release mit einem Patch von seinem Stand installiert der Knoten normal. Hat er ein Release verpasst, passt kein Patch mehr zu seinem Stand (Nachzügler) offen.
Derselbe KnotenWeiter anbieten Lag der Patch hinter dem neuen Image, liegt er nach dem Tausch noch da. Der Knoten prüft ihn beim Start erneut und bietet weiter an. Nach einem überlappenden Anwenden ist der Patch weg. Der Knoten bietet ihn nicht mehr an.
Release-Schlüssel, jederzeitZurückziehen Ein Retract (80 B im Code geprüft) gilt für ein Ziel und einen Build. Jeder Knoten, der ihn prüft, stoppt Holen und Anbieten und speichert ihn. Er sendet ihn bis zu 3-mal im Code geprüft. Außerdem flutet er ihn einmal. Vorher wartet er 2 bis 30 min im Code geprüft. Auf ein Angebot dieses Builds antwortet er mit dem Retract, höchstens alle 30 s im Code geprüft. Kam das Angebot als Flut, antwortet er mit einer Flut: nach einer Wartezeit von bis zu 30 min, höchstens einmal am Tag je Retract im Code geprüft.
Release build, signed offlineBuild patch and manifest One patch per model and source version. The manifest takes 292 B plus 8 B per 4 KB page checked in the code. That includes the offer ticket. It names target device, build number and sizes. It also holds the SHA-256 of source image, new image and patch. For each page it carries the first 8 bytes of its SHA-256. A flag covers overlapping apply. The new image then overwrites patch pages that the node has already read. Beforehand the release build plays the apply code of the device through on a computer. It sets the flag only if that is safe. The offer ticket comes last: target, build, patch size, source and hash of the manifest. Every offer carries it. The release key signs manifest and ticket offline, separate from the build. The build environment never holds the private key.
Any operator, over USB or BLEInstall the latest release package The signed release package holds the new image and the campaign from the previous version. The campaign is a manifest plus a patch. Whoever installs it over UF2, serial DFU or BLE becomes the seed. At boot the firmware checks the campaign like a pulled one and offers it. All others pull it over the air measured. In the package the campaign sits at the start of slot B. The UF2 bootloader does not write up to the end of slot B. So the firmware moves the campaign to the end at boot. Several seeds do no harm: the campaign counts by its ID. On the bench, a USB command also loads manifest and patch separately.
Every node with a checked manifestOffer The offer carries the signed ticket (ID, size, target, build, source prefix). It also names the number of checked pages. The interval doubles from 10 s up to 2 days checked in the code. The node sends in the second half of the interval. If a node hears an equal offer before that, it stays silent (Trickle). That holds only in intervals below 1 h checked in the code. After that every node offers once per interval. So even a neighbour that cannot hear the others gets an offer.
NeighbourCheck the offer It accepts an offer only if target device and source prefix match. The build number must also be higher. The source prefix is the first 8 bytes of the SHA-256 of the running image. If an offer does not fit, the node stays silent. Otherwise it checks the signature of the ticket. It drops a forged offer here. During a test boot it does not pull. You notice: if the mesh is already up to date, no data flows.
NeighbourPull the manifest The manifest comes in 2 to 4 fragments. The node checks the signature (Ed25519 via the CryptoCell), target, source, build and space. It also checks whether this update has already failed here. If a check fails, it pulls no patch fragment at all. Only what is signed and can never fit here is banned across reboots. Otherwise the campaign rests for 10 min checked in the code.
NeighbourPull the patch The request names the lowest block with missing fragments. The block has 16 fragments checked in the code. A bitmap names the missing ones. It goes to exactly one neighbour, the most recent one whose offer covers the block. Only that one answers. If nothing comes, the next request names another provider. If the node knows no other one, it asks everybody (ID 0xFFFF). A MeshCore key never starts with 0xFF. Fragments go straight to flash.
NeighbourCheck every page at once When a 4 KB page is complete, the node checks its hash against the manifest. Wrong: it erases the page and pulls it again. Right: it may pass the page on from now on.
Same nodePass on while still pulling It offers as soon as its manifest is checked, with the number of checked pages. If a neighbour asks for a page it does not have yet, it remembers that. As soon as the page is complete, it offers at once.
Same nodeComplete: when it applies By default it applies 7 days after the campaign is complete checked in the code. This default is fuota auto delay. The running time counts across reboots. A retract (signed recall) within those 7 days stops the apply. After fuota auto off it waits for your fuota apply <build>. With fuota auto now it applies at once. That holds if the patch fits behind the new image. Otherwise it waits out a window in which it passes the patch on. The window ends no sooner than a minimum time. Then nobody may have asked for the patch for a while. And nothing may be left to deliver. The values for the field are a proposal open. On the bench they are 120 s and 180 s checked in the code. You notice: fuota info shows build, auto apply and the state of the update.
Same nodeBuild the new image in slot B The node checks the SHA-256 over the whole patch. Then it builds the new image in slot B (10.2 s on the release image measured). It checks the SHA-256 of the result against the manifest. After that it writes the swap job into the status page and reboots.
Stage-0Check, swap, test boot Before the swap, Stage-0 checks slot B (new) and slot A (old) against the job. It checks the vector table and the SHA-256. Then it swaps page by page and journals every step (30 to 39 s measured). Afterwards it checks slot A again against the target hash. The test boot runs with a watchdog (30 s checked in the code). If Stage-0 refuses a job, for example an unknown job format, the old firmware starts. The image is then blocked measured, unless slot B no longer matched the expected hash checked in the code.
New firmwareConfirm or revert 60 s of a healthy main loop and a radio sign of life (one packet received, one sent) confirm the new firmware checked in the code. After 3 test boots without confirmation Stage-0 swaps back (revert) measured. Only this one image is blocked, and only after the revert. At least one test boot must end in a fault restart. The watchdog counts measured. So do the reset button, a software reset (also by command), lockup, debugger and NFC wake-up checked in the code. A test boot with no recorded end counts the same checked in the code. The node remembers the last 4 failed images. While an image is among them, it neither installs it again nor offers it. If only the sign of life or only the power failed, the image stays allowed. A voltage dip counts as a power failure. The node tries the image again later. Only the 3rd power-loss revert blocks it checked in the code. You notice: A blocked image does not block later releases. The node installs a release with a patch from its current version as usual. If it missed a release, no patch fits its version any more (straggler) open.
Same nodeKeep offering If the patch sat behind the new image, it is still there after the swap. The node checks it again at boot and keeps offering. After an overlapping apply the patch is gone. The node no longer offers it.
Release key, any timeRetract A retract (80 B checked in the code) applies to one target and one build. Every node that verifies it stops pulling and offering, and stores it. It sends it up to 3 times checked in the code. It also floods it once. It waits 2 to 30 min first checked in the code. It answers an offer of this build with the retract, at most every 30 s checked in the code. If the offer came as a flood, it answers with a flood: after a wait of up to 30 min, at most once a day per retract checked in the code.

Wer beteiligt ist

Who is involved

RolleWas sie tutWas sie nicht kann
Release-Build (fester Linux-Container)Baut die Images und je Repeater-Modell und Quell-Version einen Patch samt Manifest.Signieren. Den privaten Schlüssel gibt es dort nie, auch nicht in einer CI.
Release-Schlüssel (offline)Signiert Manifeste und Retracts, getrennt vom Build. So zieht er auch einen Build zurück (Retract).Nichts schränkt ihn ein: Wer den Schlüssel hat, bestimmt, was installiert werden darf.
Seed (irgendein Teilnehmer)Installiert das neueste Release-Paket per USB oder BLE-OTA und bietet die enthaltene Kampagne an.Eigene Kampagnen erzeugen. Unsigniertes lehnt der Knoten schon beim Laden ab.
Repeater mit FUOTALäuft mit normaler MeshCore-Repeater-Firmware und dem FUOTA-Modul. Er hört Angebote, holt, prüft, gibt weiter und wendet an.Sein Budget überschreiten, Ungeprüftes weitergeben, fremde Knoten updaten.
Stage-0 (Loader im Flash, 3.032 B gemessen)Läuft nur beim Start. Führt einen Tausch-Auftrag aus, mit Journal, Probestart und Rückfall.Funken und Signaturen prüfen. Es vertraut dem Auftrag der App (siehe Was noch offen ist).
Normaler Repeater (ohne FUOTA), Companions (Knoten, die eine App steuert)Sie verwerfen Typ 0x0E ohne Pfad. Das ist in MeshCore 1.18.0 Absicht (src/Mesh.cpp:326-329), der Typ wird nicht geroutet im Code geprüft. Ein Paket mit Pfad leiten sie weiter wie jedes Direct-Paket (src/Mesh.cpp:78-106). Ein geflutetes Angebot oder einen gefluteten Retract behandeln sie wie jede Gruppen-Nachricht. So tragen sie Anfragen und Daten über Lücken (siehe Wer was weitergibt).Ein Update prüfen, halten oder selbst anbieten.
Betreiber (du)

Du entscheidest, ob du mitmachst. Ab Werk gibt dein Knoten ein fertiges Update 7 Tage weiter, bevor er es anwendet. Kommt in diesen 7 Tagen ein Retract, wendet er es nicht an. Du kannst sofort anwenden lassen, nur auf Befehl anwenden oder selbst starten. Das geht auch per LoRa über die Fern-Befehlszeile (CLI, siehe Befehle). Das läuft am Testaufbau, auch über LoRa gemessen.

Mit set repeat off schaltest du den Knoten als Repeater ab. Dann bietet er auch mit FUOTA nichts an, gibt keine Daten weiter und flutet nichts. Retracts und Schlüssel-Widerrufe sendet er nur an direkte Nachbarn im Code geprüft.

Andere Knoten beeinflussen.
RoleWhat it doesWhat it cannot do
Release build (fixed Linux container)Builds the images and, per repeater model and source version, a patch with its manifest.Sign. The private key is never there, not even in a CI.
Release key (offline)Signs manifests and retracts, separate from the build. This is also how it retracts a build.Nothing limits it: whoever holds the key decides what may be installed.
Seed (any participant)Installs the latest release package by USB or BLE OTA and offers its campaign.Create its own campaigns. The node rejects unsigned material already at load time.
Repeater with FUOTARuns normal MeshCore repeater firmware plus the FUOTA module. It hears offers, pulls, checks, passes on and applies.Exceed its budget, pass on unchecked data, update foreign nodes.
Stage-0 (loader in flash, 3,032 B measured)Runs only at boot. Executes a swap job, with journal, test boot and revert.Use radio or check signatures. It trusts the job from the app (see What is still open).
Normal repeater (without FUOTA), companions (nodes that an app controls)They drop type 0x0E without a path. MeshCore 1.18.0 does this deliberately (src/Mesh.cpp:326-329) checked in the code. They forward a packet with a path like any direct packet (src/Mesh.cpp:78-106). They treat a flooded offer or a flooded retract like any group message. This is how they carry requests and data across gaps (see Who passes on what).Check, hold or offer an update themselves.
Operator (you)

You decide whether to take part. By default your node passes on a complete update for 7 days before it applies. A retract in that time stops the update. You can have it apply at once, only on command, or start it yourself. That also works over LoRa via the remote command line (CLI, see commands). This runs on the bench, over LoRa as well measured.

set repeat off switches the node off as a repeater. Then, even with FUOTA, it offers nothing, passes on no data and floods nothing. It sends retracts and key revocations to direct neighbours only checked in the code.

Influence other nodes.

Befehle für Betreiber

Repeater werden meist über LoRa administriert. Darum gehen die wichtigsten Befehle auch über die Fern-CLI (Admin-Login). Alle anderen fuota-Befehle gibt es nur über USB.

Commands for operators

Repeaters are mostly administered over LoRa. The most important commands therefore work over the remote CLI (admin login) as well. All other fuota commands are USB only.

BefehlWirkungWeg
password <neu>Setzt das Admin-Passwort. Ein Release-Image hat keins, du setzt es beim ersten Mal per USB im Code geprüft. Ein leeres Passwort lehnt der Knoten ab, ebenso das Passwort password im Code geprüft.USB, danach auch LoRa
fuota infoZeigt Build, Auto-Apply und den Stand des Updates.USB und LoRa
fuota auto now|delay|offLegt fest, wann ein fertiges Update angewendet wird. now: sofort. delay: nach 7 Tagen, ab Werk. off: nur auf Befehl. Der Repeater speichert die Einstellung. on gilt weiter als now.USB und LoRa
fuota apply <build>Startet das fertige Update mit dieser Build-Nummer nach 5 s im Code geprüft. Die Nummer nennt fuota info. Über LoRa ist sie Pflicht.USB und LoRa
fuota cmdtimeZeigt und setzt den Zeitstempel des letzten ändernden Fern-Befehls. Über LoRa nimmt er keinen Wert. Er setzt den Zähler dann auf den Zeitstempel dieses Befehls, auch zurück im Code geprüft.USB, ohne Wert auch LoRa
fuota relay on|offMit off gibt der Knoten Nachbarn nichts mehr: kein Angebot, keine Flut des Angebots, keine Daten. Er holt weiter für sich selbst. Retracts, Schlüssel-Widerrufe und Antworten auf Angebote zurückgezogener Builds flutet er weiter. Der Repeater speichert die Einstellung im Code geprüft.USB und LoRa
set repeat offMeshCore-Befehl: schaltet den Knoten als Repeater ab. FUOTA bietet dann nichts an, gibt keine Daten weiter und flutet nichts. Retracts, Schlüssel-Widerrufe und Antworten auf Angebote zurückgezogener Builds gehen nur an direkte Nachbarn, ohne Flut im Code geprüft.USB und LoRa
fuota retractZeigt die Retracts, die der Knoten kennt, und 3 Zähler für Fluten: gesendete, gehörte und eigene, die eine gehörte ersetzt hat. Mit einem signierten Retract als Hex-Text übernimmt der Knoten ihn und flutet ihn nach 1 bis 5 s. Mit set repeat off sendet er ihn nur an direkte Nachbarn im Code geprüft.nur USB
alle anderen fuota-BefehleÜber LoRa lehnt der Repeater sie ab.nur USB
CommandEffectRoute
password <new>Sets the admin password. A release image has none; you set it the first time over USB checked in the code. The node refuses an empty password, and the password password too checked in the code.USB, then also LoRa
fuota infoShows build, auto apply and the state of the update.USB and LoRa
fuota auto now|delay|offSets when a complete update applies. now: at once. delay: after 7 days, the default. off: only on command. The repeater saves the setting. on still means now.USB and LoRa
fuota apply <build>Starts the complete update with that build number after 5 s checked in the code. Find the number with fuota info. Over LoRa it is required.USB and LoRa
fuota cmdtimeShows and sets the timestamp of the last remote command that changed something. Over LoRa it takes no value. It then sets the counter to the timestamp of this command, also lower checked in the code.USB, without a value also LoRa
fuota relay on|offWith off the node gives its neighbours nothing. It sends no offer, no flood of the offer and no data. It still pulls for itself. It keeps flooding retracts, key revocations and answers to offers of retracted builds. The repeater saves the setting checked in the code.USB and LoRa
set repeat offMeshCore command: switches the node off as a repeater. FUOTA then offers nothing, passes on no data and floods nothing. Retracts, key revocations and answers to offers of retracted builds go only to direct neighbours, without a flood checked in the code.USB and LoRa
fuota retractShows the retracts the node knows and 3 counters for floods: sent, heard, and own ones that a heard one replaced. Given a signed retract as hex text, the node takes it over and floods it after 1 to 5 s. With set repeat off it sends it only to direct neighbours checked in the code.USB only
all other fuota commandsOver LoRa the repeater refuses them.USB only

Schutz gegen Wiederholung

Ein mitgeschnittener alter Befehl gilt nach einem Neustart nicht wieder. Der Repeater hält den Zeitstempel eines Admins nur im RAM (Stock, also MeshCore unverändert). Darum speichert FUOTA den Zeitstempel des letzten ändernden Fern-Befehls. Das gilt für auto, apply, reboot, clkreboot, poweroff, shutdown und start ota. Gleiche und ältere Zeitstempel lehnt es ab.

Am Testaufbau gemessen

Protection against replay

A recorded old command does not count again after a reboot. A repeater keeps an admin's timestamp only in RAM (stock, that is MeshCore unchanged). So FUOTA saves the timestamp of the last remote command that changes something. That covers auto, apply, reboot, clkreboot, poweroff, shutdown and start ota. It refuses equal and older ones.

Measured on the bench

TestErgebnis
fuota apply mit falscher oder fehlender Nummer, Wiederholung vor und nach einem Neustartabgelehnt gemessen
fuota apply mit der richtigen Nummerläuft bis zur Bestätigung gemessen
Warten mit auto offübersteht einen Neustart gemessen
fuota apply startet ein Update99 bis 116 s bis zur Bestätigung, überlappend 122 und 128 s (Läufe vom 19. und 20. Oktober 2026) gemessen
auto off im laufenden Fenster, danach auto onDas Fenster bricht ab gemessen. Mit auto on wendet der Knoten nach 291 bis 295 s von selbst an gemessen. Beide Schritte sind einzeln gemessen (19. und 20. Oktober 2026), nicht als eine Kette in einem Lauf.
Funkeinstellungen und Schlüssel über 5 Image-Wechselunverändert gemessen
auto delay über Neustarts, Retract in den 7 Tagen (Test-Build mit 120 s)Die 7 Tage zählen weiter. Ein Retract stoppt das Anwenden, auch einer, der per Funk von einem Nachbarn kam gemessen
Über LoRa, Ende zu Ende: Ein Companion loggt sich als Admin ein (direkt, ohne Hop)fuota info und fuota auto kommen über Funk zurück. Ebenso die Ablehnung eines USB-Befehls gemessen
fuota apply über LoRaDer Repeater antwortet vor dem Neustart und bestätigt den neuen Build nach 113 s gemessen
fuota auto on über LoRaMeldet „applies after its window“ und wendet nach 275 s an gemessen
TestResult
fuota apply with a wrong or missing number, replay before and after a rebootrefused measured
fuota apply with the right numberruns through to confirmation measured
Waiting with auto offsurvives a reboot measured
fuota apply starts an update99 to 116 s until confirmed, overlapping 122 and 128 s (runs of 19 and 20 October 2026) measured
auto off in a running window, then auto onThe window is cancelled measured. With auto on the node then applies on its own after 291 to 295 s measured. Both steps were measured separately (19 and 20 October 2026), not as one chain in a single run.
Radio settings and keys across 5 image changesunchanged measured
auto delay across reboots, retract within the 7 days (test build with 120 s)The 7 days keep counting. A retract stops the apply, also one received over the radio from a neighbour measured
Over LoRa, end to end: a companion logs in as admin (direct, no hop)fuota info and fuota auto come back over the radio. So does the refusal of a USB command measured
fuota apply over LoRaThe repeater answers before the reboot and confirms the new build after 113 s measured
fuota auto on over LoRaReports “applies after its window” and applies after 275 s measured

Kennt der Repeater den Pfad zum Companion noch nicht, antwortet er per Flut. Eine Region ist der Flood-Scope, in dem eine Nachricht läuft. Ohne Default-Scope geht die Antwort ohne Region hinaus (Stock-Verhalten) gemessen. Mit Default-Scope geht sie in dessen Region im Code geprüft. Setze am Testaufbau darum vorher den Default-Scope.

Without a known path to the companion, the repeater answers with a flood. A region is the flood scope a message travels on. Without a default scope the answer goes out without a region (stock behaviour) measured. With a default scope it goes out in that region checked in the code. On the bench, set the default scope first.

Release-Struktur: zwei Linien

Ein Release besteht aus zwei Linien. Die Linie 1.17.1 liefert das Basispaket, die Linie 1.18.0 das Update darauf.

  1. Basispaket 1.17.1 (Build 1). Das erste Image bekommt ein Knoten per USB. Das Paket ist eine UF2-Datei für das USB-Laufwerk des Bootloaders, eine Datei je Board und SoftDevice. Es gibt sie für 18 Boards. Beispiele: FakeTec S140 6.1.1, SenseCAP P1 S140 7.3.0, RAK4631 S140 6.1.1. Es bringt Stage-0 mit, den Lader, den FUOTA nie schreibt (siehe Flash). Die Linie 1.17.1 hat keine Kampagne, sie ist die erste Auslieferung.
  2. Update auf 1.18.0. Spätere Updates kommen per Funk. Ein Knoten mit dem Basispaket 1.17.1 holt eine signierte Kampagne von 1.17.1 nach 1.18.0 über LoRa. Im Nachweislauf vom 9. November 2026 (Build 2) war die Patch-Datei 23.749 B groß, das Manifest 400 B. Das neue Image hatte 299.284 B, das alte 296.900 B gemessen.

Für 1.18.0 gibt es außerdem Seed-Pakete (UF2, per USB) für dieselben 18 Boards. Ein Seed trägt das Update und bietet es seinen Nachbarn an. Wie ein Knoten die Signatur prüft, steht unter Sicherheit.

Stand 16. November 2026: Am 11. November 2026 begann ein Alpha-Test mit 1.17.1-b2 und 1.18.0-b3. Eine allgemeine Freigabe gibt es nicht. Die Pakete dieses Tests sind zurückgezogen. Neue Pakete für einen zweiten Test folgen. Mehr dazu unter Alpha-Test.

Der Nachweislauf von 1.17.1 nach 1.18.0 ist am 9. November am Prüfbrett durchgelaufen: beide Empfänger, ein FakeTec und das RAK4631, holten die Kampagne per Funk und liefen danach auf 1.18.0 (Build 2) gemessen.

Release structure: two lines

A release has two lines. Line 1.17.1 delivers the base package, line 1.18.0 delivers the update on top of it.

  1. Base package 1.17.1 (build 1). A node gets its first image by USB. The package is a UF2 file for the USB drive of the bootloader. There is one file per board and SoftDevice, for 18 boards. Examples: FakeTec S140 6.1.1, SenseCAP P1 S140 7.3.0, RAK4631 S140 6.1.1. It brings Stage-0 along, the loader that FUOTA never writes (see Flash). Line 1.17.1 has no campaign, it is the first delivery.
  2. Update to 1.18.0. Later updates come over the air. A node with base package 1.17.1 pulls a signed campaign from 1.17.1 to 1.18.0 over LoRa. In the proof run of 9 November 2026 (build 2) the patch was 23,749 B. The manifest was 400 B. The new image had 299,284 B, the old one 296,900 B measured.

For 1.18.0 there are also seed packages (UF2, by USB) for the same 18 boards. A seed carries the update and offers it to its neighbours. How a node checks the signature is described under Safety.

Status as of 16 November 2026: An alpha test with 1.17.1-b2 and 1.18.0-b3 began on 11 November 2026. There is no general release. The packages of this test have been withdrawn. New packages for a second test will follow. More under Alpha test.

The proof run from 1.17.1 to 1.18.0 finished on the test bench on 9 November: both receivers, a FakeTec and the RAK4631, pulled the campaign over the air and then ran 1.18.0 (build 2) measured.

Der Release-Build

Der Release-Build nutzt die Stock-Vorgaben für Frequenz, Bandbreite und Spreizfaktor. Er sendet beim Start ein Advert, die Ankündigung eines Knotens im Mesh. Gespeicherte Einstellungen und Schlüssel lässt er unverändert, denn FUOTA schreibt nur seine eigene Datei. Ein normaler Repeater ist er trotzdem nicht.

Unterschiede zum Stock-Build des FakeTec

Der Release-Build weicht vom Stock-Build des FakeTec (PlatformIO-Env ProMicro_repeater) in diesen Punkten ab:

  • Kein BLE in der App: start ota startet den BLE-DFU des Bootloaders.
  • Keine Anzeige: NullDisplayDriver statt des Anzeige-Treibers.
  • Board und Pins kommen zur Laufzeit aus dem Deskriptor.
  • Gebaut mit -Os statt -Ofast.
  • Zusätzlich die Sensor-Treiber für SHTC3, SHT4x, LPS22HB, INA260 und BME680.
  • Ein Update-Angebot flutet er in seiner Standard-Region, der Region, in der er flutet. Wie oft, steht unter Sicherheit.

Das stammt aus Build-Konfiguration und Code im Code geprüft. Was bei anderen Boards gegenüber Stock fehlt, steht unter Was noch offen ist. Die Größen stehen unter Flash.

Test-Build und Release-Build

Nur der Test-Build hat die Schalter des Testaufbaus:

  • SF7 und 1 dBm beim Start erzwungen
  • kein Advert
  • 10 % Budget
  • Testbefehle

Eine Build-Sperre bricht den Release-Build ab, sobald einer davon hineingerät.

Release und Test haben verschiedene Ziel-IDs. Jedes Anwenden prüft die Ziel-ID des Manifests. Eine Kampagne für den Testaufbau passt darum nie auf einen Release-Knoten.

Auch die Schlüssel sind getrennt. Ein Release-Build kompiliert nur mit einem eigenen Release-Schlüssel. Den Test-Schlüssel nimmt er nie im Code geprüft. Der Release-Schlüssel wurde am 8. November 2026 erzeugt, und die Images beider Linien tragen seinen Schlüsselblock im Code geprüft. Die Größe von 299.284 B stammt aus dem ersten Bau mit dem Release-Schlüssel.

Der Nachweislauf vom 9. November 2026 lief mit dem Release-Schlüssel. Die Alpha-Prüfung vom 12. November 2026 lief mit Release-Images und Release-Signatur gemessen. Die übrigen Prüfungen unten sind älter und liefen mit dem Test-Schlüssel. Mehr dazu: Was noch offen ist.

Am Release-Build gemessen (Prüfungen vom 20. Oktober bis 12. November 2026)

  • 299.284 B, das sind 74 von 96 Seiten, mit signierten Angeboten. Am 8. November 2026 gemessen, beim ersten Bau des Release-Env gemessen
  • kein BLE-Symbol im Image gemessen
  • Am 12. November 2026 lehnte ein Release-Image ein Manifest mit Test-Schlüssel ab (ERR manifest signature), der Knoten blieb unverändert gemessen
  • Der Knoten hielt eine signierte Kampagne für Build 2 (dc048c3d) nur als Relais. Für sich lehnte er sie ab (not for this node) gemessen. Ob Build oder Basis-Hash der Grund war, ist nicht getrennt offen
  • Die Build-Sperre greift bei allen 22 geprüften Schaltern gemessen. Dazu gehören die 7 Tage von delay, delay als Vorgabe und die Grenzen der Flut-Angebote.

The release build

The release build uses the stock defaults for frequency, bandwidth and spreading factor. It sends an advert at boot, a node's announcement to the mesh. It leaves saved settings and keys unchanged, because FUOTA writes only its own file. It is still not a normal repeater.

Differences from the stock build of the FakeTec

The release build differs from the stock build of the FakeTec (PlatformIO env ProMicro_repeater) in these points:

  • No BLE in the app: start ota starts the BLE DFU of the bootloader.
  • No display: NullDisplayDriver instead of the display driver.
  • Board and pins come from the descriptor at run time.
  • Built with -Os instead of -Ofast.
  • Plus the sensor drivers for SHTC3, SHT4x, LPS22HB, INA260 and BME680.
  • It floods an update offer in its default region, the region in which it floods. How often is under Safety.

This comes from the build configuration and the code checked in the code. What other boards lack compared with stock is listed under What is still open. Sizes are under Flash.

Test build and release build

Only the test build has the bench switches:

  • SF7 and 1 dBm forced at boot
  • no advert
  • 10 % budget
  • test commands

A build guard stops the release build as soon as one of them gets in.

Release and test have different target IDs. Every apply checks the target ID of the manifest. So a campaign for the bench never fits a release node.

The keys are separate too. A release build compiles only with its own release key. It never uses the test key checked in the code. The release key was generated on 8 November 2026, and the images of both lines carry its key block checked in the code. The size of 299,284 B comes from the first build with the release key.

The proof run of 9 November 2026 used the release key. The alpha check of 12 November 2026 used release images and the release signature measured. The other checks below are older and used the test key. More: What is still open.

Measured on the release build (checks of 20 October to 12 November 2026)

  • 299,284 B, that is 74 of 96 pages, with signed offers. Measured on 8 November 2026 at the first build of the release env measured
  • no BLE symbol in the image measured
  • On 12 November 2026 a release image refused a test-key manifest (ERR manifest signature). The node stayed unchanged measured
  • The node held a signed campaign for build 2 (dc048c3d) only as a relay. It refused it for itself (not for this node) measured. Whether build or base hash was the reason is not separated open
  • The guard fires for all 22 switches tested measured. Among them: the 7 days of delay, delay as default, and the limits of flooded offers.

Weiter: Last im MeshNext: Load on the mesh →