dotbot device - flash one cabled board

dotbot device programs one board on your desk, connected over a cable. It talks to the board’s on-board programmer over the SWD/J-Link interface - no external probe needed for normal flashing. On the DotBot v3 the programmer (a J-Link-OB / DAPLink behind an SWD mux) is reached over USB-C; on an nRF5340-DK over its micro-USB port. A separate J-Link is only required for flash-programmer.

To put firmware on the whole fleet over the air, use swarm instead. To build the .hex first, see fw.

Tip

device flash-mari-gateway flashes firmware onto a board. The host-side UART↔MQTT bridge process is a different thing - that’s run gateway.

Note

dotbot device drives nrfjprog (Nordic’s nRF Command Line Tools), not nrfutil - install it and put its bin/ on your PATH before flashing.

Commands

Command	What it does
flash <app|file>	Whole-chip program one app (or a .hex/.bin) onto the board
flash-mari-gateway	Turn an nRF5340-DK into the swarm gateway (both cores + network id)
flash-swarmit-sandbox	Turn a DotBot v3 into a swarm sandbox host (bootloader + netcore + id)
flash-programmer	Re-flash the board’s on-board debug chip (J-Link OB / DAPLink) - needs a J-Link
info	Read a board’s provisioning state (chip id + network id)

Flash an app

flash resolves <app> to ./artifacts/<app>-<board>.hex, building it if the file isn’t there; an explicit .hex/.bin path is flashed as-is.

export DOTBOT_FIRMWARE_REPO=$(pwd)/repos/DotBot-firmware

# Build, then flash the bare DotBot app onto a DotBot v3 (board defaults to dotbot-v3)
dotbot fw artifacts --app dotbot
dotbot device flash dotbot -s 77

-b/--board selects the chip family and core to program. The nrfjprog family and coprocessor are derived from it: nRF52 boards → -f NRF52, no coprocessor; nRF5340 → -f NRF53 with CP_APPLICATION, or CP_NETWORK for a *-net board.

-b only sets the family/core nrfjprog is told to program; the CLI doesn’t read it back from the attached chip. Make sure the cabled board matches -b - e.g. don’t flash an nRF53 image onto a connected nRF52 (or vice versa).

# Gateway onto an nRF52840-DK (device flash picks -f NRF52 from the board)
dotbot fw artifacts --app dotbot_gateway -t nrf52840dk
dotbot device flash dotbot_gateway -b nrf52840dk -s 10

nRF5340 = two cores

The nRF5340’s radio lives on the net core, so an app-core app also needs a net-core image. Build and flash each for its own target - the app image is dotbot_gateway, the net image is nrf5340_net (not dotbot_gateway):

# App core
dotbot fw artifacts --app dotbot_gateway -t nrf5340dk-app
dotbot device flash dotbot_gateway -b nrf5340dk-app -s 10

# Net core (-b *-net routes to CP_NETWORK)
dotbot fw artifacts --app nrf5340_net -t nrf5340dk-net
dotbot device flash nrf5340_net -b nrf5340dk-net -s 10

flash flags (see dotbot device flash --help for the full list):

Flag	Meaning
-b, --board	Target board → chip family + core (default dotbot-v3)
-s, --sn-starting-digits	J-Link serial prefix, e.g. 77 (v3) or 10 (DK)
--sandbox	Resolve the sandbox-app flavor (.bin)
--build-config	Debug | Release (default Release)

Flash a role

flash-mari-gateway and flash-swarmit-sandbox flash a complete system firmware (both cores) and write the network identity in one shot. They auto-fetch the named release into ./artifacts/ if it isn’t cached.

# nRF5340-DK → swarm gateway
dotbot device flash-mari-gateway --swarm-id 0100 -f 0.8.0rc1 -s 10

# DotBot v3 → swarm sandbox host (the firmware that runs OTA apps)
dotbot device flash-swarmit-sandbox --swarm-id 0100 -f 0.8.0rc1 -s 77

Flag	flash-mari-gateway	flash-swarmit-sandbox
--swarm-id	16-bit hex swarm id (or from config)	16-bit hex swarm id (or from config)
-f, --fw-version	release to flash (required)	release to flash (required)
-s, --sn-starting-digits	J-Link serial prefix	J-Link serial prefix
-l, --calibration	-	optional LH2 calibration file to bake in

A board flashed with flash-swarmit-sandbox is what swarm flash targets to run sandboxed apps over the air.

Inspect a board

dotbot device info -s 77

Reports the chip id and network identity. It never fails on a blank board - it says not provisioned and how to fix it.

flash-programmer

Re-flashes the on-board debug chip’s own firmware (J-Link OB or DAPLink). This is obscure, one-time-per-board bring-up and requires an external J-Link.

dotbot device flash-programmer -p daplink -d ./programmer-firmware/

Flag	Meaning
-p, --programmer-firmware	jlink | daplink (required)
-d, --files-dir	directory with the programmer firmware files (required)
--probe-uid	pyOCD probe UID, when multiple probes are attached

Note

Never run nrfjprog (or these commands) under sudo. One sudo run leaves /tmp/boost_interprocess/ owned by root and every later call fails with Operation not permitted. Recover with sudo rm -rf /tmp/boost_interprocess.