# Flashing an STM32F7 SOM from a brintOS shell

Handoff, 2026-09-25. Emcraft **STM32F7-SOM** on a **SOM-BSB-EXT** baseboard,
programmed from a terminal inside a brintOS machine running in a browser tab.

The board needs two images, and this machine writes both:

| Half | What is written | Written from | State |
|---|---|---|---|
| U-Boot | eNVM at `0x08000000`, 119,416 B | the brintOS shell, over JTAG through WebUSB | works, one command — §4 |
| Linux kernel (`rootfs.uImage`) | NOR at U-Boot's `flashaddr`, 5,785,356 B | the board's U-Boot, over TFTP from this machine on a straight Ethernet cable | works — §6 |

**What a brintOS machine does.** It drives the JTAG adapter through WebUSB, it
opens the board's serial console the same way once P1's USB-serial bridge is
granted to it (§5.1), and it serves the kernel to the board's U-Boot through a
USB Ethernet adapter cabled straight to the board (§6). The adapter needs
**Developer mode**, and a kernel with the USB Ethernet drivers, which this image
has: the site's own HardwareJS release refused the adapter when last measured
(2026-09-30), and Developer mode runs the one in this image instead. §6.4 times
full SOM programming: U-Boot, kernel and test, from this machine.

The console from the shell works in the browser: on 2026-09-30, in Chrome on a
Linux host, a brintos.io machine took P1's bridge over WebUSB as `/dev/ttyUSB0`,
`som-console` found it, and minicom — driven by Expect — exchanged lines with the
board at 115200. On our bench the board's shell and its U-Boot both answer through
that node, and a `reset` typed there brings the U-Boot banner back through it. On
a Mac, Apple's own FTDI driver holds P1's bridge (§2.1), so on a Mac read the
console from the Mac, as in §5.

Everything below was run on our bench, on 2026-09-25 unless a section gives
another date, and the outputs are quoted from those runs.

## 1. What you need, and what connects where

Two USB cables, a USB Ethernet adapter and an Ethernet cable. Everything lands
on your Mac or Linux PC; nothing needs a second computer, and the board takes no
separate power supply. The adapter route (§6) was measured from a Linux host
only: on a Mac, the console from the brintOS shell is not expected to work
(§2.1) and an adapter granted from a Mac has not been tried, so read the console
from the Mac (§5) and serve the kernel from it (§6.5).

    Mac (Chrome)                             SOM-BSB-EXT + STM32F7-SOM
     |
     +-- USB -- Olimex ARM-USB-TINY-H ------- P3, the JTAG header   U-Boot, §4
     |          (or ARM-USB-OCD-H, §4.1, a SEGGER J-Link, §4.3,
     |          or an ST-LINK/V2, §4.4)
     |
     +-- USB A-to-mini-B -------------------- P1, mini-USB          §5, §6
     |                                        console AND power
     |
     `-- USB -- USB Ethernet adapter ---- Ethernet cable ---- RJ45  the kernel, §6

    The Ethernet cable runs from the adapter straight to the board's RJ45;
    nothing else is on it. (§6.5 serves the kernel from a host instead.)

| Link | Purpose | Needed for |
|---|---|---|
| JTAG adapter — the Olimex, a J-Link (§4.3) or an ST-LINK/V2 (§4.4): USB to the Mac, 20-pin ribbon to **P3** | the only path that writes eNVM | §4 — the U-Boot half. This is the one the brintOS machine drives, through Chrome's WebUSB. |
| Plain USB A-to-mini-B cable, Mac to **P1** | powers the board **and** carries its console, 115200 8N1 | Power: everything. Console: §5 (confirm the banner) and §6 (typing U-Boot commands) — the U-Boot flash itself does not use it. |
| A USB Ethernet adapter, USB to the Mac, and a straight Ethernet cable from it to the board's **RJ45** | TFTP transfer of the kernel, from this machine to the board's U-Boot | §6. The one tried is a TP-Link USB 10/100 LAN (`2357:0602`); which others work is in `usb-ethernet-and-tftp.md`. The machine needs Developer mode for it (§1.1). |

P1 carries power and serial over the one cable, so two things follow: use a real
data cable (a charge-only mini-USB cable powers the board and gives you no
console), and **pulling P1 is how you power-cycle the board**. The USB-serial
bridge is on the baseboard — ours enumerates as an FTDI FT232R — so no special
serial cable is needed.

A USB-C-only Mac needs an adapter or hub for both: the Olimex is USB-A, and P1
wants A-to-mini-B unless you have a C-to-mini-B cable.

Both images ship with this machine (§9). What you need is the machine itself:

### 1.1 Your own copy of the machine — fork it

The station image lives in a public machine of ours,
`https://brintos.io/sergei/core-image-brintos-manufacturing`. **Fork it into
your own account before you use it.** Running ours directly gives you a
read-only root: the writable `live` root of a machine belongs to its owner, and
a visitor's session gets the published snapshot as it stands.

1. Sign in to brintos.io in Chrome.
2. Open `https://brintos.io/sergei/core-image-brintos-manufacturing` and press
   **Fork** (the direct link is
   `https://brintos.io/new?fork=sergei/core-image-brintos-manufacturing`).
   Take it from **`latest`**, or from a dated tag (below).
3. In *your* machine, turn on **Settings → General → Developer mode**. The
   station carries its own HardwareJS runtime in `/boot` and runs on it only in
   Developer mode. With it off, brintos.io runs its own release: Expect cannot
   spawn there, so the console and minicom self-tests fail.
4. Work in your machine from then on:
   `https://brintos.io/<your-account>/core-image-brintos-manufacturing`.
   **Launch** is on that page.

A fork is instantaneous — it copies a root pointer, not the image — so this costs
you nothing but the click. What it buys is a `live` root you own and can write
to, which is what a session needs.

**Snapshots.** `latest` is the newest station image, published only after it
passes the station test plan on brintos.io. A dated tag, such as
`2026-10-01-minicom-serial`, never changes, and its description says what it
holds and its known issues. A tag ending in `-dev` carries our runtime and needs
Developer mode on. The snapshot selector next to the machine name shows which
one a page is showing, and `/usr/share/brintos-hardwarejs-runtime/PROVENANCE` in
the guest names the HardwareJS build the machine carries.

## 2. Let the browser reach the adapter

A machine attaches a USB device only if Chrome can both **open** the device node
and **claim** its interfaces. The frame reports either failure with one sentence:
*"granted, but not attached: the OS driver owns this device, so the browser cannot
claim it"*.

### 2.1 On macOS

The node-permission half does not exist — macOS has no udev and Chrome needs no
rule to open a USB device. What can still bite is Apple's FTDI serial driver
attaching to the adapter's channels, which is the second failure above.

Plug the Olimex in and look:

    ls /dev/cu.usbserial-*

Entries that appear when the Olimex is plugged in (and vanish when it is
unplugged) mean macOS's own driver has taken it. Chrome may then be refused the
claim, with the message above.

**We have not run this on a Mac** — our bench is Linux, so treat this as the one
step that may need a round trip. If the claim is refused, tell us what the frame
said and we will work it out; the classic workaround is unloading the driver
(`sudo kextunload -b com.apple.driver.AppleUSBFTDI`), which recent macOS may
refuse. Failing that, the U-Boot half runs from any Linux host with the same
command, and only that half needs the browser at all.

A **SEGGER J-Link** carries a serial port of its own (two CDC interfaces) beside
the vendor interface openocd drives. On a Mac those CDC interfaces may go to
Apple's CDC driver, and whether Chrome is then allowed to claim the J-Link has
not been tried. If the frame refuses it, send us its message, as above.

P1's serial bridge is a different USB device and stays with macOS's driver —
that is what you want; it is how you read the board (§5). The same driver is why
§5.1, the console from the brintOS shell, is not expected to work on a Mac: the
machine would need to claim that bridge, and macOS does not release it.

### 2.2 On a Linux host

Two host problems, either of which blocks the claim:

- the node `/dev/bus/usb/<bus>/<dev>` is `root:root 0664`, so `open()` fails;
- `ftdi_sio` is bound to the adapter's interface, so `claimInterface()` fails.

`lsusb` lists the device in both cases — enumeration does not need the claim, so
a device you can see is not a device the browser can use.

