From 8e5d820c9d685c3e0fd0910f70b0b971085b4d97 Mon Sep 17 00:00:00 2001 From: Syafa Hadyan Rasendriya Date: Wed, 11 Nov 2026 18:09:10 +0700 Subject: [PATCH 1/3] docs(flashing): use the esptool 5 spelling and add power, cable and BOOT checks --- docs/hub-flashing.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/hub-flashing.md b/docs/hub-flashing.md index 645f11e..478533e 100644 --- a/docs/hub-flashing.md +++ b/docs/hub-flashing.md @@ -1,6 +1,6 @@ # Flashing the hub from a CI build -The Firmware workflow builds the hub on every run and keeps the four files that the chip needs for 14 days, as the artifact `hub-flash` of that run. This page says how to put those files on a hub board without installing PlatformIO. It needs Python with `esptool` 4.6 or newer, and the GitHub CLI with a login (`gh auth login`) to download the files. +The Firmware workflow builds the hub on every run and keeps the four files that the chip needs for 14 days, as the artifact `hub-flash` of that run. This page says how to put those files on a hub board without installing PlatformIO. It needs Python with `esptool` 5 or newer, and the GitHub CLI with a login (`gh auth login`) to download the files. The commands use the hyphen spelling of `esptool` 5, for example `write-flash`. Version 4 spells them with underscores, for example `write_flash`. Use only the artifact of a run on `main`, or of a pull request that you have read. The artifact is a program that runs on your board, and a run from an unreviewed branch can hold anything. @@ -27,20 +27,20 @@ The offsets follow `gateway/partitions.csv`. The table has the NVS at `0x9000` w 2. Optional but advised when the board runs other firmware. Save the whole flash first, which takes a few minutes. Pick a new folder name for each board and after each failed try, for example `hub-backup-1`, and use the same name in both commands below. The command stops when the folder exists, and that keeps one backup from replacing another. The backup holds the NVS of the board and any crash dump, so it can hold a Wi-Fi password and keys, and it must stay private. Write it into a folder that only you can open, and treat the file like a password. ```sh - mkdir -m 700 && python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 read_flash 0 ALL /hub-backup.bin + mkdir -m 700 && python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 read-flash 0 ALL /hub-backup.bin ``` Step 3 changes folder, so go back to the folder that holds the backup folder to put the backup back. ```sh - python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash 0 /hub-backup.bin + python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash 0 /hub-backup.bin ``` 3. Write the four files. ```sh cd hub-flash - python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write_flash --flash_mode dio --flash_freq 40m --flash_size detect \ + python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash --flash-mode dio --flash-freq 40m --flash-size detect \ 0x1000 bootloader.bin 0x8000 partitions.bin 0xe000 boot_app0.bin 0x10000 firmware.bin ``` @@ -55,11 +55,14 @@ The offsets follow `gateway/partitions.csv`. The table has the NVS at `0x9000` w - On Linux the port belongs to a group, often `dialout` or `uucp`. A permission error means that your user is not in it. - The port can be `ttyACM0` or a COM name instead of `ttyUSB0`. - Some boards have no automatic reset. When `esptool` stays at `Connecting....`, hold the BOOT button until the write starts. This also reaches a board that restarts in a loop, because `esptool` talks to the loader in the chip and not to the firmware. -- `esptool` can erase the whole flash with `erase_flash`. That gives a clean state, and it deletes the saved settings and every pairing. +- The BOOT hold works only when GPIO 0 goes low. To check it, open the monitor with both control lines off, hold BOOT and wait for the chip to restart. A chip in download mode prints `boot:0x3` and `waiting for download`. A line with `boot:0x13` while BOOT is held means that GPIO 0 did not go low. Then check the button and its solder joints, or use another board. +- A boot log that restarts every few seconds with `rst:0x1 (POWERON_RESET)` can point to a weak supply, because the Wi-Fi start draws a current spike. Use a short cable that carries data and a port on the PC itself and not a hub. A powered hub can also help. +- A kernel log (`journalctl -k` on Linux) with `error -71`, or a port that vanishes and returns while you work, points to a bad cable or port. Change the cable first. +- `esptool` can erase the whole flash with `erase-flash`. That gives a clean state, and it deletes the saved settings and every pairing. ## What the write changes - It replaces the bootloader, the partition table, the OTA data and the app. It does not erase the rest of the chip. The NVS partition of this build starts at `0x9000` and ends at `0xe000`, where the write of `boot_app0.bin` begins. Saved settings of an earlier build survive only when its NVS partition was not larger than that. An earlier partition that reached past `0xe000` loses its last pages, and the settings in them may be lost. The hub then shows that no Wi-Fi is saved, and the setup portal enters it again. -- Other data in the second half of the flash, for example the file system of another firmware, is not erased by this command. Three later events can destroy it, and each one reaches a different part. An over the air update overwrites the second app slot, from `0x200000` up to `0x3F0000`. A crash dump erases whole sectors of 4 KB from the start of the core dump area at `0x3F0000`, as many as the dump needs, and writes the dump there. The sectors after them keep their data. A full erase with `erase_flash` removes everything, including the core dump area. Copy files off the board first. +- Other data in the second half of the flash, for example the file system of another firmware, is not erased by this command. Three later events can destroy it, and each one reaches a different part. An over the air update overwrites the second app slot, from `0x200000` up to `0x3F0000`. A crash dump erases whole sectors of 4 KB from the start of the core dump area at `0x3F0000`, as many as the dump needs, and writes the dump there. The sectors after them keep their data. A full erase with `erase-flash` removes everything, including the core dump area. Copy files off the board first. - A crash dump is plain flash and holds the stacks of the tasks, so it can hold key material for a moment. Parts of an old dump can stay in the flash until the area is erased on purpose. - The first boot line starts with `WATTLINK hub` and the version, and it shows that the new build runs. The lines after it report the saved nodes, the saved settings and the crypto self test. A line about the Wi-Fi follows only when a network is saved, so a new board prints none. None of them shows a password or a key. The settings line does show the name of the saved Wi-Fi network, so look at the log before you paste it in a public place. From e8440da8c0d4df5413f9cc481ca645acaa87f3eb Mon Sep 17 00:00:00 2001 From: Syafa Hadyan Rasendriya Date: Wed, 11 Nov 2026 18:10:47 +0700 Subject: [PATCH 2/3] docs(flashing): reset before the BOOT check, soften the power and cable causes --- docs/hub-flashing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/hub-flashing.md b/docs/hub-flashing.md index 478533e..eed215d 100644 --- a/docs/hub-flashing.md +++ b/docs/hub-flashing.md @@ -1,6 +1,6 @@ # Flashing the hub from a CI build -The Firmware workflow builds the hub on every run and keeps the four files that the chip needs for 14 days, as the artifact `hub-flash` of that run. This page says how to put those files on a hub board without installing PlatformIO. It needs Python with `esptool` 5 or newer, and the GitHub CLI with a login (`gh auth login`) to download the files. The commands use the hyphen spelling of `esptool` 5, for example `write-flash`. Version 4 spells them with underscores, for example `write_flash`. +The Firmware workflow builds the hub on every run and keeps the four files that the chip needs for 14 days, as the artifact `hub-flash` of that run. This page says how to put those files on a hub board without installing PlatformIO. It needs Python with `esptool` 5 or newer, and the GitHub CLI with a login (`gh auth login`) to download the files. The commands use the hyphen spelling of `esptool` 5, for example `write-flash`. Older versions use underscores, for example `write_flash`, so a version 4 install needs that spelling. Use only the artifact of a run on `main`, or of a pull request that you have read. The artifact is a program that runs on your board, and a run from an unreviewed branch can hold anything. @@ -55,9 +55,9 @@ The offsets follow `gateway/partitions.csv`. The table has the NVS at `0x9000` w - On Linux the port belongs to a group, often `dialout` or `uucp`. A permission error means that your user is not in it. - The port can be `ttyACM0` or a COM name instead of `ttyUSB0`. - Some boards have no automatic reset. When `esptool` stays at `Connecting....`, hold the BOOT button until the write starts. This also reaches a board that restarts in a loop, because `esptool` talks to the loader in the chip and not to the firmware. -- The BOOT hold works only when GPIO 0 goes low. To check it, open the monitor with both control lines off, hold BOOT and wait for the chip to restart. A chip in download mode prints `boot:0x3` and `waiting for download`. A line with `boot:0x13` while BOOT is held means that GPIO 0 did not go low. Then check the button and its solder joints, or use another board. -- A boot log that restarts every few seconds with `rst:0x1 (POWERON_RESET)` can point to a weak supply, because the Wi-Fi start draws a current spike. Use a short cable that carries data and a port on the PC itself and not a hub. A powered hub can also help. -- A kernel log (`journalctl -k` on Linux) with `error -71`, or a port that vanishes and returns while you work, points to a bad cable or port. Change the cable first. +- The BOOT hold works only when GPIO 0 goes low. The chip reads GPIO 0 only at a reset. To check it, open the monitor as in step 4 with both control lines off. Hold BOOT, press EN once and read the first lines. A chip in download mode prints `boot:0x3` and `waiting for download`. A line with `boot:0x13` while BOOT is held means that GPIO 0 did not go low. Then check the button and its solder joints, or use another board. +- A boot log that restarts every few seconds with `rst:0x1 (POWERON_RESET)` or `rst:0xf (BROWNOUT_RST)` can come from a weak supply or a faulty EN line. The Wi-Fi start is a likely trigger, because it draws a current spike. Use a short cable that carries data. Plug it into a port on the PC itself and not into a hub. A powered hub may help. +- A kernel log (`journalctl -k` on Linux) with `error -71`, or a port that vanishes and returns while you work, often points to a bad cable or port. Change the cable first. - `esptool` can erase the whole flash with `erase-flash`. That gives a clean state, and it deletes the saved settings and every pairing. ## What the write changes From 1411447451d64182326a88e4fbce7b37f88556dd Mon Sep 17 00:00:00 2001 From: Syafa Hadyan Rasendriya Date: Wed, 11 Nov 2026 18:15:52 +0700 Subject: [PATCH 3/3] docs(flashing): name download mode by its message and not by one boot value --- docs/hub-flashing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/hub-flashing.md b/docs/hub-flashing.md index eed215d..cd13883 100644 --- a/docs/hub-flashing.md +++ b/docs/hub-flashing.md @@ -55,7 +55,7 @@ The offsets follow `gateway/partitions.csv`. The table has the NVS at `0x9000` w - On Linux the port belongs to a group, often `dialout` or `uucp`. A permission error means that your user is not in it. - The port can be `ttyACM0` or a COM name instead of `ttyUSB0`. - Some boards have no automatic reset. When `esptool` stays at `Connecting....`, hold the BOOT button until the write starts. This also reaches a board that restarts in a loop, because `esptool` talks to the loader in the chip and not to the firmware. -- The BOOT hold works only when GPIO 0 goes low. The chip reads GPIO 0 only at a reset. To check it, open the monitor as in step 4 with both control lines off. Hold BOOT, press EN once and read the first lines. A chip in download mode prints `boot:0x3` and `waiting for download`. A line with `boot:0x13` while BOOT is held means that GPIO 0 did not go low. Then check the button and its solder joints, or use another board. +- The BOOT hold works only when GPIO 0 goes low. The chip reads GPIO 0 only at a reset. To check it, open the monitor as in step 4 with both control lines off. Hold BOOT, press EN once and read the first lines. A chip in download mode prints a `boot:` line with `DOWNLOAD_BOOT`, usually `boot:0x3`, and then `waiting for download`. Other strapping pins can change the value. A line with `SPI_FAST_FLASH_BOOT`, usually `boot:0x13`, while BOOT is held means that GPIO 0 did not go low. Then check the button and its solder joints, or use another board. - A boot log that restarts every few seconds with `rst:0x1 (POWERON_RESET)` or `rst:0xf (BROWNOUT_RST)` can come from a weak supply or a faulty EN line. The Wi-Fi start is a likely trigger, because it draws a current spike. Use a short cable that carries data. Plug it into a port on the PC itself and not into a hub. A powered hub may help. - A kernel log (`journalctl -k` on Linux) with `error -71`, or a port that vanishes and returns while you work, often points to a bad cable or port. Change the cable first. - `esptool` can erase the whole flash with `erase-flash`. That gives a clean state, and it deletes the saved settings and every pairing.