start here

Start here

What mbtools is, its four programs, which page answers what, and the known gaps.

mbtools

mbtools finds, flashes and talks to BBC micro:bits attached to any host in a fleet. Each host runs one daemon, mbregistry. The daemon watches USB, identifies each board by what its firmware announces, and keeps a SQLite device database. It grants exclusive locks so two tools never use one board at once, and it peers with the other hosts' daemons over mDNS and ZeroMQ. The client programs then address a board by name, wherever it is plugged in.

Source: https://github.com/League-Microbit/mbtools. The repo's docs/service.md holds the same operational material as this wiki on a single page.

It replaces the older mbdeploy serve daemon and the standalone mbrelay relay server. Robot-console keeps working unchanged through a compatibility layer (see Robot-console compatibility).

The machines are documented elsewhere. This wiki contains no hostnames, IP addresses, SSH details or per-host install state. Those are on the internal Robot Garage wiki at http://robot-garage.home/, which is reachable only from the garage LAN.

The four programs

Program	What it does	Typical command
mbregistry	The daemon (run), plus list and install-service	mbregistry list
mbdeploy	Flash firmware to a board by name, from a GitHub release or a local .hex	mbdeploy deploy <name> --repo OWNER/REPO
mbserial	Raw serial session (or one-shot message) to a board by name	mbserial <name>
mbrelay	Talk to a robot through a micro:bit radio relay; manage robot names	mbrelay connect <robot>[@host]

Run exactly one mbregistry per host. The clients find it on their own: first the running user's own daemon, then the system (root) one.

Which page answers what

Question	Page
How do I install it? Why not pip install mbtools?	Installing mbtools
How do I run the daemon at boot on a Pi / Ubuntu box?	Service on Linux
...on a Mac?	Service on macOS
...on Windows?	Service on Windows
Where are the database and socket? What flags and env vars exist?	Service on Linux, Command reference
What does each command do? What are the exit codes?	Command reference
Which ports? How do hosts find each other? Firewall? Auth?	Networking and peering
How does robot-console find relays now?	Robot-console compatibility
Something is broken	Troubleshooting

Quick orientation for agents

mbregistry list                 # every board this host and its peers know about
mbregistry list --json          # the same, machine-readable
echo $?                         # 3 = no daemon reachable, see Troubleshooting
systemctl status mbregistry     # Linux service state
journalctl -u mbregistry -f     # Linux service log

<program> --help and <program> <subcommand> --help are always authoritative. The code is normative. Where this wiki and the source disagree, the source wins.

Known gaps

1. Clients cannot send the auth token. mbregistry run --auth-token (or MBREGISTRY_TOKEN) protects the remote API and peering snapshots. mbdeploy, mbserial and mbrelay have no way to present a token, so on a token-protected host remote deploy/serial/relay fail as unauthorized. The token is unset by default. Leave it that way unless you only need peer-to-peer sync.
2. macOS has no install-service. Use the launchd plists on Service on macOS.
3. Windows is not hardware-verified. The code paths exist and are unit-tested with fakes only.
4. Retired peers are never forgotten. A host that disappears is marked peer unreachable, never deleted. Troubleshooting shows how to purge one.
5. Recent fixes need a recent build. The per-user default paths and the no-default-route address fix landed on main after tag v0.20260924.2. Install from main or a newer tag.

Notes for whoever edits this next

• No machine specifics here, ever. Hostnames, IPs, users and per-host paths belong on the Robot Garage wiki. This wiki is world-readable.
• Each page starts with # Title, a > blurb line and a <!-- meta: --> comment. Update updated when you change a page, and add new pages to Home.md. Don't create a page named index.