One-off repair, as root (both revert on replug):

    sudo chmod 666 /dev/bus/usb/003/010          # your bus/dev from lsusb
    echo -n '3-4:1.1' | sudo tee /sys/bus/usb/drivers/ftdi_sio/unbind

Permanent, tested on our host 2026-09-17:

    # /etc/udev/rules.d/70-brintos-webusb.rules
    SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="15ba", ATTRS{idProduct}=="002a", MODE="0660", GROUP="plugdev", TAG+="uaccess"
    ACTION=="bind", SUBSYSTEM=="usb", DRIVER=="ftdi_sio", ATTRS{idVendor}=="15ba", ATTRS{idProduct}=="002a", RUN+="/bin/sh -c 'echo -n %k > /sys/bus/usb/drivers/ftdi_sio/unbind'"

`udevadm control --reload`, then replug. Use `002b` in place of `002a` for an
ARM-USB-OCD-H. Do not apply the second rule to a serial adapter — unbinding
`ftdi_sio` from one takes its `/dev/ttyUSB*` away.

**Except P1's bridge, when you want the console in the machine (§5.1).** Then
unbind it for that one board only, keyed on the bridge's serial number
(`lsusb -v -d 0403:6001 | grep iSerial`; each SOM-BSB-EXT has its own). Every
other FTDI device keeps its host tty, and this board has none while the rule is
installed:

    # /etc/udev/rules.d/71-brintos-som-console.rules -- one pair per board
    SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_device", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="A505CMFS", MODE="0660", GROUP="plugdev", TAG+="uaccess"
    ACTION=="bind", SUBSYSTEM=="usb", DRIVER=="ftdi_sio", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6001", ATTRS{serial}=="A505CMFS", RUN+="/bin/sh -c 'echo -n %k > /sys/bus/usb/drivers/ftdi_sio/unbind'"

Tested on our host on 2026-09-29 with board `A6014SHO`. The node there was
already writable, so only the second line was needed; keep the first where it is
not. **A one-off `unbind` does not stick for the bridge**: when Chrome claims the
device it resets it, the kernel re-probes, and `ftdi_sio` binds again — so the
machine never gets it. The `ACTION=="bind"` line is what holds, because it
unbinds again on every re-probe.

If you do not want the rule for good, put the same file in
`/run/udev/rules.d/` instead of `/etc/udev/rules.d/` and `udevadm control
--reload`: it lasts until the host reboots, and the board's host tty comes back
after that without anyone having to remember to delete a rule.

**A SEGGER J-Link** (`1366:0105`) is held differently: the host's `cdc_acm`
binds the two interfaces of its serial port (`/dev/ttyACM0`), and openocd drives
the third, vendor-specific one. Its node is usually writable already. SEGGER's
own `99-jlink.rules`, and openocd's `60-openocd.rules`, make it `0666`. Our
Chrome attach (2026-10-05) was measured with `cdc_acm` released from both
interfaces. With `cdc_acm` still bound it has not been tried, and the claim
refusal above is the likely result. Release it as root (reverts on replug; take
the bus path from `lsusb -t`):

    echo -n '3-4:1.0' | sudo tee /sys/bus/usb/drivers/cdc_acm/unbind
    echo -n '3-4:1.1' | sudo tee /sys/bus/usb/drivers/cdc_acm/unbind

`cdc_acm` binds again whenever the J-Link re-enumerates. A replug does that, and
so did powering the board off under it (§8). Release it again before the next
attach.

The UCL-SOM-BSB starter kit's console is a CP2104, held by the host's `cp210x`
instead of `ftdi_sio`. Its line is the same with the driver and ids changed:

    ACTION=="bind", SUBSYSTEM=="usb", DRIVER=="cp210x", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", ATTRS{serial}=="<serial>", RUN+="/bin/sh -c 'echo -n %k > /sys/bus/usb/drivers/cp210x/unbind'"

The CP2104 has been measured in a brintOS guest (bound by `cp210x`, read and
written), but not yet attached from a browser, so this line is untested there.

## 3. Attach the adapter to the machine

1. Open **your fork's** page (§1.1) and **Launch**.
2. Go to the **USB devices** tab, click **Attach USB device**, pick the Olimex
   (or the J-Link, or the ST-Link) in Chrome's chooser.
3. `lsusb` in the machine's console should now list `15ba:002a` (a J-Link:
   `1366:0105 SEGGER J-Link`; an ST-Link: `0483:3748`).

**Attach one device at a time, on the running machine.** The site's runtime puts
devices granted before Launch on one port (§8). If Chrome still remembers a grant
from an earlier session, such as P1's bridge, that device is attached at Launch
too; detach it in the USB devices tab if this session does not need it. With a
J-Link on P3, **do not unplug P1**: it is the board's power, and the J-Link
dropped off USB when it was replugged (§8).

If an attach was refused once, **reload the machine page before re-granting**.
Chrome keeps a stale handle and every later grant then reports the frame's other
message, "the device disconnected before it could attach — replug it and try
again", while the host shows the device present with no driver bound.

## 4. Write U-Boot — from the brintOS shell

    som-program-f7

That is the whole command. It resolves the image, programs it, and has openocd
verify what it wrote. It takes no backup of the eNVM and does not read the flash
back unless you ask, with `--backup` and `--readback` (§4.1). Output from a real
run (elisions marked):

    som-program-f7: image:    /usr/share/brintos-som/stm32f7/u-boot.bin (built-in, 119416 bytes)
    som-program-f7: sha256:   6e060662217fcf52c2a5d7a300616e9bbec20b6e2cfe42eb219469416e844096
    som-program-f7: provenance: /usr/share/brintos-som/stm32f7/PROVENANCE
      | version: U-Boot 2010.03-cortexm-2.1.2 (Oct 23 2016 - 14:21:51)
      | …
    som-program-f7: target:   eNVM 0x08000000 on /usr/share/openocd/scripts/board/emcraft-som-stm32f7.cfg
    som-program-f7: speed:    the board config's default after reset
    som-program-f7: adapter:  the seam's default in /usr/share/openocd/scripts/mfg-jtag.cfg
    som-program-f7: programming ...
    Info : JTAG tap: STM32F756.cpu tap/device found: 0x5ba00477 (mfg: 0x23b (ARM Ltd), part: 0xba00, ver: 0x5)
    Info : [STM32F756.cpu] Cortex-M7 r0p0 processor detected
    ** Programming Started **   ** Programming Finished **
    ** Verify Started **        ** Verified OK **
    ** Resetting Target **
    som-program-f7: the board was reset and is running what was just written.
    som-program-f7: PASS -- wrote /usr/share/brintos-som/stm32f7/u-boot.bin to 0x08000000

One `PASS`/`FAIL` line ends every run, and the `image:` + `sha256:` lines are the
record of what the board was given.

### 4.1 Flags

| Flag | Use |
|---|---|
| `--adapter olimex-arm-usb-ocd-h` | drive an ARM-USB-OCD-H; `--adapter jlink` drives a SEGGER J-Link (§4.3), `--adapter stlink` an ST-LINK/V2 (§4.4). Takes a bare name, looked up in `interface/` and then `interface/ftdi/`, a filename, or a path under `/usr/share/openocd/scripts`. Installed: `olimex-arm-usb-tiny-h`, `olimex-arm-usb-ocd-h`, `olimex-arm-usb-ocd`, `olimex-jtag-tiny`, `olimex-arm-jtag-swd`, `jlink` and `stlink`. An unknown name fails before any hardware is touched. |
| `--transport swd` | `jtag` or `swd` (an ST-Link takes `hla_swd` or `hla_jtag` instead); the adapter must offer it. Default: the adapter's first, which is `jtag` for the Olimex and the J-Link and `hla_swd` for an ST-Link. |
| `--speed 1000` | JTAG clock after reset, kHz. Default 2000, which is safe out of reset (the core runs from the 16 MHz HSI and the adapter wants to stay under F_CPU/6) and is what the write costs: 141 KiB/s at 2 MHz against 11.8 KiB/s at 150 kHz. |
| `--image FILE` | program something else. Resolution order is `--image`, then `/mnt/media/stm32f7/u-boot.bin`, then the built-in; a U-Boot of your own and its record: §7. |
| `--backup` | read the whole 1 MB eNVM out before writing. A new board carries nothing worth saving, so a production run takes none; take one on a board whose contents you do not already have, because it is the only copy of what the board arrived with. It lands in the `workdir:` the run prints, as `envm-<UTC stamp>.bin`: the first writable of `/var/tmp`, `/var/backups` and `/tmp`, or `$SOM_BACKUP_DIR`. In `/tmp` it lasts only as long as the session; launch your fork as its owner, where `/var/backups` is writable and kept, to keep it. **On brintos.io, `/var/backups` is slow and can fail:** it is the machine's stored root, and on 2026-10-05 the 1 MiB backup took 201.8 s there against 69.2 s in `/tmp`, on a day the same store refused other writes with `EIO` ([linux-in-the-browser#203](https://gitlab.com/brintos/linux-in-the-browser/-/work_items/203)). For a backup you need only for this session, as in a write with restore, run `SOM_BACKUP_DIR=/tmp som-program-f7 --backup …`. |
| `--readback` | after openocd's own verify, read the flash back and compare it with the image on this side. A production run needs none: a bad U-Boot does not reach its prompt. |
| `--no-backup`, `--no-readback` | accepted, so older scripts keep working; they change nothing. |
| `--dry-run` | resolve and print the image, touch no hardware. |

