Configuration#

dotbot reads one optional config file so you don’t retype the same flags on every command. A value can come from a flag, an environment variable, the file, or a built-in default - the resolver merges them through a single precedence chain, so the file is just a place to park the defaults you’d otherwise pass by hand.

You never need a config file: every setting also has a flag and an env var. The file just makes a repeated setup (a broker URL, a board name, a swarm id) the default.

Create one with dotbot config init (it writes a minimal ./dotbot.toml); pass --conn / --swarm-id to pre-fill the two most common keys:

dotbot config init --conn mqtts://broker:8883 --swarm-id 1234

This page is the file-format reference. For the config command itself (init / show / path), see dotbot config.

Where the file comes from#

dotbot looks in this order and uses the first hit:

Order	Source	How
1	`-c PATH` / `--config PATH`	An explicit path on the command line.
2	`DOTBOT_CONFIG`	An explicit path in the environment.
3	`./dotbot.toml`	A `dotbot.toml` in the current directory (the cwd only - parent directories are not searched).
4	`~/.dotbot/config.toml`	Your user-level file.
5	(none)	Built-in defaults only.

A dotbot.toml in your working directory (3) takes precedence over your personal file (4), so a per-experiment config wins while you work in that directory. Discovery looks only at the cwd - it does not walk up to parent directories, so the active config is always unambiguous.

~/.dotbot/config.toml (4) is the per-machine fallback for settings you set once and want everywhere - typically [fw].segger_dir, since the SES install path rarely changes. Per-project settings like [fw].firmware_repo belong in the project’s ./dotbot.toml instead. Every command, including dotbot fw, reads through this same resolver.

Precedence#

For any single setting, the highest-priority source that has a value wins:

CLI flag  >  env DOTBOT_<SECTION>_<KEY> (then shared DOTBOT_<KEY>)
          >  file: section value > selected deployment > top-level
          >  built-in default

Inside the file, a key set in its own section table beats the same key on the selected deployment, which beats a shared top-level key.

Worked example - resolving the controller’s broker URL (conn):

Source	Value	Wins?
`--conn mqtts://cli:8883` flag	`mqtts://cli:8883`	yes, flag is highest
`DOTBOT_RUN_CONN` env	`mqtts://env:8883`	only if no flag
`[run] conn` in the file	`mqtts://run:8883`	only if no flag/env
`[deployment.inria] conn` (selected)	`mqtts://inria:8883`	only if `[run]` has no `conn`
top-level `conn`	`mqtts://shared:8883`	only if nothing above is set
built-in default	-	last resort

Env-var names are mechanical: a section key becomes DOTBOT_<SECTION>_<KEY> (e.g. DOTBOT_FW_BOARD, DOTBOT_RUN_CONN), and a shared top-level key becomes DOTBOT_<KEY> (e.g. DOTBOT_CONN, DOTBOT_SWARM_ID). A sectioned key also accepts the shared DOTBOT_<KEY> form as a fallback.

Top-level (shared) keys#

Set once at the top of the file; any section or deployment can override them.

Key	Meaning
`conn`	Default connection string (`mqtts://host:port`, a serial path, or `simulator`).
`swarm_id`	Swarm id selecting the MQTT topic namespace.
`log_level`	Logging verbosity.
`artifacts_dir`	Where firmware artifacts are read/written.
`default_deployment`	Name of the deployment to select when neither `--deployment` nor `DOTBOT_DEPLOYMENT` is given.

Section tables#

The four tables mirror the four CLI namespaces (fw / device / swarm / run); a section key is the per-namespace default for the matching flag.

[fw] - firmware-artifact builds (dotbot fw):

Key	Meaning
`board`	Target board, e.g. `dotbot-v3`.
`sandbox`	Build TrustZone sandbox apps (`.bin`) instead of bare apps.
`build_config`	`Debug` or `Release`.
`segger_dir`	SEGGER Embedded Studio install path.
`firmware_repo`	Path to your `DotBot-firmware` clone (so `fw build`/`artifacts` find it without `cd` or `DOTBOT_FIRMWARE_REPO`).

[device] - one cabled device (dotbot device):

Key	Meaning
`board`	Target board for flashing.
`sn_starting_digits`	J-Link serial-number prefix selecting which probe.
`build_config`	`Debug` or `Release`.

[swarm] - the fleet over the air (dotbot swarm):

Key	Meaning
`conn`	Connection string for the fleet link.
`swarm_id`	Swarm id (topic namespace).
`devices`	Device selection for fleet operations.

[run] plus [run.controller] and [run.gateway] - host processes (dotbot run):

Key	Meaning
`conn`	Connection string for `dotbot run`.
`swarm_id`	Swarm id (topic namespace).
`[run.controller] http_port`	REST/WebSocket port (default 8000).
`[run.controller] map_size`	Controller map size.
`[run.controller] background_map`	Background map image.
`[run.controller] log_output`	Log output path.
`[run.controller] csv_data_output`	CSV data output path.
`[run.controller] webbrowser`	Open the web UI on start.
`[run.controller] gw_address`	Gateway address.
`[run.controller] simulator_init_state`	Initial simulator state.
`[run.gateway] serial_port`	Gateway serial port.
`[run.gateway] mqtt`	Gateway MQTT connection string.

