The safety rules
This is the most important page in the guide. RISER controls heat in real buildings. If we get this wrong, people get cold, or worse. So we follow a set of rules that we never break. We back each rule with a test that must pass.
What is “safe state”?
Section titled “What is “safe state”?”Safe state does not mean “off.” It means the boiler goes back to its own built-in controls, and heat is still available. The boiler has simple controls of its own. If RISER steps back, those take over. So “safe” here means “warm, by the boiler’s own rules.”
The rules
Section titled “The rules”-
Safe state is the default. The agent sets the safe state when it starts up, before it does anything else. It also sets it when it shuts down, and any time something goes wrong.
-
Any problem forces safe state. A crash, a frozen program, a power loss, or a sensor reading that is too high all force the safe state right away.
-
The watchdog is real. A watchdog is a timer. The control loop must “pet” the timer every healthy cycle. If the program freezes and forgets to pet it, the watchdog forces the safe state.
-
Losing the cloud never changes heat. If the internet drops, that is not a problem to the agent. The boiler keeps running on its last good settings. Telemetry waits on the controller and is sent later.
-
Commands are checked before they run. The cloud can send a command, like “turn the boiler on.” The agent checks it against the local safety rules first. If the command is unsafe, the agent says no, writes it down, and changes nothing. The cloud cannot override safety.
-
The agent never switches high voltage. It only flips a small, low-voltage switch (the relay). That switch tells the boiler’s own circuit to run or stop. This keeps the wiring safe.
Why we test these
Section titled “Why we test these”Rules are only words until you prove them. So each rule has a test in agent/tests/safety/. The
tests use the fake boiler and push it into bad situations on purpose. For example, one test makes the
temperature too high and checks that the agent forces the safe state.
If you ever change the control code, run these tests:
.venv/bin/pytest agent/tests/safety -vAll six must pass. If even one fails, stop and fix it before you go on. Never make a safety test “pass” by faking it. That defeats the whole point.