# brintOS SOM programming station

This machine programs an Emcraft STM32F7 SOM through a debug adapter attached to
this machine over WebUSB: an Olimex ARM-USB-TINY-H by default (JTAG), a SEGGER
J-Link (JTAG or SWD), or a standalone ST-LINK/V2 (SWD).

    som-mfg-f7                             # program a whole SOM, unattended: U-Boot, kernel, boot test, MAC
    som-mfg-f7 --dry-run                   # check the set-up first; touches no board
    som-program-f7                         # write U-Boot into the SOM's eNVM and verify it
    som-program-f7 --adapter jlink         # the same through a J-Link (JTAG)
    som-program-f7 --adapter jlink --transport swd   # ... over SWD
    som-program-f7 --adapter stlink        # the same through an ST-LINK/V2 (SWD)
    som-program-f7 --help                  # --adapter, --transport, --speed, --backup, --readback, --dry-run

openocd here also carries the nRF53/nRF91 flash driver. A Nordic target is
SWD-only, so select SWD before its config. On an nRF9160-DK, put an external
J-Link on its Debug in header; its own on-board J-Link cannot be used from
brintos.io yet (guide §4.3):

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

It can also open the SOM's serial console, once the carrier's USB-serial bridge
(P1) is granted to this machine too:

    som-console               # the SOM's console in picocom, 115200 8N1; C-a C-x leaves
    som-console --list        # every USB-serial port this machine has
    minicom -b 115200 -D $(som-console --find)

The full procedure — what connects where, the host set-up, the kernel half, and
what to do when it does not work:

    /usr/share/brintos-som-station/flashing-an-stm32f7-som-from-brintos.md

A USB Ethernet adapter granted the same way puts this machine on your network,
with a TFTP client and server (Developer mode needed; no DHCP):

    ip link set eth1 up; ip addr add <address>/24 dev eth1
    curl --tftp-blksize 8192 -o /tmp/<file> tftp://<server>/<file>
    /etc/init.d/tftpd-hpa start               # serves /var/lib/tftpboot

Cabled straight to the SOM's RJ-45, the adapter is how the SOM gets its kernel:
its U-Boot fetches `stm32f7/rootfs.uImage` from this machine with `run update`
(the flashing guide's section 6, which also times full SOM programming).

`som-mfg-f7` does all of it in one run, the way Emcraft's production station
does: with the Olimex (P3), the board's console (P1) and the Ethernet adapter
attached, it writes U-Boot, writes the kernel, boots the board and pings this
machine from it, and leaves the environment the board ships with. It gives each
board the next MAC address from the station's list,
`/var/lib/brintos-som/mac/maclist`, which you fill in once (flashing guide
section 6.4).

How, what was measured, and what does not work yet:

    /usr/share/brintos-som-station/usb-ethernet-and-tftp.md

What the station carries:

| Path | What it is |
|---|---|
| `/var/lib/brintos-som/mac/maclist`, `lastmac` | the MAC range `som-mfg-f7` hands out, and the last one it gave |
| `/var/lib/brintos-som/som-mfg-f7.exp` | if present, runs in place of `som-mfg-f7`: a fixed script without a new image |
| `/usr/share/brintos-som/stm32f7/u-boot.bin` | the firmware `som-program-f7` writes |
| `/usr/share/brintos-som/stm32f7/PROVENANCE` | where that binary came from, and its sha256 |
| `/usr/share/brintos-som/stm32f7/rootfs.uImage` | the SOM's kernel, which its U-Boot fetches from this machine over TFTP and writes into NOR |
| `/usr/share/brintos-som/stm32f7/rootfs.uImage.PROVENANCE` | which release the kernel is, its sha256, and the CRC32 U-Boot prints over it |
| `/var/lib/tftpboot/stm32f7` | a link to that directory: the TFTP server serves both files as `stm32f7/<file>` |
| `/usr/share/openocd/scripts/mfg-jtag.cfg` | the one place the JTAG adapter is named |
| `/usr/share/openocd/scripts/interface/jlink.cfg` | the J-Link, for `--adapter jlink` |
| `/usr/share/openocd/scripts/interface/stlink.cfg` | the ST-Link, for `--adapter stlink` |
| `/usr/share/openocd/scripts/target/nordic/` | the Nordic target configs, under upstream's newer path |
| `/usr/share/openocd/scripts/board/emcraft-som-stm32f7.cfg` | the SOM's openocd board config |
| `/boot/hardwarejs.html`, `/boot/hardwarejs.js` | the HardwareJS runtime this machine launches with in Developer mode |
| `/usr/share/brintos-hardwarejs-runtime/PROVENANCE` | the HardwareJS commit that runtime was built from, and its sha256 sums |

To check the station itself, with no board attached:

    brintos-selftest 99-som-station.test 99-som-console.test 99-minicom.test

With P1's bridge granted, the last two also exchange a line with the board.

Snapshots and Developer mode:

- This machine runs in **Developer mode** (the machine's Settings). The site then
  runs the HardwareJS in this image's `/boot` (its commit is in `PROVENANCE`)
  rather than its own release. `expect`, `openocd` and USB devices need it. A
  snapshot is the filesystem only, so a fork has to turn Developer mode on too.
- `latest` is the current station. It moves only after a change passes the
  station's test plan on brintos.io.
- Fixed snapshots are tags named by date and content (`2026-10-01-minicom-serial`).
  They never change, each has a note of what it holds and its known issues, and
  only the last few are kept. A tag ending in `-dev` carries a patched runtime.