# brintOS SOM programming station

This machine programs an Emcraft STM32F7 SOM over JTAG, through a JTAG adapter
attached to this machine over WebUSB: an Olimex ARM-USB-TINY-H by default, or a
SEGGER J-Link.

    som-program-f7                         # write U-Boot into the SOM's eNVM, verify, read back
    som-program-f7 --adapter jlink         # the same through a J-Link (JTAG)
    som-program-f7 --adapter jlink --transport swd   # ... over SWD
    som-program-f7 --help                  # --adapter, --transport, --speed, --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

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 |
|---|---|
| `/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/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/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.