Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/hub-flashing.md
Original file line number Diff line number Diff line change
@@ -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`. 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.

Expand All @@ -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 <backup folder> && python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 read_flash 0 ALL <backup folder>/hub-backup.bin
mkdir -m 700 <backup folder> && python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 read-flash 0 ALL <backup folder>/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 <backup folder>/hub-backup.bin
python -m esptool --chip esp32 --port /dev/ttyUSB0 --baud 460800 write-flash 0 <backup folder>/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
```

Expand All @@ -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. 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.

## 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.
Loading