Guides

Add a roaster

Adding a roaster in the dashboard or with roast roaster add, map and check: the connection, the mapping of its own names, and the conformance check.

Adding a roaster is configuration, not code: a connection (how Roastwarden reads it), a mapping when the device uses its own field names, a kind, and its outputs and channels. Then one check says whether it reads right. A roaster is always added at control off: it is logged and sent nothing until you switch control on (roaster kind and control level). What a roaster has to send to be logged or controlled is on connect your roaster.

In the dashboard

Roasters → Add roaster has four steps:

Roaster: Name, ID and Kind. A known machine? searches Artisan's machine catalogue, or opens an .aset file saved from Artisan, and fills in the rest (roasters from Artisan's catalogue).
Connection: Wi-Fi (MQTT), USB thermocouple board (TC4), Phidgets temperature board, Controller on RS-485 (Modbus RTU), Controller on the network (Modbus TCP) or WebSocket. A Modbus roaster's registers are listed here, each with its role. Save and check saves the roaster at control off.
Check ("Does it read?"): the check, live every 3 s. If readings are missing or wrong, Map its fields opens the mapping: a row per field, the newest message the roaster sent, and what each field becomes. If nothing arrives, Test the connection.
Control ("What may Roastwarden send it?"): Off · logs only, Manual or Full. Leave it off until the check passes.

A roaster that is already sending on MQTT shows under Roasters → Found, not added yet. Nothing is sent to it; Set up opens Add roaster with it filled in.

Later, on the roaster's own page: Overview → a connection's Mapping (or for Modbus, Register Map → Edit), the Check tab, and Control → Setup for kind, outputs and channels.

From the command line

add and map need an admin token; map --try and check only read.

roast roaster add <id> --transport mqtt|websocket|modbus_tcp|modbus_rtu|serial_tc4|phidget22
    [--name …] [--kind fluid_bed_electric|drum_electric|drum_gas|logger|other]
    [--topic-prefix … --telemetry-topic …]           # mqtt
    [--device-url ws://…]                            # websocket
    [--host … --port … --unit-id …]                  # modbus_tcp
    [--port /dev/ttyUSB0 --baud … --parity …]        # modbus_rtu, serial_tc4
    [--preset stock-aartisan|tasmota|esphome|artisan-websocket]
roast roaster map <id> --field bt=data.BT --field et=data.ET [--units F] --try
roast roaster map <id> --field bt=data.BT --field et=data.ET [--units F]
roast roaster check <id>

The loop is map --try until the values look right, then map to save, then check. A preset fills a common device's defaults:

Preset	Fills in
`stock-aartisan`	a TC4 board running stock aArtisan: active channels only, ET on channel 1, BT on 2
`tasmota`	the telemetry topic `tele/<id>/SENSOR`, BT from `MAX31855.Temperature`
`esphome`	BT and ET each on its own sensor topic (`<id>/sensor/bean_temperature/state`, `…/environment_temperature/state`)
`artisan-websocket`	Artisan's WebSocket protocol: the `getData` request every second, BT and ET from `data.BT`, `data.ET`

add on a roaster found streaming on MQTT sets it up in place under its own id. add never raises control: roast roaster control <id> manual asks the owner. The full flags are in the roast command reference; the mapping is on mapping a device's own names.

The check

Roasters → the roaster → Check, or roast roaster check <id> (exit 0 ok, 1 warn or fail). Each line is ok, warn or fail; the verdict is the worst.

Line	Passes when
rate	0.5–4 samples a second over the last 30 s, evenly spaced
bt_et	BT present and within −10–300 °C; ET present (missing ET only warns)
units	at idle (heater off) both probes read room temperature, 5–45 °C; 50–115 suggests °F (`--units F`)
outputs	each declared output (heater, fan, drum, damper) is in the readings
channels	each declared channel is in the readings
caps	always ok: what the roaster says it can do, or that it said nothing
control	always ok: the control level and what it allows

Saving a Modbus register map restarts its polling, so the rate can warn for the next 30 s: check again.

The write check

Once control is manual or full, run the write check once with the roaster cold: Check → Run the write check, or roast roaster check <id> --write. It takes the owner key, a heater declared, BT below 50 °C, no roast open and the roaster's own PID not in auto. It sends heater 10 %, waits up to 5 s for the roaster to report it, sends emergency stop, and waits up to 5 s for the heater to read 0. It always ends with emergency stop, also after a timeout or an error.

To practise, the simulated gas drum is set up through this same path: switch it on under Roasters → Simulator and open its Check tab (simulated roasters).