**An ARM-USB-OCD-H needs that flag and nothing else** — no file edited, no
snapshot published. `--adapter` sets `BRINTOS_JTAG_IFACE` before the board config
is sourced, and `/usr/share/openocd/scripts/mfg-jtag.cfg` — which every board
config sources, and which names the default — reads it there. Both adapter
configs ship in the image.

That indirection exists because a running machine's filesystem is per-session: an
edit inside a machine holds for that session and survives it only if you publish
a snapshot of your fork, which copies the image. A flag costs neither.

### 4.2 How long it takes

The first openocd run in a fresh session loads the 26 MB openocd binary: on
2026-09-25, a run with no backup and no read-back took **62.2 s** first, then
**21.2 s** and **17.9 s**, against 2.9 s on a host. A run that seems to hang for
half a minute before printing anything is this, not a dead adapter.

A run with `--backup --readback` (backup, write, read-back) after that, measured
on 2026-10-07/08 on our SOM-BSB-EXT boards (Chrome: the median of seven runs;
single runs, through either probe, took from 52 to 76 s):

| Where | Olimex ARM-USB-TINY-H | ST-LINK/V2 |
|---|---|---|
| Chrome on brintos.io | 58 s | 61 s |
| a host running the same openocd | 11.5 s | 14.4 s |

More than half of it is the 1 MiB backup. The rest is mostly what each USB
transfer costs inside a machine, not the JTAG clock: openocd waits for each
answer before it sends the next request, a transfer costs a machine several
milliseconds where a host spends well under one, and a 119 KB write makes 1,200
to 2,500 of them. Each openocd start inside a machine also costs between 1 and
10 s before its first transfer.

In earlier versions of `som-program-f7` the read-back after the write ran at the
150 kHz connect clock (125 kHz on an ST-Link): it followed a halt, and only a
reset raises the clock. It now follows a reset, as the backup does. In Chrome
the read-back step went from 15–21 s to about 6–7 s, and a restore of a 1 MiB
backup (`--readback --image <backup>`), whose read-back is 1 MiB too, from
178 s to 86 s through the Olimex (one run each, the same board; the ST-Link's
is in §4.4). The read-back figures in §4.3 are from before that.

### 4.3 Through a SEGGER J-Link, over JTAG or SWD

    som-program-f7 --adapter jlink                   # JTAG
    som-program-f7 --adapter jlink --transport swd   # SWD

The J-Link goes on P3 like the Olimex, and attaches the same way (§3). Nothing
else changes: `--adapter` names the J-Link's interface config, and the board
config leaves the transport to the adapter unless `--transport` names one.

Measured on 2026-10-05, in Chrome on brintos.io, with a J-Link V9 on our
SOM-BSB-EXT, when the backup and the read-back were still the default (they are
`--backup --readback` now). The eNVM was backed up (1 MiB in 70 s) and erased. U-Boot was
written over JTAG and read back as the image. The backup was then written back
over SWD and read back as the backup, and a final dump equalled the original:

    som-program-f7: adapter:  interface/jlink.cfg (override)
    som-program-f7: transport: swd (override)
    ** Verified OK **
    som-program-f7: readback: 14d65a34…7eb8b matches the image
    som-program-f7: PASS -- wrote /tmp/envm-orig.bin to 0x08000000

How long the pieces took on brintos.io (Chrome, the same day, a J-Link V9):
- a 1 MiB eNVM dump into `/tmp`: about 70 s (14.6–15.0 KiB/s);
- the erase of all eight sectors: 9 s;
- U-Boot's write, verify and 119 KB read-back: a few tens of seconds;
- the 1 MiB restore's read-back over SWD: 138 s (7.4 KiB/s).

The dump and the write ran at 2000 kHz, after the reset each makes. The
read-backs ran at the 150 kHz connect clock, which is why the restore's took
138 s; `som-program-f7` now reads back after a reset (§4.2).

**The nRF91.** openocd here carries the nRF53/nRF91 flash driver, backported to
this openocd, and the Nordic target configs under `target/nordic/` as well as
`target/`. The nRF91 is SWD-only and the J-Link offers JTAG first, so select SWD
before the target config:

    openocd -f interface/jlink.cfg -c "transport select swd" -f target/nordic/nrf91.cfg

On a machine with no nRF91 attached, that parses and creates `nrf91.cpu` with
two flash banks, `nrf91.flash` and `nrf91.uicr`.

