Skip to content

A truly modular keyboard

C

firmware: README recommends BOOT0 to GND through 10k, BOOTLOCK optional

Nathan8cf5eff1a0f7
diff --git a/firmware/README.md b/firmware/README.md
index b896539..540516d 100644
--- a/firmware/README.md
+++ b/firmware/README.md
@@ -64,35 +64,38 @@ the app asked for an update.
### One-flash setup
> [!CAUTION]
-> **Over USB DFU, never use STM32CubeProgrammer's `-startfus`, `-fwupgrade`,
-> `-startwirelessstack`, "run after programming" (`-g`, `-s`, `-rst`) or any
-> `-ob`.** On this board `-startfus` over USB left `nSWBOOT0=0`, `nBOOT0=1`:
-> it boots from flash only, ignores BOOT0, and can't get back into DFU without
-> SWD. Plain writes (`-d ... -v`) and reads only. The keyword installs the BLE
-> stack itself and `BOOTLOCK` sets the boot option bytes from the app.
+> **In STM32CubeProgrammer over USB, never tick "Run after programming".** It
+> writes `nSWBOOT0=0`, `nBOOT0=1`, and that's what locked the first keyword
+> (with `-startfus`): it boots from flash only, ignores BOOT0, and can't get
+> back into DFU without SWD. The same goes for `-g`, `-s`, `-rst`,
+> `-startfus`, `-fwupgrade`, `-startwirelessstack` and any `-ob` over USB.
+> Plain writes (`-d ... -v`) and reads only. The keyword installs the BLE stack
+> itself.
One file has everything: the bootloader at 0x08000000, the app at 0x08007000
and the BLE stack at 0x080D0000. The gaps aren't in it, so it never writes the
keymap page or anything of FUS.
-1. **Get into DFU.** On a fresh chip, BOOT0 (PH3, U11 pin 5) high at reset
- starts ST's ROM DFU. PH3 and NRST (pin 8) aren't routed on the keyword, so
- hold a wire from pin 5 to 3V3 while plugging in USB. It shows up as
- `0483:df11`. A keyword that already runs this firmware gets there with
- `DFU` over USB serial instead.
+The way I recommend leaves the option bytes at the factory default
+(`nSWBOOT0=1`, BOOT0 read from the pin) and ties BOOT0 (PH3, U11 pin 5) to GND
+through about 10k. PH3 and NRST (pin 8) aren't routed on the keyword, so that's
+a resistor from pin 5 to the GND pad. Then the app boots on every reset and
+nothing ever writes the option bytes.
+
+1. **Get into DFU.** Bridge pin 5 to 3V3 (it overrides the 10k) and plug in
+ USB, or power cycle. It shows up as `0483:df11`. A keyword that already
+ runs this firmware gets there with `DFU` over USB serial instead.
2. **Flash it once.** Either one:
```sh
STM32_Programmer_CLI -c port=usb1 -d release/keyword_complete.hex -v
dfu-util -a 0 -d 0483:df11 -D release/keyword_complete.dfu
```
-3. **Start the app.** Unplug, take the wire off pin 5, and plug it back in.
- Until step 5 the chip still reads the BOOT0 pin, and PH3 floats on this
- board, so tie pin 5 to GND for the first boot: the stack install resets the
- chip and a floating BOOT0 could land it in DFU halfway. (ST's AN3156 says
- DfuSe "leave" only jumps to the address, and the WB isn't in its list of
- parts that reset there, so `dfu-util -a 0 -d 0483:df11 -s 0x08000000:leave`
- should start it too without touching the option bytes. I haven't tried that
- on the keyword.)
+3. **Start the app.** Remove the bridge to 3V3, then unplug and plug it back
+ in. The 10k holds BOOT0 low, so the resets during the stack install stay in
+ the app. (ST's AN3156 says DfuSe "leave" only jumps to the address, and the
+ WB isn't in its list of parts that reset there, so
+ `dfu-util -a 0 -d 0483:df11 -s 0x08000000:leave` should start it too without
+ touching the option bytes. I haven't tried that on the keyword.)
4. **Let it install the stack.** It comes up on USB serial, finds the stack at
0x080D0000 and has FUS install it (`STACK PROGRESS ...` lines), resets and
comes back as **Keyword**. Check:
@@ -101,12 +104,18 @@ keymap page or anything of FUS.
STACK? -> STACK ble v=1.24.0 fus=2.2.0
BOOTCFG? -> BOOTCFG nBOOT0=1 nSWBOOT0=1 nBOOT1=1 RDP=0xAA
```
-5. **Lock the boot.** Only once `STACK?` shows the stack and the app has run
- more than 10 s, send `BOOTLOCK yes` over USB serial. It changes only
- `nSWBOOT0` to 0 and keeps `nBOOT0` at 1, never RDP or anything else, then
- reloads the option bytes (a reset). `BOOTCFG?` should then show
- `nSWBOOT0=0`. From then on BOOT0 doesn't matter and `DFU` is the way back
- into the ROM bootloader. The pin 5 wire can go.
+
+That's it. To get back into DFU later, send `DFU` or bridge pin 5 to 3V3 and
+reset.
+
+**Optional, only for a board with BOOT0 left floating:** without the 10k a
+floating BOOT0 can randomly start the ROM bootloader, so keep pin 5 wired to
+GND through the steps above, then send `BOOTLOCK yes` over USB serial once
+`STACK?` shows the stack and the app has run more than 10 s. It changes only
+`nSWBOOT0` to 0 and keeps `nBOOT0` at 1, never RDP or anything else, then
+reloads the option bytes (a reset). `BOOTCFG?` should show `nSWBOOT0=0`. From
+then on BOOT0 does nothing and `DFU` is the only way back into the ROM
+bootloader short of SWD.
### First install over USB DFU, two files
@@ -178,8 +187,10 @@ into the system bootloader instead of the firmware. That's why its option bytes
were set to ignore the pin and always boot from flash (`nSWBOOT0 = 0`,
`nBOOT0 = 1`). Leave them like that: `DFU` above gets into the system
bootloader without them.
-`BOOTLOCK yes` over USB serial sets exactly those two from the app (see
-[One-flash setup](#one-flash-setup)), and `BOOTCFG?` shows them.
+With BOOT0 tied to GND through 10k instead (see
+[One-flash setup](#one-flash-setup)) the factory option bytes are fine. On a
+board that keeps BOOT0 floating, `BOOTLOCK yes` over USB serial sets exactly
+those two from the app, and `BOOTCFG?` shows them.
## Keybit dock and side bus