Unknown keys are rejected: a typo in a section or key name fails loud rather than being silently ignored.

What a deployment is#

A deployment here means one physical deployment - one set of real DotBots behind one broker, in one place (e.g. the ~100-bot setup at Inria Paris, or a 1000-bot campaign). You define each one as a [deployment.<name>] table and select it; you do not edit the file to switch between them.

Select the active deployment with, in precedence order, --deployment NAME, the DOTBOT_DEPLOYMENT env var, or the top-level default_deployment. The selected deployment’s keys slot into the file layer (above top-level, below sections), so an explicit flag or env var still overrides it. Selecting a name with no matching [deployment.<name>] table is an error that lists the defined deployments.

A deployment is not the simulator. To drive simulated bots, set the connection to simulator (--conn simulator, or conn = "simulator"); that is a connection kind, not a deployment.

A [deployment.<name>] table holds the deployment-binding keys plus descriptive metadata:

Key	Meaning
`conn`	Broker / link for this deployment.
`swarm_id`	Swarm id for this deployment.
`serial_port`	Default serial port for this deployment.
`location`	Descriptive label (shown by `dotbot deployment list`).
`bots`	Descriptive bot count.

Managing deployments#

The dotbot deployment group inspects, switches, and fetches deployments:

Command	Does
`dotbot deployment list`	List defined deployments; mark the active one.
`dotbot deployment show NAME`	Print one deployment’s fields.
`dotbot deployment use NAME`	Set NAME as `default_deployment`, written into your config file (comments preserved).
`dotbot deployment fetch [SOURCE]`	Fetch published deployments and merge them into your config.

fetch takes a URL or a local file holding [deployment.*] tables; with no SOURCE it uses the built-in DotBots registry. It merges: a same-named deployment is replaced (you are asked first), and everything else in the file (other deployments, sections, comments) is left intact. Like dotbot fw fetch, it only acquires the deployment - select it afterwards with dotbot deployment use or --deployment. Useful flags: --into project (write the nearest dotbot.toml instead of ~/.dotbot/config.toml), --dry-run, and --yes.

Because MQTT credentials are env-only (below), a published deployment file is not secret - it carries only the broker URL, swarm id, and descriptive labels.

MQTT credentials are env-only#

MQTT username and password are read only from the environment:

export DOTBOT_MQTT_USER=alice
export DOTBOT_MQTT_PASS=…

They are never file keys - don’t put them in dotbot.toml, and don’t commit them. Keep the broker URL in the file and the credentials in your environment (or a secret manager).

Inspecting the resolved config#

Two helpers show what dotbot actually resolved, so you don’t have to trace the precedence chain by hand:

Command	Shows
`dotbot config show`	The merged, effective config and which file (if any) it came from.
`dotbot deployment list`	The defined deployments, their metadata, and which one is selected.

Full example#

An annotated dotbot.toml exercising every layer:

# Top-level shared keys: every section and deployment inherits these unless it
# sets its own value.
default_deployment = "inria"                 # used when --deployment / DOTBOT_DEPLOYMENT unset
conn            = "mqtts://broker.local:8883"
swarm_id        = "0001"
log_level       = "info"
artifacts_dir   = "./artifacts"

# A physical deployment. Select it with `--deployment inria`, DOTBOT_DEPLOYMENT, or
# default_deployment above - don't edit this table to switch deployments.
[deployment.inria]
conn        = "mqtts://broker.inria.fr:8883"
swarm_id    = "0001"
serial_port = "/dev/ttyACM0"
location    = "Inria Paris"               # descriptive, for `dotbot deployment list`
bots        = 100                          # descriptive

[deployment.limerick]
conn     = "mqtts://broker.limerick:8883"
swarm_id = "0002"
location = "Limerick campaign"
bots     = 725

# Firmware-artifact builds (dotbot fw).
[fw]
board        = "dotbot-v3"
sandbox      = false
build_config = "Release"
# segger_dir = "/Applications/SEGGER/SEGGER Embedded Studio 8.22a"

# One cabled device (dotbot device).
[device]
board              = "dotbot-v3"
sn_starting_digits = "77"                  # J-Link serial prefix
build_config       = "Release"

# The fleet over the air (dotbot swarm).
[swarm]
swarm_id = "0001"

# Host-side processes (dotbot run).
[run]
conn = "mqtts://broker.local:8883"

[run.controller]
http_port      = 8000
webbrowser     = true
# background_map = "./map.png"

[run.gateway]
serial_port = "/dev/ttyACM0"

# Note: MQTT credentials are env-only - DOTBOT_MQTT_USER / DOTBOT_MQTT_PASS.
# Never a file key.