Lazy-ESP32 usage guide

What you need

A Linux machine with Python 3, arduino-cli, and esptool installed, plus an ESP32 board on USB. The bundled install.sh script configures arduino-cli board URLs, installs pyserial, and adds a lazy_esp alias.

git clone https://github.com/pdev-labs/Lazy-ESP32.git
cd Lazy-ESP32
chmod +x install.sh
./install.sh

Basic workflow

Open a terminal in any folder containing a .ino sketch and run the toolkit. It auto-detects the sketch and the connected module, then offers flashing, compiling, recovery, and diagnostics from one menu.

Sketches compile in a temporary sandbox, so your project folder no longer needs to match the .ino filename.

python lazy_esp.py

Partitions and web assets

Use the partition manager before flashing web servers: it detects your chip's flash size and writes a custom partitions.csv with the app and LittleFS split you choose.

Switching partition sizes injects a clean build automatically, which avoids the classic undefined reference to app_main linker failure from stale cache.

The web assets converter turns a folder of HTML, CSS, and JS into a PROGMEM C++ header, then packs the data folder to LittleFS on flash.

Wireless and serial

OTA flashing pushes firmware over Wi-Fi with no cable. The serial monitor is a thin wrapper over pyserial for watching boot logs and crashes.

Back up the current firmware before experimental flashes, and use the board info option to confirm flash size before slicing partitions.

Full flash walkthrough

Start with the partition manager when the project serves files or logs: confirm the detected flash size, set the LittleFS share, and let the toolkit write partitions.csv with the flash size flag baked in.

Compile first without flashing to catch errors cheaply. Then flash over USB: the toolkit installs missing Arduino libraries, builds, writes bootloader plus firmware, and packs the data folder to LittleFS in one run.

Finish in the serial monitor. A clean boot log with no Guru Meditation errors means the partition table and firmware agree.

When flashing fails

Hold BOOT and tap RESET if the chip never enters download mode; some boards need the manual sequence every time.

Undefined reference to app_main after changing partitions means stale cache. Re-run through the partition manager so the clean flag is injected, then compile again.

Failed OTA usually means the board and computer are on different subnets or the firewall drops the return path. Flash over USB once to confirm the binary is good, then debug the network separately.