Flash from any subnet — the bootloader IP is now configurable (v3.7.0)

[jnilo1]

You asked, it's in. A couple of you ran into the same wall:

"re-flashing is hard because of the hardcoded bootloader IP-Address… Would it be > possible to make the bootloader IP configurable?" — @flowjob1 (#97)

"Could we imagine in bootloader to save the IP address instead of getting the default one 192.168.1.6 at reboot? Kind of SAVEENV or SAVE command…" — @jlayec (#111)

As of v3.7.0 (bootloader V2.7), the download-mode / TFTP server IP is no longer hard-wired to 192.168.1.6 and you don't have to recompile anything.

How it works

When the flash scripts send the gateway into bootloader mode, they hand the desired IP to the bootloader through a small reserved DRAM page (the same mechanism boothold already uses for the reboot-to-bootloader flag). The bootloader reads it on the next reset and brings up download mode on that address.

• It only applies on a deliberate warm reboot from Linux (the automated flash path), so cold-boot recovery still falls back to the compiled 192.168.1.6.
• Nothing is written to flash, and there's no new partition — exactly the "separate area, not overwritten on bootloader update" property that was asked for, achieved without touching flash at all.
• The serial IPCONFIG command still works at the prompt for the cold-boot case.

Using it

Just pass --boot-ip to the flash scripts (or set the BOOT_IP env var):

# gateway and PC both on a 192.168.0.x LAN, no serial console needed
./flash_install_rtl8196e.sh --boot-ip 192.168.0.6 192.168.0.88
./flash_remote.sh --boot-ip 192.168.0.6 kernel 192.168.0.88

The flag is available from v3.7.0; the in-bootloader handoff needs V2.7, which v3.7.0 installs.
Thanks @flowjob1 and @jlayec for the clear write-ups.

[MaxRower]

Is the new bootloader installed with ./flash_install_rtl8196e.sh?
How can I get the current version (without serial access)?
Would it be possible to add DCHP to the bootloader? Then it would get the same IP as normally. But ./flash_install_rtl8196e.sh could get the current IP as well? It would be nice to use a hostname with --boot-ip. This would do the job nicely, like ./flash_install_rtl8196e.sh --boot-ip otbr otbr

[MaxRower]

Just tried to flash via VPN, but got the message "Error: 192.168.23.206 is reached via a gateway (routed). The bootloader's
TFTP server only answers on the same L2 segment.". If I added an SNAT rule to my firewall, it would probably work, but the script would still abort?

After flashing it local with --boot-ip, the following happened:

Uploading fullflash.bin via TFTP (16 MiB)...
Upload OK.
Bootloader does not answer ICMP (Tuya / pre-v2) — manual flash required.

The image is in the gateway's RAM at 0x80500000. On the serial console
(38400 8N1, line wrap ON), type:

    FLW 0 80500000 01000000

Answer (Y)es when prompted, then wait ~2 min until the <RealTek> prompt returns.

Has the flash completed (FLW back at the <RealTek> prompt)? [y/N] n

Flash not confirmed — nothing was changed if you did not run FLW.
The image is still in RAM at 0x80500000: run the FLW above and reboot
manually, or re-run this script to upload again.

$ ssh root@otbr
Lidl Zigbee Gateway v3.8.1 - J. Nilo - 2026-06-09
~ # 

So the flashing did actually succeed.

[jnilo1]

Thanks @MaxRower — and good news: your flash actually succeeded. What you hit was a reporting bug in the script, not a flashing failure. Details below, plus answers to your questions. Most of this is fixed in v3.8.2, which I just released.

Your flash did complete — the "manual flash required" message was a false negative

The auto-flash is triggered by the TFTP upload itself: once the 16 MiB image lands in the bootloader's RAM, a custom (V2.x) bootloader writes it to flash and reboots on its own. The script only observes this over the network to tell you what happened — it doesn't drive it.

To classify the bootloader, the script pinged it once before the upload. On v3.8.1 that was a single ICMP probe, and a single dropped/raced ping made it guess "Tuya / pre-v2 → manual flash required" — even though your V2.7 bootloader went on to auto-flash and reboot normally. That's why you answered n, saw "nothing was changed", and then found v3.8.1 running anyway. The "nothing was changed" line was simply wrong in that situation.

Fixed in v3.8.2:

• the probe now polls for ~10 s instead of pinging once, so a single flaked ping no longer misclassifies an auto-flash bootloader;
• the image is now built before the gateway is sent into the bootloader, so nothing masks the bootloader's brief settle window;
• and if the script ever does fall back to the manual path, it now tells you to ping/ssh the gateway first (wait ~2 min for the reboot) before re-flashing, instead of claiming nothing happened.

Q: Is the new bootloader installed by flash_install_rtl8196e.sh?

Yes. flash_install_rtl8196e.sh writes the full 16 MiB image, and the bootloader (boot.bin) sits at offset 0 of that image — so a full install updates the bootloader too. (The per-partition scripts flash_kernel.sh / flash_rootfs.sh / flash_userdata.sh do not touch the bootloader; only the full install and flash_bootloader.sh do.)

Q: How do I read the current version without serial access?

• Firmware version — it's the line you already saw on login (Lidl Zigbee Gateway v3.8.1 …), or cat /etc/version over SSH.
• Bootloader version — it isn't separately exposed to Linux (its banner is printed only on the serial console at boot, and the stage-2 image is compressed in flash, so strings on the MTD won't reliably show it). In practice the bootloader tracks the firmware: v3.7.0+ ships bootloader V2.7, which is the one with the configurable --boot-ip handoff. So if your firmware is ≥ v3.7.0, you're on V2.7.

Q: DHCP in the bootloader, and a hostname for --boot-ip?

• DHCP — I'd rather not. A DHCP client is a lot of code/size to carry in a minimal bootloader. The --boot-ip DRAM handoff was the deliberate lightweight alternative: it already lets the bootloader come up on your subnet without recompiling or using serial, which covers the "same IP as normal" need without a DHCP stack.
• Hostname — now supported in v3.8.2. --boot-ip (and the BOOT_IP env var) accept a hostname; it's resolved host-side to an IPv4 before use (the on-device handoff needs a literal IPv4). So your exact example works now:

  ./flash_install_rtl8196e.sh --boot-ip otbr otbr

  (--boot-ip otbr is resolved by the script; the positional otbr is resolved by SSH.)

On flashing over VPN / a routed segment

That guard is doing the right thing, and SNAT alone wouldn't be enough. Beyond TFTP, the script detects the bootloader via ARP (it ARPs the target on the local segment to find it and confirm it's in download mode). ARP can't cross a router — through a gateway you'd resolve the router's MAC, not the device's — so the detection step would fail even if you NAT'd the TFTP through. That's why it aborts early rather than stranding the gateway mid-flow.