**An nRF9160-DK, measured on 2026-10-05.** Use an external J-Link on the DK's
10-pin **Debug in** header, through a 20-to-10-pin Cortex-Debug adapter, with
the DK powered from its micro-USB and its debug switch on nRF91. **Do not use
the DK's own on-board J-Link from brintos.io.** It also carries a mass-storage
drive, Chrome refuses to let a page claim that, and the site's runtime then
refuses the whole device ([brintos/hardwarejs#41](https://gitlab.com/brintos/hardwarejs/-/work_items/41)).
Attach only the external J-Link. With it on Debug in:

    openocd -f interface/jlink.cfg -c "transport select swd" -f target/nordic/nrf91.cfg -c init -c "flash probe 0" -c shutdown

prints `VTarget = 1.795 V`, `SWD DPIDR 0x6ba02477`, `Cortex-M33 r0p2` and
`nRF9160-SICA 1024kB Flash, 256kB RAM`. `VTarget = 0.000 V` means the cable is
on the wrong header or the wrong way round. On the nRF9160, programming is
openocd's own `program`; there is no `som-program-f7` for the nRF91. **On an
nRF9151, read the two rules below first:**

    openocd -f interface/jlink.cfg -c "transport select swd" -f target/nordic/nrf91.cfg -c init -c "program <image> 0x00000000 verify" -c "reset run" -c shutdown

In Chrome on brintos.io, the DK's 1 MiB application flash was backed up (`dump_image`),
erased (`flash erase_sector 0 0 last`, 52 s), programmed back with `Verified OK`,
and read back equal to the factory image. That order, an erase and then
`program` in a new session, is safe on the nRF9160 only.

**An nRF9151 SOM, measured on 2026-10-05** (SOM-NRF9151-BSB-1A, a J-Link EDU
Mini, Chrome on macOS). The probe prints `nRF9151-LACA 1024kB Flash, 256kB RAM`
at `VTarget = 2.94 V`. b0, both MCUboot slots and the application read back
equal to the 1.2-114 release, at about 6.8 KiB/s through the EDU Mini. A full
1 MiB `dump_image` took 154 s and passed `verify_image`; `program` of that dump
with `verify` took 5 min 48 s, and the board rebooted into 1.2-114.

**Disable the application's watchdog first.** The 1.2-114 application resets the
chip 3–6 s after openocd halts it (a 2.5 s feed and a 10 s timeout), and the
halted dump or program then dies with `SWD: Read data parity mismatch`. Run
`watchdog disable` on the board's own shell before starting. It stays off across
`reset halt` and comes back at the next boot.

**On an nRF9151, two mistakes cannot be undone:**
- **A reset of an erased chip locks debug access** (APPROTECT), and `program`
  starts with `reset init`. Never run `program` after a separate
  `flash erase_sector`. Erase, write and verify in one openocd session with no
  reset in between, and reset only after the verify passes.
- **The UICR is write-once** (b0's key hashes, and a counter b0 updates at run
  time). Emcraft's hex files carry UICR records: strip everything from
  `0xFF0000` up before writing, and compare the UICR rather than write it.

The one-session form, for a binary image of the application flash (a `.bin`
from `dump_image` carries no UICR):

    openocd -f interface/jlink.cfg -c "transport select swd" -f target/nordic/nrf91.cfg -c init -c "reset halt" -c "flash erase_sector 0 0 last" -c "flash write_image <image.bin> 0x00000000" -c "verify_image <image.bin> 0x00000000" -c "reset run" -c shutdown

It prints `erased sectors 0 through 255 on flash bank 0`, `wrote 1048576 bytes
from file …` and `verified 1048576 bytes`, and resets only once the verify has
passed; a failed step stops openocd before the `reset run`. Measured on the
nRF9160-DK on 2026-10-07 (erase 66.8 s, write 51.3 s, verify 1.4 s, the
factory image back byte for byte); not yet run on an nRF9151. Once in two runs
it stopped at once with `Error: Target not halted` and `failed erasing sectors
0 to 255`: the reset had not halted the core, nothing was erased, and the same
command then passed.

**Reading needs no halt.** A `dump_image` straight after `init`, with the watchdog
running, read 1 MiB in 57 s (18 KiB/s through the EDU Mini), 2.6 times the
halted rate. That was measured through a board config for the SOM; the same read
through the configs above has not been run:

    openocd -f interface/jlink.cfg -c "transport select swd" -f target/nordic/nrf91.cfg -c init -c "dump_image <file> 0 0x100000" -c shutdown

### 4.4 Through a standalone ST-LINK/V2, over SWD

    som-program-f7 --adapter stlink

A standalone ST-LINK/V2 has the same 20-pin JTAG connector as the Olimex, so it
goes on P3 and attaches the same way (§3); `lsusb` then lists `0483:3748
STMicroelectronics ST-LINK/V2`. On a Linux host its node has to be writable by
the user running Chrome, which openocd's `60-openocd.rules` or ST's
`49-stlinkv2.rules` arrange; no host driver binds it. Its openocd driver (`hla`)
offers `hla_swd` first and `hla_jtag` second, not the plain `jtag` and `swd` the
other adapters take, and the board config takes the adapter's first, so no
`--transport` is needed. Only `hla_swd` has been measured on this board.

Measured on 2026-10-07, in Chrome on brintos.io, with an ST-LINK/V2 (firmware
V2J32S7) on our SOM-BSB-EXT, by the same procedure as the J-Link run in §4.3.
`som-program-f7` backed the eNVM up into `/tmp` and wrote U-Boot, with the backup
and the read-back that were then the default (`--backup --readback` now). The
bank was then erased, U-Boot written into the blank bank and read back as the
image, the backup written back and read back as the backup, and a final dump
equalled the original:

    som-program-f7: adapter:  interface/stlink.cfg (override)
    Info : STLINK V2J32S7 (API v2) VID:PID 0483:3748
    Info : [STM32F756.cpu] Cortex-M7 r0p0 processor detected
    ** Verified OK **
    som-program-f7: readback: 6e060662…4096 matches the image
    som-program-f7: PASS -- wrote /usr/share/brintos-som/stm32f7/u-boot.bin to 0x08000000

The same procedure ran again on 2026-10-08, on another of our boards, with the
read-back after a reset. How long the pieces took on brintos.io (Chrome) that
day:
- `SOM_BACKUP_DIR=/tmp som-program-f7 --adapter stlink --backup --readback`, its 1 MiB backup and
  119 KB read-back included: 52 s;
- the erase of all eight sectors: 17 s for the whole openocd run;
- U-Boot's write, verify and read-back into the blank bank: 21 s;
- the restore of the 1 MiB backup, with its 1 MiB read-back: 89 s;
- a final dump of 1 MiB into `/tmp`: 24 s for the dump itself (42 KiB/s), 34 s
  for the openocd run.

The ST-Link has a fixed set of SWD clocks and runs the nearest one at or below
the clock asked for: the board config's 2000 kHz runs as 1800 kHz, and openocd
says so on each reset (`Unable to match requested speed 2000 kHz, using 1800
kHz`). In earlier versions of `som-program-f7` the read-backs followed a halt
and ran at the connect clock (150 kHz asked for, which the ST-Link runs as
125 kHz). On 2026-10-07 the same five pieces took 83, 18, 37, 201 and 35 s, the
1 MiB restore longer than everything else together. Not all of that gap is the
read-back: that day's first connect also took 34 s against 14 s. Over seven
runs of each in Chrome, a 119 KB read-back took 4.6–12.3 s after a reset and
16.8–23.3 s after a halt, about 15 s apart at the median.

**Only a standalone ST-LINK/V2.** An STLINK-V3, and the ST-LINK/V2-1 built into
Nucleo and Discovery boards, also carry a USB mass-storage interface, and that
stops them on brintos.io (§8).

## 5. Confirm on the serial console

Open the console — that is the P1 cable, and on macOS it shows up as a
`/dev/cu.usbserial-*` entry:

    ls /dev/cu.usbserial-*
    screen /dev/cu.usbserial-XXXX 115200        # `Ctrl-A` then `k` to quit

(`picocom -b 115200 /dev/cu.usbserial-XXXX` does the same if you have it. On our
Linux bench the same device is `/dev/ttyUSB<n>`.)

Reset the board and watch. Expected, verbatim:

    U-Boot 2010.03-cortexm-2.1.2 (Oct 23 2016 - 14:21:51)

    CPU  : STM32F7 (Cortex-M7)
    Freqs: SYSCLK=200MHz,HCLK=200MHz,PCLK1=50MHz,PCLK2=100MHz
    Board: STM32F7 SOM Rev 1.A, www.emcraft.com
    DRAM:  32 MB
    Flash: 16 MB
    …
    Hit any key to stop autoboot:  1
    STM32F7-SOM>

`STM32F7-SOM>` is this build's prompt. `STM32F7-SOM-UCL>` means the board is
running the LCD starter kit's cm-2.4.0 build instead — a different product, not
an older copy of this one.

### 5.1 From the brintOS shell

Grant P1's bridge to the machine the way §3 grants the Olimex: in the **USB
devices** tab, pick `FT232R USB UART` (its serial names the board). On a Linux
host that first needs the per-board rule in §2.2; on a Mac see §2.1. Then, in the
machine's console:

    som-console --list                           # every USB-serial port, with its USB id and serial
    som-console                                  # open the SOM's console in picocom, 115200 8N1; C-a C-x leaves
    minicom -b 115200 -D $(som-console --find)   # the same in minicom; C-a x leaves

minicom, and Expect scripts that drive it, run in the machine on brintos.io.
Both are built without shared libraries on purpose: the HardwareJS release the
site serves cannot fork a program that needs two or more shared libraries
(brintos/hardwarejs#50), and Expect forks every time it spawns.

`som-console` finds the console by the bridge's USB id, not by tty number, which
matters as soon as a second USB-serial device is granted: an ARM-USB-OCD-H has an
RS232 channel of its own and takes a `/dev/ttyUSB*` too. Where two SOM-BSB-EXT
bridges are granted at once it refuses to guess; name one with `--serial`.
`som-console --find` prints the node alone, for scripts and Expect:

    som-console --list                                # every port, with its USB id and serial
    som-console --find --serial A505CMFS              # one board by its bridge's serial
    SOM_CONSOLE_SERIAL=A505CMFS som-console           # the same, from the environment
    som-console --dev /dev/ttyUSB1                    # or name the node directly

**With the Olimex attached, the console stays silent until the first openocd
run.** Once a machine has opened the adapter, its reset line holds the SOM in
reset until openocd sets the adapter's pins. `som-program-f7` does that as part
of the write; on its own, `openocd -f board/emcraft-som-stm32f7.cfg -c init -c
shutdown` releases it, and the board boots. Measured on our host, outside
brintOS: the console answered with the adapter idle, went silent once it was
opened, and came back after that openocd command.

Only one side uses the console at a time: while the machine holds P1's bridge,
the host has no tty for it. To hand it back, detach the device in the USB
devices tab and replug P1.

## 6. Write the kernel — from this machine, over a straight cable

U-Boot carries a macro for exactly this, `update`:

    update=tftp ${image};prot off ${flashaddr} +${filesize};era ${flashaddr} +${filesize};
           cp.b ${loadaddr} ${flashaddr} ${filesize};setenv kernelsize ${filesize};
           setenv filesize; setenv fileaddr;saveenv

It fetches `${image}` by TFTP from `${serverip}`, writes it at `${flashaddr}` and
saves the environment. Addressing is static, out of U-Boot's own environment; no
DHCP is involved. This machine is the TFTP server: a USB Ethernet adapter
granted to it, cabled straight to the board's RJ45.

### 6.1 This machine's side

With Developer mode on, attach the adapter in the **USB devices** tab, wait about
ten seconds, then in the console:

    ip link set eth1 up
    ip addr add 192.168.7.1/24 dev eth1
    /etc/init.d/tftpd-hpa start

If the adapter is not `eth1`, find it by its MAC address
(`grep -l <mac> /sys/class/net/*/address`). The kernel is already in the TFTP
root: `/var/lib/tftpboot/stm32f7` is a link to
`/usr/share/brintos-som/stm32f7/`, so the board asks for
`stm32f7/rootfs.uImage` and nothing is copied first. A kernel of your own: §7.
The adapter's host set-up
(a Linux host's kernel holds it until a udev rule lets go), what was measured,
and what does not work: `/usr/share/brintos-som-station/usb-ethernet-and-tftp.md`.

### 6.2 At the board's U-Boot prompt

Open the console from this machine (§5.1; on a Mac, from the Mac, §5) and stop
at `STM32F7-SOM>`. The countdown is short, so start a reset in the background
first, then open the console and press Ctrl-C about once a second until the
prompt appears and stays:

    (sleep 8; openocd -f board/emcraft-som-stm32f7.cfg -c init -c "reset run" -c shutdown >/tmp/ocd.log 2>&1) &
    som-console

The reset also releases the reset line an opened Olimex holds (§5.1); openocd's
first run in a session takes about a minute (§4.2). That command drives the
default adapter; for another, name its config first, as `--adapter` would (§4.1), e.g.
`openocd -c "set BRINTOS_JTAG_IFACE interface/jlink.cfg" -f board/…`. At the
prompt:

    printenv flashaddr                      # where update will write: §6.3
    setenv ipaddr 192.168.7.2
    setenv serverip 192.168.7.1
    setenv image stm32f7/rootfs.uImage
    run update

From our bench, 2026-10-08 (§6.4 has the timings):

    Auto-negotiation...completed.
    STM32_MAC: link UP (100/Half)
    TFTP from server 192.168.7.1; our IP address is 192.168.7.2
    Filename 'stm32f7/rootfs.uImage'.
    Load address: 0xc0007fb4
    Loading: T #################################################################
    …
    Bytes transferred = 5785356 (58470c hex)
    … Erased 45 sectors
    Copy to Flash... done
    Saving Environment to Flash...

Check the copy in NOR against the image rather than trusting it:

    STM32F7-SOM> crc32 ${flashaddr} ${kernelsize}
    CRC32 for 60020000 ... 605a470b ==> 87504267

`87504267` is the `crc32:` line of
`/usr/share/brintos-som/stm32f7/rootfs.uImage.PROVENANCE`. Then `reset`:
`bootcmd=run flashboot`, so the board boots what was just written:

    ## Booting kernel from Legacy Image at 60020000 ...
       Image Name:   Linux-4.2.0-cortexm-2.1.2
       Verifying Checksum ... OK
    …
    Linux version 4.2.0-cortexm-2.1.2 …
    / #

The kernel takes its address from U-Boot (`flashboot` runs `addip`), so the
board's Linux reaches this machine at once: `ping -c 3 192.168.7.1` there, and
`ping -c 3 192.168.7.2` here, answered three of three each way.

Console habits worth knowing:

- **A bare Enter at the U-Boot prompt repeats the last command.** After
  `run update` that is a second write. Wake the prompt with Ctrl-C instead.
- **This U-Boot has no `ping` command.** To test the cable from U-Boot without
  writing anything, fetch into RAM and check it:
  `tftp ${loadaddr} stm32f7/rootfs.uImage`, then `crc32 ${loadaddr} ${filesize}`.
- `update` ends with `saveenv`, so the addresses are stored with the kernel.
- A fetch can start `Loading: T` or `Loading: T T`: U-Boot timing out on its
  first requests and retrying, about 5 s each by default, and then running to
  the end. Most first fetches after a reset lose the first: the board's link
  goes down and up as the fetch starts, the board sends its first ARP request as
  soon as its link is up, and in the loads traced the adapter passed that packet
  on before it told this machine the link was up, so this machine dropped its
  answer. A second fetch in the same U-Boot session starts at once. `setenv tftptimeout 1000` before the fetch makes
  U-Boot ask again after 1 s, its minimum, instead of 5 s; it also asks this
  machine's TFTP server to resend after 1 s. It applies to every wait in the
  fetch: U-Boot allows ten (`T`) and gives the fetch up at the eleventh
  (`Retry count exceeded`). From a machine you launch as its owner, where more
  waits timed out, runs on 2026-10-12 spent up to six. `update` saves the variable with the rest;
  `setenv tftptimeout` and `saveenv` remove it from the saved environment, and a
  U-Boot that has already run a fetch with it keeps 1 s until a `reset`.

### 6.3 Where `flashaddr` points

`update` writes wherever `flashaddr` says, so read it first on a board you did
not program yourself:

| NOR address | Contents |
|---|---|
| `0x60000000` | the saved U-Boot environment, 128 KB |
| `0x60020000` | the kernel, in this U-Boot's default environment (`flashaddr=60020000`) |

A board whose environment has been erased, which is every board the run in §6.4
programs, takes the default and writes the kernel at `0x60020000`. A board can
carry a saved environment naming another address: one of ours had
`flashaddr=600A0000`, with a splash image at `0x60020000`.

### 6.4 Full SOM programming, the way the VF6 station does it

One command runs the production station's whole run for this SOM
(`target_som-stm32f7.exp`), unattended: `som-mfg-f7`. Attach the three devices
(§3, §5.1, §6.1: the Olimex on P3, the board's FT232R on P1, the Ethernet
adapter cabled to the board's RJ45), then:

    som-mfg-f7 --dry-run          # the MAC it would give, the console, the adapter; touches no board
    som-mfg-f7                    # program the board

It finds the console (`som-console --find`) and the adapter (the one USB network
interface), gives the adapter `192.168.7.1/24` and starts the TFTP server if
they are not already so, and then runs steps 1 to 7 below. It prints a line per
step with its time and ends with one line, `som-mfg-f7: PASS -- <MAC> programmed
in <s> s` or `som-mfg-f7: FAIL -- step <n> (<what>): <why>`, exit status 0 or 1.
On a failure it also prints the last of what the board said; the whole console
transcript is in `/tmp/som-mfg-f7-<time>.log`. `-v` shows the console as it
goes. `som-mfg-f7 --help` has the rest: `--console`, `--netif`, the addresses,
`--no-net`, `--kernel` (the kernel to write, §7), and `--adapter`, `--transport`,
`--speed` and `--image`, which go to `som-program-f7`.

If U-Boot gives a fetch up (`Retry count exceeded`), before its first block or
during the blocks, it would start it again by itself; `som-mfg-f7` stops it with
Ctrl-C, which also stops the NOR write chained after it, and runs `update`
again, five runs in all, the VF6 station's limit. (The VF6 script stops a fetch
at `ARP Retry count exceeded` or at two timeouts in a row, `T T`; `som-mfg-f7`
lets U-Boot retry until it gives the fetch up.) If the fetch fails in any other way
before its last block, it stops the board the same way, before U-Boot reaches
the NOR write.

What it checks: openocd's verify of the eNVM write; U-Boot reaching its prompt
and printing the version in U-Boot's record (§7); the kernel image's size as
U-Boot received it; `bootm`'s checksum of the kernel in
NOR when the board boots it (`Verifying Checksum ... OK`), and the kernel's
version; the board's link, and three of three pings from the board to this
machine; and that each `saveenv` wrote its sector (`Writing to Flash... done`).
`--reset-test` adds the VF6 station's last step, which waits for you to
press the board's reset button.

**The MAC address.** A new board has none: once U-Boot is written, its default
environment carries `C0:B1:3C:88:88:85`, the same on every board. Like the VF6
station, `som-mfg-f7` gives each board the next address from a list, in the
same two files the VF6 kept on its SD card, here in
`/var/lib/brintos-som/mac/`:

    maclist   the range: one line, FROM TO, e.g.  C0:B1:3C:84:00:00 C0:B1:3C:84:0F:FF
    lastmac   the last address given out; absent at first, then written by every run

The next address is `lastmac` plus one, or FROM when there is no `lastmac`. It
is written to `lastmac` in step 4, before it is given to the board, so a run
that fails after that has used its address and the next board gets the one
after it. A missing list, a range whose first three octets differ, or a list
used up are refused before the board is touched. The range is yours to
allocate: one list serves one station at a time, so two stations need a range
each, and an address given with `--mac` is not checked against the list. The files live on this machine, so keep the machine
your own fork (§1.1), signed in. `--mac <MAC>` gives one board an address without
touching the list; `--keep-mac` keeps the address a board already has, for
re-programming one.

**A fixed script without a new image.** If `/var/lib/brintos-som/som-mfg-f7.exp`
exists, `som-mfg-f7` runs it instead of itself and says so on its first line,
as the VF6 station ran the `expect/` scripts on its SD card. Put a copy there
(from the machine's Files tab, with `curl` over TFTP from your host, or pasted
at the console), edit it, and the next run uses it; remove it to go back.
`--no-override` runs the installed script regardless. Every run prints the
script it is and its sha256.

The steps it runs, which are also how to do it by hand: every step but the first
is typed at the board's console.

1. `som-program-f7` — U-Boot into the eNVM (§4), with no backup and no
   read-back. Nothing on a new board needs saving, and a bad write shows
   itself: U-Boot does not reach its prompt in step 2.
2. The U-Boot prompt (Ctrl-C as the board resets), and `printenv ethaddr`:
   the board's MAC address before step 3 erases it. A board with no saved
   environment shows the built-in `C0:B1:3C:88:88:85`, the same on every such
   board; give it one of your own (by hand, or from the list as `som-mfg-f7`
   does).
3. `prot off all`, `erase 60000000 +20001` — erase the saved environment, and
   with it the next 128 KB sector, at `0x60020000`, where step 5 writes.
4. `reset` (`*** Warning - bad CRC, using default environment`, stop autoboot),
   `setenv serverip 192.168.7.1`, `setenv ipaddr 192.168.7.2`,
   `setenv ethaddr <the MAC from step 2, or your own>`, `setenv bootdelay 1`, `saveenv`.
5. `setenv image stm32f7/rootfs.uImage`, `setenv tftptimeout 1000` (not in the
   VF6 run; §6.2), `run update` (§6.2). For a kernel of your own, first link it
   on this machine by its full path, and then `setenv image
   som-mfg-f7/rootfs.uImage` instead:

       mkdir -p /tmp/som-mfg-f7
       ln -sfn /mnt/media/stm32f7/<the kernel> /tmp/som-mfg-f7/rootfs.uImage
       ls -lL /tmp/som-mfg-f7/rootfs.uImage

   The `ls` line, not `ln`'s message, says whether it took: it lists the
   kernel's size.
6. `reset`; check the U-Boot and Linux banners; at the board's `/ #`,
   `ping -c 3 192.168.7.1`.
7. `reboot -f`, stop autoboot, the shipping environment:
   `setenv serverip 192.168.0.1`, `setenv ipaddr 192.168.0.2`,
   `setenv gatewayip 192.168.0.1`, `setenv image rootfs.uImage` (the name the
   VF6 station ships), `setenv bootdelay 3`, `setenv tftptimeout` (step 5's,
   which `update` saved; not in the VF6 run), `saveenv`.

The VF6 station also asks the operator to press the board's reset button and
watch it boot; that needs a hand on the board and is not in the timings.

Measured on 2026-10-09, before `som-mfg-f7` set `tftptimeout`, in headless
Chrome on a Linux host, in Developer mode: an Olimex
ARM-USB-TINY-H on P3, the board's own FT232R on P1, and a TP-Link USB 10/100 LAN
cabled straight to the RJ45 of an STM32F7-SOM on a SOM-BSB-EXT. An Expect script
in this machine typed the steps at the console, so the figures carry no human
pauses. For comparison, the same script also ran on that Linux host with no
machine at all: openocd built from this image's revision, the host's own
`ftdi_sio` console and TFTP server, the same adapter, cable and board.

| VF6 step | This machine | The host alone | This machine, with the read-back |
|---|---|---|---|
| 1. U-Boot into the eNVM, `som-program-f7` | 9.9 s | 2.9 s | 49.2 s |
| 2.–4. the prompt; erase the environment; set and save the new one | 3.0 s | 2.8 s | 3.0 s |
| 5. `run update` | 64.1 s | 45.3 s | 71.5 s |
| - load the kernel image to DRAM over TFTP | 29.1 s | 10.3 s | — |
| - NOR erase, copy and `saveenv` (the board's own work) | 35.0 s | 35.0 s | — |
| 6. boot, both banners, the link, `ping` from the board | 9.9 s | 10.9 s | 8.2 s |
| 7. the shipping environment | 0.8 s | 0.7 s | 0.8 s |
| **Full SOM programming, steps 1–7** | **87.6 s** | **62.5 s** | 132.6 s |

`som-mfg-f7` itself, the same day, board and runtime: 96.8 s for steps 1–7 (the
eNVM 14.5 s, `run update` 68.8 s), a second run in the session; the session's
first took 115.2 s, its openocd and its first fetch both slower. Its step 0,
the adapter's address and the TFTP server, took 14.0 s the first time in a
session and 0.5 s once they were up. Other runs on the same day: this machine 97.7 and 96.2 s (step 1: 16.9 and
12.2 s; step 5: 67.3 and 70.4 s), the host alone 62.5 s twice. The totals are
sums of the unrounded step times. The last column is an earlier run that read
the eNVM back after writing it, as `som-program-f7 --readback` does now; it also
pinged without waiting for the link. The script read the
MAC before step 1 and outside the timings. Not counted: launching the machine
and attaching the three devices, which happen once per session, not once per
board.

Step 6 waits, as the VF6 station's script does, up to 15 s for the board's
link-up line, `eth0: Link is Up - 100Mbps/Full`, before the board pings. The
board's PHY negotiates again after every reset, and a ping sent before it is up
is lost: on the host the line came 8.8 s after the reset, and pinging without
the wait lost all three. Where no line comes within the 15 s, the script pings
once at a time until one is answered.

Where the time goes: step 1 is JTAG traffic, at a USB round trip per
transaction through the browser (§4.2). Step 5 is loading the kernel image to
DRAM plus the board's own work, which takes the same 35.0 s from either side.
This U-Boot negotiates TFTP blocks of about 1,468 B and waits for each to be
acknowledged, so the load is about 3,950 round trips through the adapter: the
blocks took 21.7–25.1 s from this machine and 3.1–3.2 s from the host. Before
the first block, U-Boot starts its Ethernet, and a request lost meanwhile costs
its retry timeout, about 5 s: with none lost, the first block came 4.5 s after
the command here and 2.3–2.4 s on the host. Four of five loads here lost one,
and two of four on the host. In the two loads traced (2026-10-12), the one lost
was the board's first ARP request, which reached this machine at least 8 ms and
38 ms before the adapter reported the link up (§6.2). `som-mfg-f7` sets
`tftptimeout` to 1 s, so it now costs 1 s.

**The kernel over JTAG instead of TFTP.** With U-Boot at its prompt, openocd can
write the image straight into the board's DRAM, where `tftp` puts it:

    openocd -f board/emcraft-som-stm32f7.cfg -c init -c halt \
        -c "adapter speed 15000" \
        -c "load_image /usr/share/brintos-som/stm32f7/rootfs.uImage 0xc0007fb4 bin" \
        -c resume -c shutdown

The clock is set after `halt` because the board config raises it from 150 kHz
only on a reset. Then, at the U-Boot prompt, `crc32 ${loadaddr} 58470c` (`==>
87504267`) and the rest of `update`:

    setenv filesize 58470c; prot off ${flashaddr} +${filesize}; era ${flashaddr} +${filesize}; cp.b ${loadaddr} ${flashaddr} ${filesize}; setenv kernelsize ${filesize}; setenv filesize; setenv fileaddr; saveenv

It needs no Ethernet adapter and no TFTP server, but it is not faster. Loading
the kernel image to DRAM, from the command until the image is in DRAM (the
`crc32` after it not included), with TFTP and JTAG alternating:

| Method | This machine | The host alone |
|---|---|---|
| **Load the kernel image to DRAM over TFTP** | **29.1–34.7 s** | **5.4–10.3 s** |
| - wait for the first block | 4.5–10.5 s | 2.3–7.1 s |
| - transfer | 21.7–25.1 s | 3.1–3.2 s |
| **Load the kernel image to DRAM over JTAG (15 MHz)** | **47.4–50.8 s** | **7.9 s** |
| - openocd start, connect, halt, exit | 6.4–9.2 s | 0.3 s |
| - transfer | 41.0–41.6 s | 7.6–7.7 s |

TFTP here is `tftp ${loadaddr} stm32f7/rootfs.uImage` from a freshly reset
U-Boot, as in step 5 at U-Boot's default 5 s timeout: five loads here and four on the host, against four and
three JTAG loads. So JTAG at 15 MHz costs 13–22 s more per board here, and on
the host the two are even. The JTAG transfer at other clocks:

| JTAG clock | This machine | The host alone |
|---|---|---|
| 2 MHz | 108.0 s (52 KiB/s) | 38.7 s (146 KiB/s) |
| 8 MHz | 60.6 s (93 KiB/s) | 12.4 s (454 KiB/s) |
| 15 MHz | 41.8 s (135 KiB/s) | 7.6 s (740 KiB/s) |

On the host 4 MHz took 22.3 s and 20 MHz 7.9 s, no faster than 15 MHz; 30 MHz
failed (`Invalid ACK (4) in DAP response`). Every load's `crc32` matched, and the
copy written to NOR from one booted.

### 6.5 From a host instead

Without the adapter, serve `rootfs.uImage` from any TFTP server the board can
reach, and set `serverip` to it and `image` to the file's path under that
server's root:

- **The board on your local network**, with a TFTP server you already run on
  it, and a free address for the board on that subnet.
- **A straight cable to the Mac**, with the Mac serving TFTP: System Settings →
  Network → the Ethernet interface → Configure IPv4: **Manually**, address
  `192.168.7.1`, mask `255.255.255.0`, no router; on the board the same
  `setenv`s as §6.2. macOS has carried a `tftpd` serving `/private/tftpboot`
  (`sudo launchctl load -w /System/Library/LaunchDaemons/tftp.plist` where that
  file exists); otherwise Homebrew's `tftp-hpa`, or a throwaway server such as
  `python3 -m py3tftp` run in the directory holding the image.

From a TFTP server on our bench LAN, `run update` took **38 s** for the same
5,785,356 B.

## 7. Where the images come from

By default, from this machine: U-Boot and the kernel ship inside it, under
`/usr/share/brintos-som/stm32f7/`, each with its record (§9). They are the
cortexm-2.1.2 release the VF6 station programs, and the station serves the
kernel from there.

### 7.1 A U-Boot or a kernel of your own

`som-program-f7` and `som-mfg-f7` take each image from the first of:

1. the file you name: `--image FILE` for U-Boot, `--kernel FILE` for the kernel
   (`som-mfg-f7` only), under any name (a U-Boot's without spaces or brackets,
   which openocd would read as part of its command);
2. `/mnt/media/stm32f7/u-boot.bin` and `/mnt/media/stm32f7/rootfs.uImage`;
3. the built-in copy.

Every run says which copy it took and its sha256: for U-Boot the
`som-program-f7: image:` and `sha256:` lines, for the kernel the
`som-mfg-f7: kernel:` and `kernel record:` lines. `som-mfg-f7 --dry-run`
prints them and touches no board.

**Each image needs its record.** `som-mfg-f7` checks the board against what the
record says: U-Boot's prompt and banner, the kernel's size and image name. It
uses the record beside the image, `PROVENANCE` in U-Boot's directory or
`<file>.PROVENANCE` beside the kernel; without one, the built-in record, which
fits only the built-in images. A different kernel with no record of its own is
then refused before the board is touched (its size), and a different U-Boot is
written and then fails at step 2 or step 6 (its prompt or its banner).

You do not write a record by hand: `som-provenance-f7` reads it out of the image.

    som-provenance-f7 --origin "<where the files came from>" /mnt/media/stm32f7/u-boot.bin /mnt/media/stm32f7/rootfs.uImage

From a U-Boot it takes the `U-Boot 20…` banner, and records this station's
prompt, `STM32F7-SOM>`, or the one you give with `--prompt`; it refuses a U-Boot
that does not carry that prompt. From a uImage it takes the image name in its
header. It records each file's size and sha256, and prints each record it
writes. A kernel's image name is `Linux-<release>`, as the built-in one's is:
the run waits for the board to print `Linux version <release>`. A
U-Boot's record is `PROVENANCE`, one per directory, so keep each U-Boot in a
directory of its own. Read a record with `sed -n p <record>`.

### 7.2 Putting them on the machine

With the machine **stopped**, its **Files** tab uploads files into it:

1. Stop the machine. In the Files tab, open `/mnt`. The station image does not
   have `media/stm32f7` in it: make each with **Add file → Create new
   directory**, the first time. Upload the files into `/mnt/media/stm32f7/`
   (**Add file → Upload files…**): `u-boot.bin` and `rootfs.uImage`, or either
   one, or other names that you will give with `--image` and `--kernel`.
2. Launch your fork, signed in as its owner (§1.1). An anonymous launch runs
   the machine's published snapshot, which does not have your upload.
3. Write the records: `som-provenance-f7 /mnt/media/stm32f7/<the files>`.
4. `som-program-f7 --dry-run` (with `--image` if you used another name): its
   `image:` line names your U-Boot. `som-mfg-f7 --dry-run` (with `--kernel`):
   its `kernel:` line names your kernel.
5. `som-mfg-f7`.

To go back to the built-in images, delete the files from `/mnt/media/stm32f7/`.

A launched machine has no Files tab. Into a running one, a file comes over the
adapter: on a network with a TFTP server, fetch it into `/tmp`
(`usb-ethernet-and-tftp.md`, section 4), write its record there with
`som-provenance-f7`, and name it with `--image` or `--kernel`. `/tmp` is empty
after a restart. Keep large files out of the machine's own filesystem from the
console: writing 5.8 MB into it took 337 s.

### 7.3 Changing the built-in images

The built-in images are part of the station image, in meta-brintos's
`recipes-bsp/brintos-som-firmware`: replace the file under `files/`, set the
recipe's `SOM_F7_UBOOT_*` or `SOM_F7_KERNEL_*` values to the new image (a
sha256 that does not match the file fails the build), rebuild the image and
publish it as a new station release. The station's own test names the built-in
images too: `99-som-station.test` and its stand-in board,
`data/som-mfg-f7-board.exp`, in `recipes-support/brintos-selftests`, expect
their banner, prompt and image name. Change them with the images, or the
station's test plan fails; and this guide and the README, which name the
cortexm-2.1.2 release and its sizes.

## 8. When it does not work

| Symptom | Cause / what to do |
|---|---|
| Chrome's chooser offers no device | The host owns it — §2.1 on macOS, §2.2 on Linux; for a USB Ethernet adapter, `usb-ethernet-and-tftp.md` §2. Seeing it in `lsusb` / System Information proves nothing. |
| "granted, but not attached: the OS driver owns this device" | Same. Repair, then **reload the page** before re-granting. On macOS this is the case we have not tested — send us the message. |
| "the device disconnected before it could attach" | A stale Chrome handle after an earlier refusal. Reload the page; a replug was not needed here. On this board a replug of P1 is also a power cycle — see the J-Link row below. |
| The J-Link is listed by `lsusb` in the guest, but openocd fails with `LIBUSB_ERROR_NO_DEVICE` and the J-Link is then gone | The J-Link left the host's USB bus and came back as a new device, and the guest was not told. Seen on 2026-10-05 two seconds after P1 was replugged with the J-Link attached; the host's `cdc_acm` then held it again. Release `cdc_acm` (§2.2), reload the page, and attach the J-Link alone. A dry run and `lsusb` do not prove the J-Link is there; openocd's `init` is the first thing that talks to it. |
| `Error: unable to open ftdi device` inside the guest | The machine has not been given the device, or it was revoked. Re-attach in the USB devices tab. |
| `JTAG tap … tap/device found` missing, or `all ones`/`all zeroes` | Cable, orientation, or the board is unpowered. Nothing to do with the image. |
| `Error: newtap: nrf91.cpu missing IR length` | The J-Link's first transport is JTAG and the nRF91 is SWD-only. Put `-c "transport select swd"` before `-f target/nordic/nrf91.cfg` (§4.3). |
| An nRF91 dump or `program` dies with `SWD: Read data parity mismatch` a few seconds after the halt | The application's watchdog reset the chip. Run `watchdog disable` on the board's own shell first (§4.3). |
| An nRF91 erase stops at once with `Error: Target not halted` and `failed erasing sectors 0 to 255` | The reset did not halt the core, and nothing was erased. Run the same command again (§4.3). |
| `som-program-f7: FAIL -- no such adapter config: …` | `--adapter` typo. The resolved path is in the message; the installed names are in §4.1. |
| `som-program-f7: FAIL -- openocd stopped before the erase (the lines above say why); nothing was written` | openocd did not get as far as the flash: it printed no `** Programming Started **`. Its own lines above the FAIL say why, usually `unable to open ftdi device` or a missing `tap/device found` (the rows above). The eNVM is as it was. |
| `som-program-f7: FAIL -- program/verify failed -- the flash is in an unknown state` | openocd started the erase and then failed: `** Programming Started **` is above the FAIL, then `** Programming Failed **` or `** Verify Failed **`. Without `** Programming Started **`, the run could not keep a copy of openocd's output to tell, and says this rather than guess. The eNVM may be blank or partly written, and the board may not reach U-Boot until a write passes: run `som-program-f7` again. A run with `--backup` names its backup here; `som-program-f7 --image <that file>` writes it back. |
| A Nordic DK's on-board J-Link (`1366:1055`) attaches, but `lsusb` shows no interfaces and openocd says `Failed to get configuration descriptor: LIBUSB_ERROR_NOT_FOUND` / `No J-Link device found`; the Log shows `claimInterface(7) refused … protected class` | The on-board J-Link's mass-storage drive (brintos/hardwarejs#41). Use an external J-Link on the DK's Debug in header (§4.3). |
| An STLINK-V3, or the ST-LINK/V2-1 on a Nucleo or Discovery board, does not work from the machine | These carry a USB mass-storage interface beside the debug one. Chrome does not let a page claim mass storage, and the site's runtime claims every interface of a device, so the whole probe is refused ([brintos/hardwarejs#41](https://gitlab.com/brintos/hardwarejs/-/work_items/41)). When a V3 was tried, the guest logged `usb 1-1: can't set config #1, error -32`. The V2-1 carries the same kind of interface and was not tried. Use a standalone ST-LINK/V2 (§4.4). |
| `Info : Unable to match requested speed 2000 kHz, using 1800 kHz` through an ST-Link | Expected. The ST-Link offers a fixed set of SWD clocks, and openocd takes the nearest one below the clock asked for. |
| `Warn : STM32 flash size failed, probe inaccurate - assuming 1024k flash` through an ST-Link | Harmless on this SOM: the STM32F756 has 1024 KiB, which is what openocd assumes. On our bench every ST-Link session that probed the flash bank (a write, an erase, `flash probe`) printed it. |
| `som-console: no USB-serial port matching …` | P1's bridge has not been granted to the machine, or the host still owns it (§2.2). `som-console --list` shows what the machine does have. |
| `som-console: 2 ports match …` | Two SOM-BSB-EXT bridges are granted. Name one: `som-console --serial <its serial>`. |
| The console is silent, and the Olimex is attached | The opened adapter holds the SOM in reset (§5.1). Run any openocd command, e.g. `openocd -f board/emcraft-som-stm32f7.cfg -c init -c shutdown`; `som-program-f7` does it as part of the write. |
| One of two granted devices is missing after Launch | Developer mode is off, and brintos.io's own release attaches every granted device to the same port at launch, so the guest sees one ([brintos/hardwarejs#55](https://gitlab.com/brintos/hardwarejs/-/work_items/55)). The station's own runtime has the fix: turn Developer mode on (§1.1). Otherwise detach the missing device in the USB tab and attach it again: one at a time on a running machine, each gets its own port. |
| Expect's `spawn` or Tcl's `exec` fails with `parent: sync byte write: broken pipe` | Developer mode is off, and brintos.io's own release cannot fork a program that needs two or more shared libraries ([brintos/hardwarejs#50](https://gitlab.com/brintos/hardwarejs/-/work_items/50)). Turn Developer mode on (§1.1) and launch again. |
| `cat <file>` never returns on brintos.io, and the Log shows `RESTART-SENTINEL-LEAK … nr=40` | busybox `cat` copies with `sendfile`, which does not complete on a file the session has not read before ([brintos/glibc#14](https://gitlab.com/brintos/toolchain/glibc/-/work_items/14)). Developer mode does not help: it happens on the station's own runtime too. Press Ctrl-C; the shell is fine afterwards. Read the file with `sed -n p <file>` instead. |
| Partway through a session, a file read never returns, or a write fails with `Unknown error 517` (`RESTART-SENTINEL-LEAK val=517` in the Log) | The session's root filesystem has stopped answering ([brintos/linux#134](https://gitlab.com/brintos/packages/modified/linux/-/work_items/134)). Nothing in the session recovers it: reboot the tab. In a fresh tab, run `som-program-f7` before anything else. |
| `/usr/bin/<tool>: Bad address` when you run a program | That program needs two or more shared libraries and the HardwareJS release the site gave this machine cannot load them (brintos/hardwarejs#43). The station's own tools are built so this does not happen — tell us which program it was. |
| Halt ends with "AggregateError: Filesystem shutdown failed; latest was not updated" | A brintos.io defect on recently created machines (brintos/linux-in-the-browser#205): what you changed inside the machine this session is not saved. The machine itself is unharmed and launches again as it was. |
| `Unknown command 'ping' - try 'help'` at the U-Boot prompt | This U-Boot has no `ping`. Test the cable with a TFTP fetch into RAM (§6.2). |
| `run update` stops at `Loading: T T T …` with no `#` | The board does not reach this machine's TFTP server. On this machine: `ip -4 addr show dev eth1` names `192.168.7.1`, `grep ':0045 00000000:0000' /proc/net/udp` shows the server listening, and `ls -lL /var/lib/tftpboot/stm32f7/` lists the kernel (`/var/lib/tftpboot/som-mfg-f7/` for a kernel of your own). On the board: `printenv serverip ipaddr image`. |
| Nothing on the console, board seems dead | P1 is power as well as console. A charge-only mini-USB cable, or a hub that will not supply the port, gives you exactly this. Re-seat P1 — that is also the power-cycle. |
| First run takes a minute with no output | The cold exec, §4.2. |
| `halt` inside the guest hangs | Known: PID 1 is bash and `reboot(2)` is unimplemented. `sync`, then use the frame's **Halt**. |

## 9. What exactly gets written

The image and its provenance ship together, and the recipe recomputes the hash at
build time, so a binary swapped in without its metadata fails the build:

    image:   u-boot.bin
    target:  Emcraft STM32F7 SOM (STM32F756), eNVM at 0x08000000
    version: U-Boot 2010.03-cortexm-2.1.2 (Oct 23 2016 - 14:21:51)
    prompt:  STM32F7-SOM>
    origin:  tftp://192.168.1.5/…/cm-2.1.2/u-boot.bin
    sha256:  6e060662217fcf52c2a5d7a300616e9bbec20b6e2cfe42eb219469416e844096
    size:    119416 bytes

The kernel's record, `rootfs.uImage.PROVENANCE`, beside it:

    image:   rootfs.uImage
    target:  Emcraft STM32F7 SOM, NOR at U-Boot's flashaddr (60020000 in its default
             environment), written by U-Boot's update over TFTP
    version: Linux-4.2.0-cortexm-2.1.2
    origin:  the cortexm-2.1.2 release, the uimage_file the VF6 station's
             target_som-stm32f7.exp programs
    sha256:  0fe38cdba7ee58841b4a8b2839aeec77f71300445e11cd8c619672d26f5978e5
    crc32:   87504267 (what U-Boot's crc32 prints over the copy in NOR)
    size:    5785356 bytes

The openocd in the image is `0.12.0+dev-00150-g91bd43134`, built for wasm32,
with the J-Link driver enabled and the nRF53/nRF91 flash support backported. The board config is
`board/emcraft-som-stm32f7.cfg`, and it sources `mfg-jtag.cfg` — the one place
the adapter is named.