Installing PlatformIO and Flashing Samovar for the First Time

Samovar supports two full installation methods: Arduino IDE and the PlatformIO-based configurator. This page describes PlatformIO. For Arduino IDE, use the section "Preparing the ESP32 for Upload".

The configurator lets you choose the board and equipment, save settings, flash the ESP32, upload LittleFS separately, and open the serial monitor. PlatformIO is a program that builds the source code and writes it to the board.

Windows 10/11 (64-bit only): download the latest Samovar release, unpack the archive to a simple path, for example C:\Samovar, connect the ESP32 with a USB cable that carries data, and double-click flash_windows.bat. The batch file checks Python and PlatformIO, installs them if necessary and opens the setup window.

macOS and Linux: open Terminal in the unpacked project folder and run:
chmod +x flash_macos_linux.sh
./flash_macos_linux.sh
The script checks Python with Tkinter and PlatformIO, installs them if necessary and opens the same configurator.

If macOS reports Operation not permitted or getcwd: cannot access parent directories: move the project folder from Downloads to your home folder and run the script there. Or allow Terminal access to the Downloads folder in "System Settings → Privacy & Security → Files and Folders", then fully restart Terminal.

On macOS, automatic installation of Python and Tkinter requires Homebrew. On Linux, apt, dnf and pacman are supported; the system may ask for the sudo password - the administrator password of the computer.

Working in the configurator: choose ESP32 DevKit, LILYGO or ESP32-S3, set the equipment and, if needed, the initial Wi-Fi credentials. The other parameters are arranged on the tabs "General" («Основные»), "Temperatures" («Температуры»), "Regulator" («Регулятор»), "BK" («БК»), "NBK" («НБК»), "Sensors" («Датчики»), "Pumps" («Насосы»), "Equipment" («Оборудование»), "Stepper motor" («Шаговый двигатель»), "Rectification" («Ректификация»), "Network" («Сеть») - these are the same directives that used to be edited in Samovar_ini.h. Press "Save settings" («Сохранить настройки»), then "Flash" («Прошить»). The settings are saved to the file user_config_override.h next to the project and are not overwritten when the sources are updated. The build and flashing log is at the bottom of the window.

For a new board, press "Upload LittleFS" («Загрузить LittleFS») separately. LittleFS is a memory area holding the web interface and user files. Uploading it again may replace programs, Lua files and logs, so the configurator asks for confirmation. Before uploading again, save the user files you need through the Samovar file editor.

The "Serial monitor" («Монитор порта») button opens a separate diagnostics window (speed 115200). If flashing stays on Connecting... for a long time, hold BOOT, briefly press RESET/EN and release BOOT after writing begins.

Update over Wi-Fi. Subsequent firmware updates can be done without a cable. Press "Refresh" («Обновить») next to the "Port or address" («Порт или адрес») field: besides COM ports, the list includes Samovar devices found on the network and the address the device reported after the "Get IP" («Получить IP») button in the serial monitor. You can also enter the address manually (for example 192.168.1.37 or samovar.local). Select the device instead of a COM port and press the same "Flash" or "Upload LittleFS". Conditions: the firmware on the device is built with "Allow update over Wi-Fi" («Разрешить обновление по Wi-Fi») enabled (the "Network" tab), the computer and Samovar are on the same network, and the firewall allows incoming connections for python.exe. Full flash erase, the serial monitor and "Reboot ESP" («Перезагрузить ESP») work only over USB.

The "File editor" («Редактор файлов») button opens the device files (programs, Lua scripts, web interface pages) right in the configurator, and "Open in browser" («Открыть в браузере») opens the Samovar web interface.

Manual method via PlatformIO:
pio run -e Samovar -t upload - ESP32 DevKit or LILYGO;
pio run -e Samovar_s3 -t upload - ESP32-S3;
pio run -e <environment> -t uploadfs - upload LittleFS;
pio run -e <environment> -t monitor - open the serial monitor.
Ready-made environments with a different regulator: Samovar_rmvk (RMVK), Samovar_sem (SEM_AVR), Samovar_no_power (no regulator, with UART); Samovar_lua - with Lua, Samovar_alarm_button - with the emergency button. User parameters for a manual build are set in user_config_override.h following the example in user_config_override.example.h.

After the first flashing, go on to connecting Samovar to Wi-Fi. If the network data is already set in the configurator and the board memory does not yet hold another network, the firmware tries to connect to it automatically.