The practical answer is the --boot-ip feature itself: connect on the same L2 (a direct cable or a local switch on the gateway's segment) and pass --boot-ip <your-subnet-IP>. I'd avoid routed/VPN flashing entirely — a flash that fails partway leaves the gateway sitting in the bootloader, reachable only through that fragile NAT path.

---

Upgrade note: v3.8.2 is a host-side tooling release — the on-device firmware (kernel + bootloader) is byte-identical to v3.8.1, so there's nothing you must re-flash for it; just pull the updated scripts. Thanks again for the clear write-up, it made this easy to pin down.

[MaxRower]

• Hostname — now supported in v3.8.2. --boot-ip (and the BOOT_IP env var) accept a hostname; it's resolved host-side to an IPv4 before use (the on-device handoff needs a literal IPv4). So your exact example works now:

Thanks, upgraded to 3.9.0, this works fine.

Fixed in v3.8.2:

* the probe now **polls for ~10 s** instead of pinging once, so a single flaked ping no longer misclassifies an auto-flash bootloader;

But no change here.

Uploading fullflash.bin via TFTP (16 MiB)...
Upload OK.
Bootloader does not answer ICMP (Tuya / pre-v2) — manual flash required.

NOTE: a custom (V2.x) bootloader may auto-flash the uploaded image on its
own even when this script could not detect it. If the gateway reboots and
comes back on SSH within ~2 min (ssh root@otbr), the
flash already succeeded — you are done and can ignore the steps below.
The steps below are only for stock/older bootloaders that need a manual FLW.

The image is in the gateway's RAM at 0x80500000. On the serial console
(38400 8N1, line wrap ON), type:

    FLW 0 80500000 01000000

Answer (Y)es when prompted, then wait ~2 min until the <RealTek> prompt returns.

Has the flash completed (FLW back at the <RealTek> prompt)? [y/N] n

Manual FLW not confirmed. Before doing anything else, check whether the
gateway auto-flashed on its own (custom V2.x bootloaders often do, even
when this script could not detect it):

    ping otbr      # wait up to ~2 min for the reboot
    ssh root@otbr

If it answers, the flash already succeeded — you are done.
If it stays unreachable, nothing was written: the image is still in RAM
at 0x80500000 — run the FLW above and reboot manually (J BFC00000), or
re-run this script to upload again.

$ ssh root@otbr
Lidl Zigbee Gateway v3.9.0 - J. Nilo - 2026-06-10
~ # ot-ctl state
child
Done

[MaxRower]

Tried to flash the gateway on the other location the same way, I got a TFTP timeout twice and had to reboot it via a smart plug. Flashing without --boot-ip did succeed, but the script did not detect auto-flash as well.

Sending boothold + reboot...
Boot hold set (TFTP server IP 192.168.23.206).
Waiting for shutdown...
Waiting for bootloader at 192.168.23.206...
Bootloader detected at 192.168.23.206.

Uploading fullflash.bin via TFTP (16 MiB)...
Error: TFTP transfer failed: Transfer timed out.

ending boothold + reboot...
Boot hold set (TFTP server IP 192.168.1.6).
Waiting for shutdown...
Waiting for bootloader at 192.168.1.6...
Bootloader detected at 192.168.1.6.

Uploading fullflash.bin via TFTP (16 MiB)...
Upload OK.
Auto-flash detected (bootloader is writing flash). Waiting for confirmation...
No auto-flash confirmation. Falling back to manual flash.

NOTE: a custom (V2.x) bootloader may auto-flash the uploaded image on its
own even when this script could not detect it. If the gateway reboots and
comes back on SSH within ~2 min (ssh root@otbr), the
flash already succeeded — you are done and can ignore the steps below.
The steps below are only for stock/older bootloaders that need a manual FLW.

The image is in the gateway's RAM at 0x80500000. On the serial console
(38400 8N1, line wrap ON), type:

    FLW 0 80500000 01000000

Answer (Y)es when prompted, then wait ~2 min until the <RealTek> prompt returns.

Has the flash completed (FLW back at the <RealTek> prompt)? [y/N] n

[jnilo1]

Hi @MaxRower,

Thanks for the two reports — they exposed a deeper bug than the one v3.8.2 fixed, and both of your symptoms turned out to be the same root cause. Fixed in v3.10.0, released today — the fix is host-side only, so a plain git pull gives you the corrected script; details below.

Root cause: the script trusted ARP to mean "bootloader is up"

After boothold + reboot, the script waited for the bootloader by ARP-probing BOOT_IP. The problem: when Linux shuts down, it keeps answering ARP for a few seconds after SSH dies. So "Bootloader detected" could fire while the box was still rebooting — and everything downstream inherited the lie:

• The ICMP classification (the v3.8.2 10-second poll) ran inside the dead window between Linux going down and the bootloader coming up. All 10 pings fell into the gap, so the script concluded "does not answer ICMP → Tuya / pre-v2 → manual flash required". Meanwhile the TFTP client kept retransmitting its request until the bootloader actually came up, the upload landed, and the auto-flash ran fine — exactly what you saw. The v3.8.2 fix lengthened the poll but did not fix the race, because the whole poll could still run before the bootloader existed.
• At your second location, the same false "Bootloader detected" sent a 16 MiB upload at an address where (probably — see question below) no bootloader was listening, so it sat in the 5-minute TFTP timeout. Twice.

On top of that, the post-flash confirmation listened only for the bootloader's UDP:9999 notification. That packet is unsolicited inbound UDP — the first thing any host firewall drops — and the fallback message then claimed "No auto-flash confirmation" for a flash that had succeeded.

What changed in v3.10.0

1. "Bootloader detected" now means it — the wait loop requires the bootloader's TFTP server to actually ACK a 1-byte write probe, not just an ARP reply. A dying Linux or a proxy-ARP router can't fake that. This kills both the false "Tuya / pre-v2" classification and the upload-into-nothing timeout.
2. No ICMP classification at all on the automated path. If the script got there via boothold, the bootloader is a custom V2.x by construction — classifying it "Tuya" from a missed ping was logically impossible to begin with. The Tuya/pre-v2 detection remains only on the serial/first-flash path, where it belongs.
3. The flash confirmation now has two independent channels: the UDP:9999 notification (instant, when your network lets it through), and the behavioural proof — after writing, the bootloader reboots the box into the new firmware, so SSH coming back up at the gateway's address can only mean the flash succeeded. Nothing answers there during the write, and the script only polls an address it knows for certain (your --boot-ip otbr otbr case qualifies). A firewall can no longer turn a successful flash into a scary message.
4. Honest failure messages: if the bootloader never shows up, or TFTP fails, the script now says explicitly that nothing was written and that a power cycle returns the gateway to its current firmware — which is what your smart plug did.

A question about the second gateway

The TFTP timeouts at your other location fit one specific profile: a bootloader older than V2.7. Pre-V2.7 bootloaders ignore the --boot-ip handoff and always come up at the default 192.168.1.6 — the script (misled by the ARP race) uploaded to 192.168.23.x where nothing was listening, while the bootloader sat waiting at 192.168.1.6. That would also explain why the run without --boot-ip worked on that box.

The bootloader only updates on a full install (flash_install_rtl8196e.sh / fullflash.bin) or an explicit flash_bootloader.sh — per-partition kernel/rootfs/userdata flashes never touch it. Do you remember whether that second gateway ever had a full install from v3.7.0 or later before this attempt? If it only ever got partition updates, it was still on its old bootloader, and --boot-ip will start working there now that this attempt's full install brought it to V2.7. The new error message calls this trap out explicitly.

Verified on the bench

Two full installs against a bench gateway:

• a normal run — the new TFTP-verified detection found the bootloader, the upload auto-flashed, and the UDP confirmation reported the write;
• a run with UDP:9999 deliberately made unreceivable on the host (simulating your firewall) — the script confirmed the flash through the SSH channel instead: Gateway is back up on SSH — flash write succeeded. No manual-flash fallback, no false negative.

Beyond the script fix, v3.10.0 also carries kernel + userdata changes (see the release notes) — your boxes can pick those up with the usual ./flash_install_rtl8196e.sh --boot-ip otbr otbr, which is now a much less chatty experience. Thanks again — between this and the v3.8.2 report you have personally debugged most of this script's networking assumptions.