# Samovar and safety

- Link: https://www.samovar-tool.ru/en/2021/03/26/samovar-and-safety/
- Published: 2021-03-26T10:03:00+03:00
- Author: kosoj.diy

The Samovar monitors process parameters and cuts off heating in an emergency when
readings go outside safe limits. All emergency events are recorded in the log and
sent to the mobile app and to the samovar-tool.ru website. This page describes the
full list of emergency scenarios in firmware 7.00 and the controller’s reaction 
to each of them.

## How the emergency protection works

All emergency checks are concentrated in the `alarm.h` module and are called from
the controller’s main loop by the `check_alarm()` function. When any check triggers,
an emergency stop reason is generated and `request_emergency_stop(reason)` is called.
The function turns off heating, stops the pumps, writes the reason to non-volatile
memory and sends a notification. The only way out of emergency mode is to reboot
the controller.

Emergency messages arrive:

 * on the main screen of the web interface;
 * in the Android and iOS mobile apps;
 * on the samovar-tool.ru website;
 * in the local log on the SD card or in LittleFS.

The message type is `ALARM_MSG` for emergencies and `WARNING_MSG` for warnings. 
Warnings do not stop the process but require the operator’s attention.

## Temperature limits

The temperature limits are set by constants in the `Samovar_ini.h` file. These values
are the threshold for an immediate emergency stop. For thresholds the user can configure(
for example, the distillation end temperature) there are separate fields in the 
settings.

 * `MAX_STEAM_TEMP = 98,8 °C` — the steam temperature limit. Exceeding it triggers
   an emergency stop with the reason “Maximum steam temperature exceeded”.
 * `MAX_WATER_TEMP = 75 °C` — the cooling water temperature limit. Exceeding it 
   triggers an emergency stop with the reason “Maximum water temperature exceeded”.
 * `ALARM_WATER_TEMP = 70 °C` — the critical water temperature (a warning). When
   it is reached, the controller lowers the power regulator voltage in steps of 
   5 V per iteration, pausing 30 seconds between steps. If lowering does not help
   and the temperature keeps rising, the `MAX_WATER_TEMP` emergency triggers.
 * `MAX_ACP_TEMP = 75 °C` — the limit temperature of the TCA (the sensor in the 
   atmospheric vent tube of the column). Exceeding it triggers an emergency stop.
 * `SamSetup.DistTemp` (configurable, 99.9 °C by default) — the temperature at which
   distillation and BC (the boiler-column mode) end. When it is reached, the controller
   tries to finish the program normally through the `SAMOVAR_POWER` command queue.
   If the queue is busy, the controller calls an emergency stop — it is better to
   take the emergency path than to leave the heating on until the boiler boils dry.

## Pressure

If an MPX5010DP pressure sensor is installed and a `MaxPressureValue` value is set
in the settings (0 by default — the check is off), the controller monitors the pressure
in the column. When the threshold is exceeded, an emergency stop occurs with the
reason “Maximum pressure exceeded!”. Once the pressure drops 5% below the threshold(
hysteresis), the emergency state is cleared automatically.

## Flooding sensor

If the “Use reflux level sensor” setting (`UseHLS`) is enabled and the sensor is
connected to the WHLS pin, the controller monitors the reflux level at the head 
of the column. If the sensor stays triggered for more than `WHLS_ALARM_TIME = 3 
seconds`:

 * the buzzer sounds and the notification “Flooding sensor triggered!” is sent;
 * if a power regulator is used, the controller lowers the voltage by one step (
   3% for SEM AVR, 1 × PWR_FACTOR for other regulators);
 * the next reaction is possible only after 40 seconds — the process is slow to 
   respond, and there is no point in lowering more often.

If the program is running at pre-flooding (line type C), the controller remembers
the current voltage as `prev_target_power_volt` and after `TIME_C / 5 minutes` returns
the voltage to the remembered value minus 0.5 step. If the sensor keeps triggering,
the lowering cycle repeats.

## Water flow

If a water flow sensor is installed and the “Use water flow control” setting (`UseWS`)
is enabled, the controller monitors for water flow in all modes that require cooling.
If the water flow is zero for `WF_ALARM_COUNT` polling cycles, `request_emergency_stop`
is called with the no-flow reason. This protects the column and the TCA from overheating
if the water is cut off or the pump fails.

## Temperature sensor failure

