Samovar 7.00: the parameters can be set up either in the way described below for the Arduino IDE or through the configurator. The configurator saves the selected values in user_config_override.h, without changing the main Samovar_ini.h file. The firmware includes this file automatically, and its values override Samovar_ini.h; it can also be created by hand from the user_config_override.example.h template. In the configurator the parameters are arranged in sections (the "Section" («Раздел») list): Main («Основные»), Temperatures («Температуры»), Pumps («Насосы»), NBK («НБК»), Regulator («Регулятор»), Equipment («Оборудование»), Rectification («Ректификация»), BK («БК»), Network («Сеть»), Sensors («Датчики»), Stepper motor («Шаговый двигатель»).
To set up the sketch for your equipment configuration, open it in the Arduino IDE and make changes in the Samovar_ini.h file
In the Arduino IDE, open the file Samovar.ino from the folder ...\Documents\Arduino\Samovar\.
This loads into the Arduino IDE all the files located in the ..\Documents\Arduino\Samovar\ folder
In the top row of the Arduino IDE, find the Samovar_ini.h tab and start editing.
To keep a line of code from being compiled and therefore executed by Samovar, put the characters // in front of the line (comment it out).
And vice versa, to make a line run, remove the characters // (uncomment it)
It is recommended to exclude exactly those lines that relate to equipment you do not have, rather than switching off in a row all the parameters that you think you will not need.
For convenience, the code in the file is divided into blocks.
#define SAMOVAR_HOST "samovar"
Samovar's name on the network. The device is available under it as http://samovar.local (mDNS), and under the same name it is visible in the network ports of the Arduino IDE and the configurator when updating over WiFi. In the configurator: section "Main" («Основные»), "Device name on the network" («Имя устройства в сети»).
Block
//Selecting the ESP32 board in use
//********************************************
//#define BOARD DEVKIT
//#define BOARD LILYGO
//#define BOARD ESP32S3
//********************************************
Skip this. The firmware determines the board type by itself from the board selected in the Arduino IDE (DOIT ESP32 DEVKIT V1 / ESP32 Dev Module - DEVKIT, ESP32S3 Dev Module - ESP32S3), or from the board selected in the configurator. If nothing is detected, DEVKIT is used.
You can start editing values and enabling/disabling lines of code from this line:
//Water temperature at which the operator will be alerted
#define ALARM_WATER_TEMP 70
Here 70 is the temperature in degrees Celsius. When it is reached, a message about the critical coolant temperature (hereinafter CT) is issued. If a buzzer is used and event notification is enabled in the interface, Samovar also alerts with a sound. The alerts keep coming until the temperature drops. If you want the alert to come at a different temperature, change the number 70.
//Maximum water temperature at which the power will be turned off
#define MAX_WATER_TEMP 75
When the CT reaches 75°, Samovar gives the command to turn the heating off.
//Maximum steam temperature at which the power will be turned off
#define MAX_STEAM_TEMP 98.8
When the steam sensor temperature reaches 98.8°, Samovar gives the command to turn the heating off.
//Maximum temperature in the TCA at which the power will be turned off
#define MAX_ACP_TEMP 75
When the TCA sensor temperature reaches 75°, Samovar gives the command to turn the heating off.
(see also TCA sensor setpoint)
//Steam sensor temperature at which the column switches from boost mode to working mode, and in distillation mode, with a steam sensor installed, detects the start of boiling
#define CHANGE_POWER_MODE_STEAM_TEMP 39
When the steam sensor temperature (or the temperature of the upper sensor in the column section) reaches 39°, Samovar gives the regulator the "stop boost" command and sets on the regulator the voltage specified in the first line of the take-off program. In distillation mode, Samovar uses the same steam sensor temperature to detect the start of boiling. In the configurator: "Temperatures" («Температуры»), "Boost transition temperature, °C" («Температура перехода из разгона, °C»).
//Boiler sensor temperature at which the water supply valve opens and the water supply pump turns on
#define OPEN_VALVE_TANK_TEMP 77
At a boiler temperature of 77°, the command to open the water supply valve is given, the PWM control signal to turn on the pump is sent at the same time, and a message is sent to the operator that the water must be opened.
The message is sent in any case, even if neither a pump nor a valve is used, or the water is already open.
#define DELTA_T_CLOSE_VALVE 20
//The difference between the set water cooling T and the water T, down to which the pump will keep running after the distillation process ends in distillation and rectification modes. The value is in degrees C°, it can be changed. Disabling it is strongly discouraged. (for details see
here)
//Lower value (in percent) for the PWM regulator for the pump. Choose a value that ensures water flow
#define PWM_LOW_VALUE 10
As is well known, a motor needs a higher voltage to start than to keep running. This line sets the minimum possible value (in percent) at which the motor can keep the water supply pump running without stopping.
//Lower value (in percent) at which the PWM regulator for the pump starts working. Choose a value that is guaranteed to start the motor
#define PWM_START_VALUE 40
The value in % of the rated voltage at which the pump motor is guaranteed to start.
That is, if your pump (provided that it is already installed in the system and has liquid in it) reliably starts when a voltage of 6 volts or more is applied, and does not start at less, then with its rated voltage of 12 volts this is 50% of the rated value. So the number 40 must be replaced with 50.
//Correction for the servo rotation angle.
int8_t servoDelta[11] = {0, -2, -3, -4, -3, -2, 0, 0, 0, 0, -2};
Correction of the rotation angle of the take-off table servo for precise positioning. It is given in degrees. Each position is corrected individually. It does not depend on the correction of neighboring positions.
For example, if the rocker arm has "overshot" position No. 2 and we set minus 10°, this value (-10) does not need to be taken into account when correcting position No. 3.
//Difference between the target temperature and the current temperature (for Beer and sous-vide modes) until which heating will be at full power (in boost mode).
For Beer and sous-vide modes. The value is given in degrees Celsius. This parameter relates to the main heater. It means that heating is at full power as long as the difference between the actual temperature and the one set in the mashing program line is greater than 1°. As soon as the difference is less than or equal to the one specified in #define HEAT_DELTA, the regulator is told to reduce heating so as to reach the set temperature smoothly and/or not exceed it by much.
If you have a fairly powerful heater, increase the value so as not to "overshoot" the target temperature.
//If the difference between the target temperature and the current temperature (for Beer and sous-vide modes) is greater than the set one, then when a UART-controlled regulator is used, relay No. 4 additionally turns on the boost heating element; when the difference is smaller, the boost heating element turns off
#define ACCELERATION_HEATER_DELTA 4
For Beer and sous-vide modes. The value is given in degrees Celsius. The parameter relates exclusively to the additional heater.
If the boiler temperature is lower than the target (in this case by 4°), the additional heater turns on.
//Boiling temperature (for Beer mode)
#define BOILING_TEMP 98.9
For Beer and sous-vide modes. The value is given in degrees Celsius. The value is set manually and tells Samovar at what temperature on your equipment real boiling started in the boiler. The value
affects the operating algorithm of the main and additional heaters
//Default distillation end temperature
#define DEFAULT_DIST_TEMP 99.9
For distillation mode. The boiler temperature at which the run ends, if the distillation program does not set another value. In the configurator: "Temperatures" («Температуры»), "Distillation end temperature, °C" («Температура завершения дистилляции, °C»).
Settings for using Samovar subsystems
#define SAMOVAR_USE_BLYNK //use Blynk in the project
If you do not use Blynk, this line must be commented out with //.
#define BLYNK_SAMOVAR_TOOL "samovar-tool.ru" //use the free Blynk server samovar-tool.ru instead of the Blynk cloud
If you use a paid Blynk server rather than the server provided by the developer, the line must be commented out .
//#define USE_MQTT //send readings to your own MQTT broker To save logs to the cloud this parameter is not needed: if the device token is set in the settings and SAMOVAR_USE_BLYNK is enabled, Samovar's log and messages go to the samovar-tool.ru server on their own. Register on the www.samovar-tool.ru website and enter the device token when editing your profile; the logs will then be available on the site through the menu: User - Logs. More details in the section -
Logs and charts in the cloud.
USE_MQTT is a separate, optional sending of a shortened readings line to an arbitrary MQTT broker (without TLS, every 4 seconds during a process and every 5 seconds when idle). This line is not in Samovar_ini.h: the parameter is enabled in the configurator (section "Network" («Сеть»): "MQTT server" («Сервер MQTT»), "MQTT port" («Порт MQTT»), "MQTT user" («Пользователь MQTT»), "MQTT password" («Пароль MQTT»), "MQTT topic" («Топик MQTT»)) or in user_config_override.h, where MQTT_SERVER, MQTT_PORT, MQTT_USER, MQTT_PASSWORD and MQTT_TOPIC must be set; without them a build with USE_MQTT stops with an error.
Selecting the power regulator
In the file Samovar_ini.h the selection is made with ordinary lines:
#define SAMOVAR_USE_POWER
//#define KVIC_USE_9600
//#define SAMOVAR_USE_RMVK
//#define SAMOVAR_USE_SEM_AVR
When building with the Arduino IDE leave the lines as follows:
KVIC: change nothing. The SAMOVAR_USE_POWER line is already enabled in the original file, and the RMVK and SEM_AVR lines are commented out.
RMVK: uncomment only the line SAMOVAR_USE_RMVK. The firmware enables the necessary general regulator support automatically.
SEM_AVR: uncomment only the line SAMOVAR_USE_SEM_AVR. The firmware enables RMVK protocol support and general regulator support automatically.
Without a UART-controlled regulator: comment out SAMOVAR_USE_POWER, SAMOVAR_USE_RMVK and SAMOVAR_USE_SEM_AVR.
The KVIC_USE_9600 parameter applies only to KVIC: uncomment it for a regulator with a UART speed of 9600. If the regulator uses 38400, leave the line commented out.
When building with
PlatformIO you do not need to change these lines by hand: choose a ready-made environment,
Samovar,
Samovar_no_power,
Samovar_rmvk or
Samovar_sem (there are also
Samovar_s3 for the ESP32-S3 board,
Samovar_lua and
Samovar_alarm_button). The configurator chooses the environment by itself from the "Power regulator" («Регулятор мощности») group (Do not use («Не использовать») / KVIC / RMVK / SEM_AVR) and the board. Details are given in the instructions
Building and flashing with PlatformIO.
Parameters for the NBK
#define NBK_MULT_PAUSE_OVERFLOW 2 // number of inertias used as the pause after flooding
#define NBK_PUMP_LIMIT 30 // maximum wash pump capacity for Optimization, l/h
#define NBK_WORK_PRESSURE_RATIO 0.5f // working pressure ceiling = a fraction of the flooding pressure
#define NBK_PRESSURE_MARGIN 5 // mm Hg below the pressure at the moment of flooding when learning the ceiling
//#define USE_NBK_DELTA_PRESSURE // stillage temperature correction by the pressure in the stillage drain
//#define USE_NBK_END_BY_STEAM_RISE // finish NBK operation when the steam T has risen by NBK_END_STEAM_RISE relative to the minimum
#define NBK_END_STEAM_RISE 5.0f // steam T rise threshold (°C) for USE_NBK_END_BY_STEAM_RISE
Needed only for continuous wash column mode; in the configurator: section "NBK" («НБК»). If the NBK is not used, leave them as they are. More details in the section
NBK.
#define SAMOVAR_USE_POWER_START_TIME 2000 //delay before sending the boost command to the regulator. Ensures "cold" closing of the power circuit by the contactor.
To avoid an electric arc on the contactor's power contacts. After the "Turn on heating" («Включить нагрев») command, relay No. 1 operates and turns on the contactor, which in turn closes the power circuit to the heater. After the time set in milliseconds, the regulator supplies voltage.
#define LCD_RESET_PERIOD_MS 240000UL //period (ms) of the periodic re-initialization of the LCD display, 4 minutes
Protection against the display "freezing" on I2C. No need to change it. In the configurator: "Equipment" («Оборудование»), "Display reset period, ms" («Период сброса дисплея, мс»).
#define USE_WATERSENSOR //use the cooling water flow sensor. If used, then if there is no water for the set time Samovar turns the column heating off
The flow sensor works on the Hall sensor principle. If there is coolant flow, Samovar receives periodic pulses. If there are no pulses or they arrive too rarely, Samovar turns the heating off and sends an alert.
#define WF_CALIBRATION 98 //Value for the flow sensor F=98*Q(L/min); for a different sensor, set a different value.
Flow sensor correction. If 1 liter of water is passed through the sensor, 5880 pulses are received from it. In reality the number of pulses per 1 liter differs at different water flow rates. The correction can be made by changing the value 98.
#define WATER_FLOW_MIN_PULSES 7 //Flow is considered real if the number of pulses per cycle is not less than this threshold
Filters out single pulses of the flow sensor when the water is closed. If Samovar sees flow where there is none, increase the value; if it turns the heating off at a weak flow, decrease it. In the configurator: "Pumps" («Насосы»), "Minimum flow pulses" («Минимум импульсов потока»).
#define USE_HEAD_LEVEL_SENSOR //use the reflux level sensor in the head (P-N-P sensor). If used, when the sensor triggers, the power is reduced by 1*PWR_FACTOR (for KVIC: 1 V, for RMVK: 2 V; for SEM_AVR: by 3% of the current value)
Use a reflux level sensor whose output is a logic one when it triggers.
#define IGNORE_HEAD_LEVEL_SENSOR_SETTING //If the reflux sensor is used, ignore the command to disable the sensor in the WEB interface. (If you comment it out, a checkbox appears in the interface, on the Settings («Настройки») tab, with which you can enable or disable the use of the reflux sensor.)
//define USE_HEAD_LEVEL_SENSOR // use the reflux level sensor... is commented out, the sensor is not used, and it does not matter in what state (commented out or uncommented) the next line is.
If the line #define USE_HEAD_LEVEL_SENSOR is uncommented, the state of the next line is taken into account:
#define IGNORE_HEAD_LEVEL_SENSOR_SETTING - If it is uncommented, there is no checkbox for controlling the reflux sensor in the WEB interface. Accordingly, the sensor cannot be disabled from the WEB interface.
If //#define IGNORE_HEAD_LEVEL_SENSOR_SETTING is commented out, the use of the reflux level sensor can be quickly switched on and off (item 5) from the WEB interface.
//#define WHLS_HIGH_PULL //use an N-P-N liquid level sensor
Use a reflux level sensor whose output is a logic zero when it triggers.
#define USE_WATER_PUMP //use PWM control for the water pump and/or for switching on the stirrer for Beer mode
If the pump for automatically maintaining the CT is not used and the stirrer in Beer mode is not connected, the line must be commented out. In the configurator: "Pumps" («Насосы»), "Control the water pump or stirrer" («Управлять насосом воды или мешалкой»).
//#define USE_WATER_VALVE LOW //use valve control to adjust the water pressure
When a bypass valve is used, the line must be uncommented. The valve is connected in place of the pump. It works on the thermostat principle. If the temperature exceeds the set one, the valve opens; when the temperature falls below the set one, it closes. More details here.
If a normally closed valve is used on the bypass line, the value LOW must be replaced with HIGH.
If the CT is regulated manually or by some third-party device, both lines must be commented out.
//#define USE_ALARM_BTN //use the emergency button.
Pressing it stops the water supply and cuts off the power. You can use it by installing leak sensors (an unlimited number of devices with "dry contacts" connected in parallel is allowed), or an ordinary button (it can also be connected in parallel with the sensors)
#define USE_BODY_TEMP_AUTOSET //use automatic hearts T correction for the first hearts or pre-flooding take-off program after the heads, and also for the pre-flooding program if it comes before the second-to-last hearts or pre-flooding take-off program
In the standard Samovar 7.00 build this function is enabled. It cannot be commented out: the firmware enables USE_BODY_TEMP_AUTOSET forcibly (Samovar.h). In the configurator it is in the "Rectification" («Ректификация») section ("Hearts temperature auto-correction" («Автокоррекция температуры тела»)), and the rise limit BODY_TEMP_AUTOSET_MAX_RISE is there too (see below).
The take-off will not be paused provided that:
For the line Hearts («Тело»). If a Hearts line comes right after a Heads line and is followed by two Hearts or Pre-flooding lines in any combination.
For the line Pre-flooding («Предзахлеб»). If a Pre-flooding line is anywhere in the take-off program and is followed by two Hearts or Pre-flooding lines in any combination
//Choose which pressure sensor is used and leave only one line. The other lines must be commented out.
//#define USE_BMP180 //use the BMP180/BMP085 pressure sensor
//#define USE_BMP280 //use the BMP280 pressure sensor
//#define USE_BMP280_ALT //use the BMP280 pressure sensor with an alternative address
//#define USE_BME280 //use the BME280 pressure sensor
#define USE_BME680 //use the BME680 pressure sensor
Choose which atmospheric pressure sensor is used and leave only one line. The other lines must be commented out. If an atmospheric pressure sensor is not used, you can comment out all the lines. But then Samovar will not correct the boiling temperature depending on the atmospheric pressure.
#define USE_BTN //use the button
Use the universal button on Samovar. It is connected to the D39 output of the ESP32. A handy button, but if it is not used, it is better to disable it.
#define USE_UPDATE_OTA //use ArduinoOTA for updating over WiFi. Handy for debugging; during operation it puts extra load on the ESP32
If a serial wired connection is used to update the ESP32 sketch, this line can be commented out. Updating over WiFi will then be unavailable. When building with ESP32 core version 3.x, the firmware disables this parameter by itself. In the configurator: "Network" («Сеть»), "Allow update over Wi-Fi" («Разрешить обновление по Wi-Fi»).
//#define USE_EXPANDER 0x20 //use the PCF8575 port expander
//#define USE_ANALOG_EXPANDER 0x48 //use the PCF8591 analog port expander
//#define USE_LUA //use Lua for writing scripts to control Samovar and the port expander
//Selecting the type of pressure sensor used in the column. Only one type can be used.
//#define USE_PRESSURE_XGZ 32 //use the XGZP6897D pressure sensor (or similar). The value is the K parameter from the sensor's table
//#define USE_PRESSURE_1WIRE {0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x22, 0x55} //use a pressure sensor over 1Wire
//#define USE_PRESSURE_MPX //use the MPX5010D pressure sensor
Pressure sensor in the column (not to be confused with the atmospheric pressure sensor above). It is needed for the NBK and for monitoring the pressure in the column. Uncomment only one line; if two or three are uncommented, the MPX5010D is used. If there is no sensor, leave all three lines commented out. In the configurator: the "Column pressure sensor" («Датчик давления в колонне») group.
//#define USE_STEPPER_ACCELERATION //use smooth start and braking of the stepper motor
Turn on smooth acceleration of the take-off pump; it will also stop smoothly.
//#define STEPPER_REVERSE //reverse the stepper motor rotation direction
If you need the take-off pump motor (Nema17) to rotate in the other direction, the line must be uncommented.
//#define I2CStepperStepMl 16000 //number of steps per ml for the I2CStepper
Only when an external I2CStepper module is used. Sets the initial calibration of the take-off pump (steps per milliliter). In the configurator: "Stepper motor" («Шаговый двигатель»), "Steps per ml for I2CStepper" («Шагов на мл для I2CStepper»).
//#define COLUMN_WETTING //if a reflux level sensor is installed, at the start of rectification bring the column to pre-flooding to wet the packing
//#define WETTING_POWER 220 //regulator voltage/power (for SEM_AVR) when wetting the packing
Wetting the packing before rectification. Works only with the reflux level sensor (USE_HEAD_LEVEL_SENSOR): after boost, Samovar holds on the regulator the voltage of the first program line (if it is not set, 220 V; for SEM_AVR, WETTING_POWER), reduces it in steps down to 80% if necessary and waits for the reflux level sensor to trigger, for no more than 20 minutes. In the messages: "Column packing wetting started" («Начало смачивания насадки колонны») and "Column packing wetted successfully!" («Насадка колонны успешно смочена!»). In the configurator: "Rectification" («Ректификация»), "Wetting the packing before rectification" («Смачивание насадки перед ректификацией») and "Packing wetting power" («Мощность смачивания насадки»).
//#define NOT_USE_INTERFACE_UPDATE //do not update the interface on startup
Samovar compares the locally installed version of the interface with the version available remotely and, if they do not match, updates it.
This approach lets you keep files with your own developments in Samovar. A local update overwrites everything, while an update over the internet updates only the interface, and scripts and settings are kept.
For a new version you do not need to upload the interface; it updates automatically.
But, as it turned out, something has changed and this does not work for everyone.
If this parameter is uncommented, the interface will not be updated over the internet.
//#define KVIC_DEBUG //debug messages of the exchange with the KVIC regulator to the serial monitor
Needed only when troubleshooting communication with the regulator. In the configurator: "Regulator" («Регулятор»), "KVIC debug messages" («Отладочные сообщения KVIC»).
Rectification algorithm parameters
#define PAUSE_RESUME_HYSTERESIS_DELTA 0.07f //hysteresis (°C) between the pause entry threshold by steam/column section T and the exit threshold
#define PROGRAM_ROW_STOP_PAUSE_LIMIT 3 //number of stop pauses during the current program line after which the line's base speed is reduced automatically
#define PROGRAM_ROW_STOP_PAUSE_SPEED_CUT_PCT 10 //by how many % to reduce the line's base speed when PROGRAM_ROW_STOP_PAUSE_LIMIT is triggered
#define PROGRAM_DONE_AUTO_POWEROFF_MIN 30 //time (min) to hold the status "Program execution finished" («Выполнение программы завершено») (the pump is stopped, heating continues), after which it switches off automatically. 0 = switch off immediately
#define BODY_TEMP_AUTOSET_MAX_RISE 0.3f //limit (°C) of the automatic rise of the hearts T within one program line
The default values are chosen for a typical column; do not change them unless necessary. In the configurator: section "Rectification" («Ректификация»).
BK mode parameters
#define BK_STEAM_SETPOINT_MIN 30 //lower limit of the BK dephlegmator steam T setpoint (5th field of the program line), °C; 0 - water by hand
#define BK_STEAM_SETPOINT_MAX 100 //upper limit of the BK dephlegmator steam T setpoint, °C
#define BK_WATER_ADJUST_PERIOD_MS 60000 //BK water regulator step period, ms
#define BK_WATER_DEADBAND 0.2f //dead band (°C) around the BK steam setpoint
#define BK_WATER_PWM_STEP 30 //BK water PWM regulator step (out of 1023)
Setpoint limits and the step of automatic water regulation in wash column mode. In the configurator: section "BK" («БК»).
After editing the file, you must upload the sketch to the ESP32 again. To do this, click the arrow on the top panel of the Arduino IDE and wait for the upload to finish.
Your Samovar is ready to work.
Note.
From now on, when you install a new release, you do not have to edit Samovar_ini.h every time.
When updating through the Arduino IDE, compare the new and old Samovar_ini.h and transfer only your own values. Do not replace the new file entirely with the old one: a new release may have parameters without which the configuration would be incomplete. The configurator stores user differences separately in user_config_override.h.
It is better to edit the new file itself rather than add lines from the new code to the old one, to avoid accidental errors (see Updating the sketch).
For comparing and editing you can use special programs that can compare two different files, visually showing the differences between them.
Warning.
It is recommended to download the archive with the new Samovar release from this link. It will be a stable and tested version.
________________________________________________________________________________________________________________
* For developers. A description of the sketch sections and a block diagram are on
github.com
Other files and lines with explanations:
file Samovar_pin.h
Samovar 7.00: the TARGET_WATER_TEMP constant is no longer in this file. The water temperature maintained by the pump PWM regulator is taken in all modes (including the NBK) from the "Water sensor setpoint" («Уставка датчика воды») field on the
Settings - Temperature («Настройки - Температура») tab; if the field is empty, the firmware uses 48°. When the process has finished and the outlet water temperature becomes lower than the setpoint by DELTA_T_CLOSE_VALVE (20° by default, see above), Samovar stops the pump, gives the command to close the water valve and sends an alert that the water must be closed.
file pumppwm.h
define PUMP_PWM_FREQ 15
Minimum PWM frequency of the cooling pump, in hertz
