commands

Command reference

All four programs, their flags, common flows, and the exit-code contract.

Command reference

<program> --help and <program> <subcommand> --help are authoritative. This page writes the same surface out in one place. The --help text prints default paths for the user running it.

Targets. Wherever a command takes a target, it accepts a board's name, its full uid, or a short-uid token. The client asks the local daemon, which knows local and peer boards, and then goes to whichever host owns the board. You never name the host, except with mbrelay connect robot@host.

Every client needs a local daemon. mbregistry list, mbdeploy deploy/list/debug, mbserial and mbrelay fail with exit 3 if no mbregistry runs on this host. The one exception is mbdeploy build.

mbregistry

mbregistry list [--json] [--socket PATH]
mbregistry run [--socket PATH] [--db PATH] [--interval SEC] [--peer HOST[:PORT]]...
               [--remote-port N] [--peer-pub-port N] [--peer-snapshot-port N]
               [--auth-token SECRET] [--no-relay-pool] [--windows-service]
mbregistry install-service [--output PATH] [--udev-output PATH] [--user NAME]

list prints a table with the columns STATE NAME UID FIRMWARE HOST PORT. HOST is local or the peer's host name. STATE is one of:

STATE	Meaning
free	present and unlocked
locked by <kind> ...	someone holds it (flash, serial, relay)
no-firmware	present, but no announcement was heard when it was probed
gone	unplugged / not currently enumerated
peer unreachable	owned by a peer whose daemon can't be reached right now

--json prints the same data, machine-readable. Use it from scripts.

mbregistry run flags and environment variables

Precedence: flag > environment variable > default.

Flag	Env var	Default
--socket PATH	MBREGISTRY_SOCKET	per platform/user (table below)
--db PATH	MBREGISTRY_DB	per platform/user (table below)
--interval SEC	(none)	2.0 (USB poll)
--peer HOST[:PORT]	(none)	none. Repeatable. PORT = peer's remote API, default 7440
--remote-port N	MBREGISTRY_REMOTE_PORT	7440
--peer-pub-port N	MBREGISTRY_PEER_PUB_PORT	7442
--peer-snapshot-port N	MBREGISTRY_PEER_SNAPSHOT_PORT	7443
--auth-token SECRET	MBREGISTRY_TOKEN	unset, meaning no auth (see Networking for the gap)
--no-relay-pool	(none)	pool on. Disables port 7444 / _mbrelay._tcp
--windows-service	(none)	only for the Windows SCM binPath=

Default database and local API:

Platform / user	Database	Local API
Linux, root	/var/lib/mbregistry/devices.db	/run/mbregistry/api.sock
Linux, user	$XDG_STATE_HOME/mbregistry/devices.db (~/.local/state/...)	$XDG_RUNTIME_DIR/mbregistry/api.sock, else ~/.cache/mbregistry/api.sock
macOS, root	/Library/Application Support/mbregistry/devices.db	/var/run/mbregistry/api.sock
macOS, user	~/Library/Application Support/mbregistry/devices.db	~/Library/Application Support/mbregistry/api.sock
Windows	%ProgramData%\mbregistry\devices.db	\\.\pipe\mbregistry

Clients (all programs below, and mbregistry list) look for their own user's socket first, then the system one. --socket or MBREGISTRY_SOCKET overrides the search.

mbdeploy

mbdeploy deploy <target> (--hex FILE | --repo OWNER/REPO[@TAG]) [--asset NAME]
                [--force-relay] [--reprobe-timeout SEC] [--socket PATH]
mbdeploy list [--json] [--socket PATH]
mbdeploy debug [--socket PATH] <target> -- <pyocd args...>
mbdeploy build [--clean] [--verbose] [-j N] [--build-cmd CMD]

• deploy --repo OWNER/REPO flashes the GitHub Latest release's hex. @TAG pins a release, and --asset picks a file when a release has several. Downloads are cached in ~/.cache/mbtools/hex/<owner>/<repo>/<tag>/. Set GITHUB_TOKEN to avoid API rate limits or to reach private repos.
• deploy --hex FILE flashes a local .hex.
• After flashing, deploy waits up to --reprobe-timeout (default 15 s) for the board to announce its new firmware.
• deploy refuses a board whose announced role looks like a relay/bridge unless you pass --force-relay.
• list is the same table as mbregistry list.
• debug runs pyOCD against the named board. Give --socket before <target>. Everything after <target> passes to pyOCD unchanged, e.g. mbdeploy debug tapiz -- commander.
• build runs <python> build.py in the current directory. It needs no daemon.

mbserial

mbserial <target> [word ...] [--reset] [--baud N] [--timeout SEC] [--socket PATH]

• With no words, it opens an interactive session.
• With words, it sends them as one line (joined with spaces, newline terminated), waits --timeout (default 2 s) for the reply, prints it, and exits. Example: mbserial tapiz HELLO.
• Connecting does not reset the board. --reset resets it on purpose (BREAK on Linux, reopen on macOS).
• --baud defaults to 115200.

mbrelay

mbrelay connect <robot>[@host] [--send LINE]... [--expect REGEX] [--timeout SEC]
                [--no-probe] [--escape CHAR] [--socket PATH]
mbrelay names get <name>
mbrelay names set <name> <channel> <group>
mbrelay names clear <name>
mbrelay names list

• connect picks a free relay (a board whose role contains RELAY/BRIDGE), preferring one on this host. It tunes the relay to the robot's channel/group and runs a PING liveness probe (skip it with --no-probe). Then it opens an interactive session; Ctrl-] quits (change it with --escape).
• <robot>@<host> pins the session to a relay owned by that peer.
• Script mode: --send LINE (repeatable) sends lines, then exits. --expect REGEX waits for a matching reply for up to --timeout (default 8 s).
• Robot names are five letters, consonant-vowel alternating ([zvgpt][uoiea][zvgpt][uoiea][zvgpt], e.g. tapiz). A name's channel/group is derived from the name unless set explicitly. names set/clear replicate to every peered host.

Exit codes

The same for every client:

Code	Meaning
0	success
1	generic failure
2	bad command line
3	no daemon: local API socket/pipe missing or unreachable
4	no such device
5	device locked by someone else
6	a flash ran and failed
130	mbdeploy interrupted (Ctrl-C)

Common flows

# what's out there?
mbregistry list

# flash the latest release of a firmware repo to a board, wherever it is
mbdeploy deploy tapiz --repo OWNER/REPO

# ask a board who it is
mbserial tapiz HELLO

# drive a robot over the radio from a script
mbrelay connect tapiz --send "<command>" --expect "<reply regex>" --timeout 5

# scripts: branch on exit codes, not text
mbdeploy deploy tapiz --hex build/firmware.hex; case $? in 0) ;; 5) echo busy ;; *) echo failed ;; esac

(Board names above are examples.)