Samovar and safety

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.