Open the text reading version
Currency note. Figures originally quoted in Chinese yuan are shown as CNY with a USD conversion in parentheses. Conversion basis for October 2026: 1 USD ≈ 6.71 CNY.
Almost every gateway firmware upgrade guide ends with the same line: do not disconnect power during the upgrade.
It reads like advice. It is actually a disclaimer. It hands the only survival condition of the system over to the field environment: whether the mains supply is stable, whether the cleaner unplugs something, whether the UPS has expired, whether a colleague walking past decides the enclosure feels a little hot.
The trouble is that most gateways live inside riser cupboards, above suspended ceilings, and in corridor distribution boxes — places where nobody supervises them and nobody has committed to continuity of supply.
A/B dual partitioning was not invented to make upgrades convenient. It exists to delete that disclaimer from the system. This article covers how it works, and what it looks like concretely on an open-source ESP32-S3 gateway like the GD6.
1. First, separate two things: gateway OTA and end-device FUOTA are not the same problem
A LoRaWAN system contains two completely different kinds of "firmware update". They share the OTA acronym, but differ in transport, constraints, and consequences. Conflating them leads teams to pick the wrong tool.
| Gateway-side OTA | End-device FUOTA | |
|---|---|---|
| Target | The gateway itself (application on the ESP32-S3) | End LoRaWAN nodes (sensors, DTUs) |
| Transport | IP: Ethernet / Wi-Fi / 4G / USB | LoRaWAN downlink over the air |
| Firmware size | Megabytes | Kilobytes, sent in fragments |
| Main constraints | Flash slot capacity, rollback availability | Duty cycle occupancy, battery charge |
| Failure impact | Gateway offline; every device beneath it stops reporting | One node lost; localised impact |
| A/B required? | Strongly recommended, effectively mandatory | Depends on MCU resources |
A useful sense of scale: a single GD6 application slot is 2.75 MB. The maximum LoRaWAN frame is 255 bytes. The same volume pushed over the air in fragments would take tens of thousands of packets. That is why end-device practice leans on delta updates (official figures cite a reduction of roughly 90% in transferred data) and multi-bin fragment reassembly, while the gateway side never needs to save airtime — it only needs to answer one question: can we get back?
Everything below concerns the gateway side.
2. The lethal window in single-partition, in-place OTA
To see what A/B buys you, look at where the single-partition approach breaks.
In-place update sequence:
- Receive the new firmware stream
- Erase the current application partition
- Write the new firmware block by block
- Verify
- Reboot
The risk lives entirely between the start of step 2 and the end of step 3. During that interval the device holds neither a complete old firmware nor a complete new one. It is a bare machine with no operating system.
How long is that window? On an ESP32-S3, erasing a multi-megabyte flash region typically takes hundreds of milliseconds to a few seconds, and writing plus verification adds on top. In other words it is a window of several seconds that cannot be shortened: lose power inside it and the device does not degrade gracefully and does not retry. It sits there with no valid program until somebody drives out to it.
Worse, this risk has nothing to do with firmware quality. Even a perfectly tested image produces the same result if somebody pulls the plug during the erase-write window.
So the correction is not test harder. It is keep the old image executable at all times, physically, until a replacement exists. That is the starting point of dual partitioning.
3. A/B partitioning: shrinking a lethal window to a single flag
The structural change is small: reserve two application slots in flash, run from one at any moment, leave the other idle.
The upgrade sequence becomes:
- Receive the new image and write it into the slot that is not running
- Verify the integrity of the image now sitting in the idle slot
- Write "boot from this slot next time" into a small dedicated partition
- Reboot
The essential point: the running old image is never touched. Write fails? The old image is still there, the next boot still uses it, and the worst outcome is that the upgrade did not happen. Power lost midway? Old image still there, reboot returns to the previous version. New image has a bug and will not boot? As long as it has not been marked confirmed good, the bootloader falls back to the old slot on the next reset.
On the ESP32-S3 this mechanism consists of several pieces (standard capability provided by the ESP-IDF framework):
- Bootloader — reads the OTA data partition first at every boot, decides which slot to start from, and validates the image in the target slot.
- OTA data partition — holds the slot selection record. Small enough that a single atomic write updates it.
- Application slots — at least two, flagged as OTA-writable.
- Rollback confirmation — after booting, the application must actively call the confirmation API to cancel the rollback marker. If the new image never reaches that point (crash at startup, reset loop), the bootloader switches back to the old slot at the next reset.
That "application actively confirms" step is the soul of the whole design. It converts the question is this new image usable? from a human judgement call into a signal triggered by actual runtime behaviour: it booted, it stabilised, it reached the server — then confirm. Otherwise roll back automatically.
One caveat worth stating plainly: rollback is not free by default. Rollback behaviour depends on enabling the relevant application rollback and anti-rollback settings in the bootloader SDK configuration. If you are building your own firmware, check that option explicitly rather than assuming it is on.
4. Anatomy of the GD6 8 MB partition table
GD6 firmware and its web configuration system are open source (github.com/ManThink/gd6-open), built on the ESP-IDF framework with PlatformIO. The partitions.csv at the repository root lays out the full 8 MB flash. Line by line:
| Partition | Type / Subtype | Offset | Size | Purpose |
|---|---|---|---|---|
| nvs | data / nvs | 0x9000 | 24 KB | Non-volatile storage (including passwords) |
| otadata | data / ota | 0xF000 | 8 KB | OTA slot selection record |
| phy_init | data / phy | 0x11000 | 4 KB | RF PHY initialisation data |
| ota_0 | app | 0x20000 | 2.75 MB | Firmware slot A |
| ota_1 | app | 0x2E0000 | 2.75 MB | Firmware slot B |
| storage | data / spiffs | 0x5A0000 | 2.375 MB | Web UI and configuration files |
The table is full — six partitions totalling exactly 8 MB. Three points deserve separate attention.
First: what occupies 0x0 to 0x9000. That range does not appear in partitions.csv because it holds the bootloader and the partition table itself, burned in at fixed offsets by the build system rather than described as user partitions. This also explains the origin of the prohibition covered in the next section.
Second: 2.75 MB is per slot, not the total budget for both. Two slots of 2.75 MB means any single image cannot exceed 2.75 MB — otherwise it compiles fine and fails at OTA time. This is a wall people hit only after adding a large new component, such as an extra TLS stack or another backhaul protocol implementation. The repository documentation is explicit: if firmware exceeds 2.75 MB, the partition table must be reworked.
There is also a multiplier effect that is easy to overlook. The size of the .bin determines flash occupancy, and each slot must accommodate a complete worst-case copy. You cannot argue that the two slots share a common data region — they are physically separate areas.
Third: the storage partition is outside A/B protection. The web UI and its configuration files live in SPIFFS and travel through a different update path (pio run --target uploadfs). OTA covers application slots only.
The practical consequence is that upgrade risk splits into two halves, and they are asymmetric:
- Application slots are safe, with A/B fallback behind them.
- If you corrupt web UI files by overwriting them online, the repository README warns explicitly that the console may become unreachable and that a factory reset does not restore those files. The only reliable recovery at that point is re-flashing SPIFFS over serial.
So use the file-system page to edit web files online only when you have serial access as backup. That boundary is set by architecture; no operating procedure can compensate for it.
5. Three artefacts, two offsets, one prohibition
The GD6 multi-region build script, scripts/build_regions.py, produces several artefacts, all named with version and region:
| Artefact | Contents | Flash offset | Safe for web OTA? |
|---|---|---|---|
GD6-<ver>-<REGION>-full.bin |
Complete 8 MiB flash image | 0x0 | No |
GD6-<ver>-<REGION>-firmware.bin |
Application image | 0x20000 | Yes |
GD6-<ver>-<REGION>-spiffs.bin |
SPIFFS image | 0x5A0000 | No — separate filesystem flashing |
Then there is the prohibition that appears repeatedly across the documentation.
The GD6 manual says it directly: do not upload a complete flash manufacturing image as a web OTA firmware. The gwTool6 configuration guide puts it even more plainly in its firmware upgrade section: do not use a whole-chip flash image as web OTA firmware, and record your network, LoRaWAN, and radio parameters before upgrading.
Why?
Because full.bin is a complete image laid out starting at 0x0, beginning with the bootloader and partition table. The web OTA channel writes to the idle application slot, at 0x20000 or 0x2E0000.
Handing full.bin to the OTA channel asks the system to take a dataset that expects to be executed from 0x0 and drop it verbatim into an application slot. The head of the slot is not a valid application image. Verification fails, and execution was never on the table.
Here A/B partitioning saves you a second time. Because the write targets the idle slot, even a wrong file leaves the running image intact: the gateway most likely stays alive, the console stays reachable, and you get another chance to upload the correct file. Under a single-partition scheme the same action is an instant brick.
This is perhaps the clearest illustration available: A/B partitioning protects against power loss, and against people.
Two offsets worth memorising for recovery work: applications start at 0x20000, SPIFFS starts at 0x5A0000.
Full-chip rewrite and recovery, as two commands:
python -m esptool --chip esp32s3 erase_flash python -m esptool --chip esp32s3 write_flash 0x0 GD6-1.0.2-EU868-full.bin
The first wipes everything including the Gateway EUI, so treat it as a last resort rather than routine. The documentation is blunt on this point: back up anything you want to keep.
6. Four flashing paths, and what each is for
GD6 exposes four routes for getting an image onto the device. They are not redundant options; each covers a different situation.
| Path | Prerequisites | Typical use | Covered by A/B? |
|---|---|---|---|
| PlatformIO upload | Build environment, USB connection | Development and debugging | No — overwrites the current slot |
| esptool full-chip flash | USB connection | First flashing, brick recovery | No — rewrites everything |
| Browser flasher | Chrome or Edge plus USB | Field upgrade with no toolchain installed | Depends on write target |
| Web console OTA | Network reachability | Online upgrade of deployed gateways | Yes |
The browser flasher under tools/flasher/ deserves a mention. Built on the ESP Web Serial API, it needs no toolchain on the engineer's laptop: open a page in Chrome or Edge, plug in the USB cable, flash. It also integrates feed control for the ESP32-S3 external watchdog (TPL5010) plus abort and abnormal-reset protection — both of which matter in the field, where the probability of yanking the cable halfway through is far higher than the probability of a mains dropout during the upgrade window.
Console-side OTA has matching REST endpoints: GET /api/firmware returns firmware information, and POST /api/firmware/upload performs the upload and OTA. In other words the operation is scriptable; nobody has to click through a page.
The documented operating discipline is consistent across models:
- Check current model, hardware version, region, and firmware version.
- Select only a firmware file that matches the device exactly.
- Wait for upload, verification, and write to complete — do not refresh the page, drop the network, or remove power.
- Reboot as prompted, log in again, and confirm the version and key settings.
One model-specific note: GDI51 and GDO51 gateways upgraded through the local web interface are documented to reboot twice during the procedure. Knowing that prevents the mistake of assuming the upgrade finished at the first reboot and pulling the cable.
7. A console that never disappears: six-stage boot as fallback
A/B partitioning handles the image will not run. There is a second failure mode: the image runs, but something it depends on is broken — SPIFFS fails to mount, or the SX1302 self-test does not pass.
A/B cannot help here, because both copies encounter the same problem. GD6 applies a second layer at boot. app_main() runs in six stages:
| Stage | Action |
|---|---|
| Phase 0 | NVS init plus event loop; status LED and factory-reset button armed as early as possible |
| Phase 1 | Mount SPIFFS — failure disables the web server and the packet forwarder |
| Phase 2 | Start the Wi-Fi soft AP (asynchronous, non-blocking) |
| Phase 3 | Route manager brings up Ethernet, then 4G PPP, with failover |
| Phase 4 | Start HTTPD (REST API plus static files) and the remote MQTT configuration channel |
| Phase 5 | SX1302 self-test, then start the packet forwarder or BasicStation as configured |
The repository documents the design principle plainly: later stages tolerate non-fatal failures in earlier ones, ensuring the device can always enter recovery mode through the Wi-Fi AP. Concretely, even if SPIFFS fails to mount or the SX1302 self-test fails, the web console remains reachable.
This is a pragmatic trade-off. It concedes a basic fact of the field: the cheapest way to save a gateway is not for the device to heal itself, it is to leave a human a way in. A reachable console means you can re-upload a correct image, read the logs, change configuration, and trigger a factory reset.
One related point that trips people up: the entry point differs by model. The GD62 IP67 outdoor unit has no external REC button. Official guidance is explicit that you must not give users instructions involving an external REC long-press of about two seconds, three rapid flashes, or anything similar, and must not suggest opening the enclosure to find an internal button. Factory reset for that model goes through technical support under the delivered maintenance procedure; afterwards the default web password is unchanged and the written-in Gateway EUI is retained.
In the GD6 open repository, src/factory_reset.c is the corresponding module, and configuration files are embedded in the firmware — a factory reset extracts defaults from the image and writes them back to SPIFFS. But a factory reset does not restore the web/ directory, as noted earlier. Worth repeating, because it is a hole you cannot climb out of unaided.
So the complete fallback chain has three layers:
- A/B partitioning covers an unusable image.
- Six-stage boot plus a persistent console covers dependency failures.
- USB or serial covers the case where both previous layers are lost.
Do not expect any single layer to carry the whole load.
8. Four fields that must line up: model, hardware version, region, firmware version
Most real upgrade incidents are not partition-design failures. They are wrong-file failures.
Four things must line up before upgrading, and this is stated identically in the GD6, gwTool6, and gwTool7 documentation:
- Model — GD6, GD61x, GD73, GDI51, and GDO51 each take their own package.
- Hardware version — even within one model, versions are not interchangeable.
- Region — CN470, EU868, US915, AS923, AU915, KR920, IN865.
- Firmware version — confirm the current-to-target upgrade path.
Region is the one most likely to go wrong, because it is a physical constraint rather than a software one.
GD6 application code is frequency-agnostic in itself; all regional difference lives in global_conf.json. That makes it tempting to believe software alone can change bands. But the RF front-end hardware must match the target band — 868, 915, and 470 modules are not interchangeable. Flash EU868 firmware onto a CN470 gateway and the software layer reports no error while the radio simply does not work.
The gwTool7 administrator guide carries a broader warning: four classes of upgrade package must not be mixed — TKG application packages, gwTool packages, gateway firmware packages, and TKE packages are different in kind, each servicing only its own target. It also requires that you do not upload files of unknown origin, files failing verification, or files whose model does not match, and that you stop retrying and preserve the logs when an upgrade fails.
Those last words matter. Retrying repeatedly with the same wrong package converts one diagnosable failure into one failure of unknown state.
9. Fleet upgrades: two roles in the platform
Manual flashing is fine for one gateway. For dozens or hundreds you need the platform.
ThinkLink splits this across two roles and two entry points:
| Role | Entry point | Action |
|---|---|---|
| Platform administrator | System platform → Software package management → Gateway upgrade package | Upload and maintain every gateway firmware package available to tenants |
| Tenant operator | Gateway list → select gateway → More → Gateway upgrade | Pick from the uploaded list and push to the chosen gateway |
The split has a purpose: the administrator vets package legitimacy, while tenants retain the right to choose which package to apply. A tenant cannot push a self-uploaded, unverified package to hundreds of devices.
One more distinction that is easy to muddle:
| System upgrade | Gateway upgrade package | |
|---|---|---|
| Upgrades | The ThinkLink instance itself (TKG / TKE) | Firmware of managed gateway devices |
| Uploaded by | Administrator, directly in the system platform | Administrator, uploaded into the system |
| Dispatched by | Administrator | Tenants, from their own gateway page |
The first upgrades the machine running ThinkLink (or the ThinkLink instance embedded in a gateway). The second upgrades the gateway's own firmware. Different paths, different objects, entirely different error messages.
For scripted operations, the gateway REST API supports pre-checks: call GET /api/status to read the current firmware version, decide whether an upgrade is needed, and only then call POST /api/firmware/upload. That turns a full fleet re-push into an incremental one, compressing an upgrade window of hundreds of simultaneous reboots down to a few dozen.
10. A worked example: what this design is actually worth
No external industry pricing here — just arithmetic with every parameter stated, so you can substitute your own numbers.
Assumptions (stated explicitly so they can be changed):
- Gateways to upgrade: 120, spread across four sites
- Under a single-partition scheme, one interruption inside the erase window per 100 upgrades (conservative for riser-cupboard deployments)
- One field recovery: three hours including travel and work on site
- Labour cost: CNY 800 per person-day at eight hours, i.e. CNY 100/hour (about USD 45/hour)
- Additional overhead (re-dispatching, arranging access, temporary replacement hardware): ignored, taken as zero
The arithmetic:
Single-partition scheme:
Expected bricks = 120 × 1% = 1.2 units Cost per recovery = 3 hours × CNY 100/hour = CNY 300 (about USD 45) Expected total recovery cost = 1.2 × CNY 300 = CNY 360 (about USD 54)
That looks cheap. But these are only the accounting costs. The real ledger reads:
Blast radius per offline gateway = every end device beneath it At 60 measurement points per gateway, one gateway offline for a working day = 60 points × one day of missing data
That loss is unrecoverable. LoRaWAN does not park historical uplinks in a retransmission queue while you repair the gateway. For customers running energy settlement, environmental monitoring, or compliance reporting, a one-day gap may require a written explanation.
The incremental cost of A/B is:
One extra application slot = 2.75 MB of flash
On an ESP32-S3 with 8 MB of flash, that investment has already been paid. Put differently: to keep 1.2 units out of 120 from becoming 1.2 truck rolls, the price is a region of flash that is already on the chip.
Raise the interruption probability from 1% to something closer to real riser-cupboard conditions — say 3% — and the accounting figure becomes 3.6 units and roughly CNY 1,080 plus three rounds of access coordination. Still not enormous. Which is exactly the point: A/B partitioning is not expensive; what is expensive is not knowing clearly why it is there. Many selection debates end up asking whether a line item is worth the budget, when this particular line item was baked into the bill of materials long ago.
What belongs in the decision table are the parts that cannot be compensated after the fact: the missing data, the inspection window you missed, the customer's impression that this equipment is a little unstable.
11. Staged rollout and rollback criteria
A/B protection does not authorise a single full-fleet push. Here is a workable batching plan.
Batching
| Batch | Size | Purpose | Observation period |
|---|---|---|---|
| Batch 0 | 1 unit — the closest one, with serial access | Validate the package itself | ≥ 30 minutes |
| Batch 1 | 10% of the fleet, ideally within one site | Validate the batch dispatch path | ≥ 4 hours, covering a full data cycle |
| Batch 2 | Remaining 50% | Validate scaling behaviour | ≥ 1 working day |
| Batch 3 | Everything else | Close out | 72 hours of continued observation |
Checks required after every batch
- Firmware version actually changed
- Active slot switched (A→B or B→A) rather than staying put
- Network settings, LoRaWAN server address, and radio parameters intact
- Gateway re-registered with ThinkLink and shown online in the list
- At least one device under that gateway completed a full uplink/downlink round trip
- No new repeating alerts in the logs
Item 2 matters more than it looks. If the version changed but the active slot did not flip, the update did not travel the path you assumed — perhaps another management channel flashed it — and that needs explaining before you continue.
Rollback triggers
Stop the next batch immediately on any of the following:
- Any gateway in the batch did not come back within the expected window
- Any gateway entered a reset loop
- Any gateway lost configuration items across the reboot
- Any unit required manual intervention to recover
Then use the A/B property: re-flash the previous version onto the failed unit and it returns to the old slot. This is the whole value of that first 30-minute observation window — the cheapest point to roll back is before you have touched the second unit.
12. Acceptance checklist
Print this and take it to site.
Before upgrading
- [ ] Record current model, hardware version, region, and firmware version
- [ ] Export and save network parameters, LoRaWAN server configuration, radio parameters
- [ ] Confirm all four fields match on the target firmware
- [ ] Confirm you selected the application image, not a full-chip image
- [ ] Confirm this gateway has a reachable serial recovery path
- [ ] Confirm power arrangements for the upgrade window
During the upgrade
- [ ] No page refresh, no network drop, no power loss
- [ ] Expect the device may reboot twice
- [ ] On failure, stop retrying and preserve logs
After the upgrade
- [ ] Version number changed
- [ ] Active slot switched
- [ ] Network, LoRaWAN, and ThinkLink connectivity restored
- [ ] Key configuration intact
- [ ] At least one complete uplink/downlink verified
- [ ] Hard-refresh the browser and log in again (avoid being misled by a cached front end)
Closing
Looked at end to end, A/B partitioning does one thing: it converts do not disconnect power during the upgrade from a promise somebody has to keep into a structural fact nobody needs to promise.
The cost lands in three places: one extra application slot (2.75 MB on the GD6), a small slot-selection data partition (8 KB), and a confirmation path that must be implemented correctly. Under 3 MB of flash in total — on an ESP32-S3 with 8 MB, money already spent before you asked the question.
The rest is not engineering, it is discipline: do not feed whole-chip images into an OTA channel, do not treat four-field verification as optional paperwork, do not declare success before the staged validation has finished.
What deserves to stick is those three layers. A/B covers the image. Six-stage boot covers console reachability. USB serial covers the last door. All three together, and an upgrade can run unattended in a riser cupboard nobody is watching.
Further reading
- Issue 24: Connecting ThinkLink to BACnet/IP and Modbus TCP: From Field Mapping to YABE Verification
- Issue 23: Deploying ThinkLink Edge On-Premises: Keeping Data Inside the Plant, From Hardware Selection to Bidirectional Migration
- Issue 21: ThinkLink Thing Model Decoding in Practice: Turning 15 Bytes Into a Readable Table
- GD6 Hardware Design: The ESP32-S3 Plus SX1302 Trade-offs
Official documentation and repository
- GD6 open-source repository: github.com/ManThink/gd6-open
- GD61x specifications and user guide: think-link.net/docs/en/Device/LoRaWANGateway/gd61x-user-guide
- gwTool6 configuration guide: think-link.net/docs/en/Device/LoRaWANGateway/gd6-configuration-guide
- gwTool7 gateway administrator guide: think-link.net/docs/en/Device/LoRaWANGateway/gwtool7-administrator-guide
- Gateway management: think-link.net/docs/en/Maintenance/GatewayManagement
- Gateway upgrade packages: think-link.net/docs/en/SystemPlatform/GatewayUpgradePackage
ManThink — making IoT development more efficient.
Buildings, HVAC & campuses · Global partners · Send an enquiry ↗
Explore more technical notes and field practices.
Back to articles ↗