Each DS18B20 sensor has an `ErrCount` error counter, which is incremented on failed
read attempts (broken wire, no response). The `optional_sensor_failed` function 
considers a sensor failed if the readings are outside the 2.0–126.0 °C range or 
read errors keep repeating. On failure:

 * a notification such as “Steam sensor is not responding” / “Boiler sensor is not
   responding” / “Water sensor is not responding” / “TCA sensor is not responding”
   is sent, indicating the mode;
 * an emergency latch is engaged — heating stays off until the cause is eliminated;
 * the way out of the emergency is a controller reboot.

In addition, in Rectification mode the controller checks that the steam and boiler
sensors are assigned at all (the address is not 0xFF). If there is not a single 
sensor on the 1-Wire bus, the controller tries to turn off heating normally through
the command queue, and if the queue is busy, it goes into emergency mode.

## Emergency button

If the `ALARM_BTN_PIN` pin is defined in the board settings (by default GPIO 35 
on the classic ESP32 and GPIO 48 on the ESP32-S3), you can connect an emergency 
button or a water leak sensor that works by closing a contact. The contact is pulled
up to the supply voltage; when it is shorted to ground (FALLING), an interrupt fires,
and a separate `triggerEmergencyButton` task calls `request_emergency_stop` with
the reason “Emergency shutdown: the emergency button was pressed”.

Pin specifics:

 * on the classic ESP32, pins 34–39 are input-only with no internal pull-ups, so
   an external pull-up resistor to the supply voltage is required;
 * on the ESP32-S3, pin 48 has an internal pull-up, so no external one is needed.

The emergency button is disabled by default — to enable it, uncomment `#define USE_ALARM_BTN`
in `Samovar_pin.h` or set the pin through `user_config_override.h`. After it triggers,
the only way out of emergency mode is to reboot the controller.

## Power regulator protection

If the “Use regulator connection check” setting (`CheckPower`) is enabled and communication
with the power regulator is lost during operation, the controller shuts off heating
in an emergency. This protects against the case where the regulator has stopped 
responding (a broken UART link, loss of regulator power) while the heating remained
on.

## Task watchdogs

The controller’s FreeRTOS tasks (the regulator task, the SysTicker supervision task,
the stack watchdog) keep an eye on each other. If any of them does not respond for
longer than the allowed time:

 * the regulator task did not start — emergency stop “Regulator task is not running”;
 * the emergency button task did not start — emergency stop “Emergency button task
   is not running”;
 * critically low remaining stack of any task — emergency stop “Critically low remaining
   task stack …”;
 * the SysTicker supervision task hangs — emergency stop “SysTicker supervision 
   task has hung”.

## Emergency stop reasons

When any emergency check triggers, the reason is written to non-volatile memory (`
latched_emergency_stop_reason`) and can be read through the web interface and the
API. After the cause is eliminated, the operator clears emergency mode by rebooting
the controller.

Typical reasons the operator sees:

 * “Maximum steam / water / TCA temperature exceeded”;
 * “Maximum boiler temperature limit. Program completed.” (a normal completion);
 * “Maximum pressure exceeded!”;
 * “Steam sensor is not responding” / “Boiler sensor is not responding” / “Water
   sensor is not responding” / “TCA sensor is not responding”;
 * “Emergency shutdown: the emergency button was pressed”;
 * “No water flow”;
 * “Power regulator is not responding”;
 * “Critical water temperature! Water supply error” (a warning, stepwise power reduction).

## Where to find the settings

 * Temperature limits — `MAX_STEAM_TEMP`, `MAX_WATER_TEMP`, `MAX_ACP_TEMP`, `ALARM_WATER_TEMP`
   in `Samovar_ini.h`.
 * Distillation end temperature — `DistTemp` on the “Main” tab of the settings page.
 * Emergency pressure — `MaxPressureValue` on the “Main” tab.
 * Flooding sensor — the “Use reflux level sensor” setting on the “Main” tab and
   the WHLS pin in `Samovar_pin.h`.
 * Water flow sensor — the “Use water flow control” setting (`UseWS`) on the “Other”
   tab.
 * Emergency button — the `ALARM_BTN_PIN` pin and the `USE_ALARM_BTN` flag in `Samovar_pin.
   h`.
 * Power regulator check — the “Use regulator connection check” setting (`CheckPower`)
   on the “Other” tab.

### Like this:

Like Loading…

### _Related_
