Roastwarden

Documentation

Installing Roastwarden, connecting a roaster, and every feature from charge to bag label. New here? Start with Install, then the User guide.

Guides

  • InstallInstall Roastwarden from scratch: one container on a Raspberry Pi or any Linux host, the built-in MQTT broker, and the first sign-in.
  • User guideEvery part of Roastwarden from the roaster's side: a roast from charge to drop, history, profiles, beans, labels, reports, roasters and settings.
  • Connect your roasterWhat Roastwarden expects of a roaster on one page, how to pick a transport, and a tested example roaster for each: MQTT, Modbus TCP, TC4 serial and WebSocket.
  • Add a roasterAdding 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.
  • Roasters from Artisan's cataloguePick a machine from Artisan's catalogue and get its connection, register map and channels set up: Modbus, Fuji PIDs, TC4, WebSocket and MQTT machines.
  • Running itDay-to-day operation: the one container, the built-in broker, upgrades that wait for the roaster, label fonts, nightly backups and a checked restore.
  • The roast CLIroast: every operation of the server from a shell, for people, scripts and agents, with tokens, approvals and exit codes.

Roasting

  • ProfilesSeed profiles by roaster kind, Artisan .alog import and export, and sharing a profile by a public link that another server imports.
  • Profile driveThe server drives a roast from a profile: setpoint, heater and fan curves, events by time or temperature, and auto DROP.
  • Roast sequenceWhat CHARGE, DROP and cancel do to the roaster: heater and fan at charge, cooling after drop.
  • Alarms and auto eventsAlarms on temperature, rate of rise and time with actions and notifications; automatic turning point, dry end and DROP; Artisan .alrm files.
  • Fan assistOn a fluid bed, the fan takes over part of the temperature control when the heater runs out of headroom late in the roast.
  • PredictionThe roaster's own model, fitted from its roasts: bean temperature two minutes ahead, first crack and DROP, RoR crash and flick warnings, and how good it is.
  • Roast guidanceThe numbers read for you: development, weight loss and colour against cited references and the roaster's own history, at most three lines per roast.
  • Roast review and compareA roast's numbers in one read, and two or more roasts compared phase by phase.
  • StatisticsConsistency bands, area under the curve per phase, and the rate of rise slope from first crack to drop.
  • A new bean's first roastStarting a new coffee: what to expect from its first roast on your roaster, what to watch, and what to change for the next one.
  • CuppingThe SCA cupping form and its score, kept with the roast.

Coffee and paper

  • Green coffeePurchases and costs, adding a coffee from a supplier's link, the shopping list and its cart links, and orders recorded from their receipts.
  • Planned roasts and batchesA queue of planned roasts, batch numbers per roaster, and green stock drawn down by each roast.
  • Roasted coffeeEach roast's lot: resting, ready, used and given away.
  • Bag labelsBag labels designed in Typst, printed over IPP, with a public page per roast behind the QR code.
  • PDF reportsA roast, two roasts compared, a profile, a coffee, a period, the plan, inventory and purchases as PDF reports.

How it works

  • Roaster kind and control levelEach roaster's kind, outputs and control level, and the one gate in the server that every command passes.
  • ControlWhere the bean temperature loop runs, the device contract, leases and the safe state, approvals.
  • AutotuneThe server's autotune: a relay experiment, a fitted model of the roaster, and PI gains designed from it.
  • Mapping a device's own namesA device keeps its own field names, units, topics and command syntax; a connection maps them.
  • Extra channelsDeclared channels: an exhaust probe or a TC4's third channel, kept with each roast, drawn, used in alarms and exported to Artisan.
  • Wire formatsEvery transport's messages in full: MQTT topics and payloads, WebSocket, Modbus registers, TC4 serial lines.
  • Phidgets boardsA Phidgets temperature board through Phidgets' network server, the protocol spoken without their library.
  • Simulated roastersThe virtual fluid bed and the simulated gas drum in the server, for trying control without a roaster.
  • Modules and first runA home install shows what a home roaster uses; Enthusiast and Roastery presets switch on the rest. Weight units, traceability.

Connections

  • Artisan as a screenArtisan reads Roastwarden over its Modbus slave, with a setup file to load.
  • Home AssistantEach roaster as a Home Assistant device through MQTT discovery, read only.
  • NotificationsAlarm and system notifications through ntfy, Gotify, webhooks and Web Push.
  • Push and the installed appAlarms that reach a locked phone, and installing the dashboard as an app.
  • AgentsAgents are first class: the roast CLI and an Agent Skill, scoped tokens, approvals and the audit log.
  • Live data WebSocketThe dashboard's live data stream: CBOR frames, subscribe and resume.

Project

  • SecurityThe owner key, sign-in, tokens, the broker's users, and how to report a vulnerability.
  • Support bundleOne file to attach to a bug report, with secrets removed.
  • ContributingSign-off, the licence grant and how changes are made.