ESP-IDF export
The same design as an ESP-IDF project in C: Espressif's own framework, the panel on esp_lcd, components from the registry, built and flashed with idf.py - and nothing of Arduino in it.
ESP-IDF is the framework Espressif writes for its own chips, and the one the Arduino core for the ESP32 is built on. This export writes your design as a project for it directly: the screens are the same LVGL C the Arduino export writes, and everything around them - the panel, the touch panel, the buses, the sensors, the network - is written on ESP-IDF's own drivers instead of Arduino libraries.
It suits you if your firmware already lives in ESP-IDF, if you want the screens inside a
project of your own, or if you would rather have Espressif's drivers and
menuconfig than the Arduino layer. It does not suit you if your board is not an
Espressif chip, or if your design needs one of the few parts this export does not carry yet -
see what it covers.
Choosing it
The toolchain is picked when the project is made, in the setup wizard, and stays with it: choose ESP-IDF on the first step. The board list, the palette and the hardware pickers then offer what this export can build, and anything it cannot is greyed in its place with the reason on it - so nothing is refused at export time that you could not see while designing.
It cannot be changed afterwards. A design is built for one toolchain. If you picked the wrong one, start a new project - the wizard takes about twenty seconds.
Generating an ESP-IDF project is part of Pro. Choosing the target, designing, previewing, checking the design in the export dialog, saving and publishing are open to everyone; pressing Generate is what asks. A build that is refused costs nothing, and one that succeeds is metered as any other export - see Accounts and limits. A new ESP-IDF project starts from the starter on a Cheap Yellow Display, the Arduino starter made for this export.
What it covers
| Supported | Not yet | |
|---|---|---|
| MCU | ESP32, ESP32-S2, ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-P4 (its Wi-Fi through the ESP32-C6 beside it) | STM32 and RP2040, which are not Espressif's |
| Panel bus | SPI, quad SPI, 8- and 16-bit parallel, RGB (ESP32-S3 and P4), MIPI-DSI (ESP32-P4) and I2C | - |
| Panel | ILI9341, ILI9342, ILI9486, ILI9488, HX8357D, ST7735, ST7735S, ST7789, ST7796, GC9A01, GC9107, JD9853, SSD1306 and SH1106 OLEDs; RGB panels including the ST7262, EK9716, ST7701 and GC9503V with their makers' register loads; MIPI-DSI EK79007, JD9165, JD9365, ILI9881C, HX8394 and ST7701; quad SPI ST77916, ST77922, AXS15231B, SPD2010 and the CO5300, SH8601, RM67162 and RM690B0 AMOLEDs | ILI9481, NT35510, SSD1351, SSD1331, NV3041A, ILI9225, R61581, SSD1963 and RA8875 |
| Touch | XPT2046 and ADS7846 (calibrated on the device, as the Arduino sketch does), GT911, GT9271, FT6206, FT6236, FT5x06, FT3267, FT3168, CST816S, CST820, CST226SE, CST9217, CST3530, AXS5106L, and the touch built into the ST77922, SPD2010 and AXS15231B | CST328, TT21100, CHSC6540, TSC2007, STMPE610, NS2009 |
| Widgets | Every widget in the palette but one, the ready-made ones included: clock, weather, map, table, canvas, QR code, Wi-Fi setup, the camera view with its MJPEG stream, the video player, Bluetooth, the two-way radio, ESP-NOW data and more | The colour wheel, which LVGL 9 removed |
| Design | Every style property and state, events, actions, variables, formulas, bindings, automations, themes, translations, imported fonts, pictures and icons | A video player's AAC sound (the picture plays; the player here decodes MP3 and WAV); Stream to card; switching Wi-Fi on and off, or choosing its network, from the design; a Wi-Fi setup page in your own colours; noticing an SD card swapped while the board runs; wake words and spoken commands |
| Peripherals | Each a driver in C: BME280, BMP280, QMP6988, SCD4x, SEN66, MLX90614, SHT31, AHT20, BH1750, MCP9808, ADS1115, INA219, MAX17048, AXP2101, AXP192, MPU6050, ADXL345, QMI8658, DS3231, PCF85063, DS1302, HC-SR04, joystick, MAX6675, MAX31855, MCP3008, PCA9685, NeoPixel, SD cards (SPI and SDMMC), OBD-II on CAN, Modbus RTU and TCP, Ethernet, a DVP camera and an ESP32-P4's MIPI camera | VL53L0X |
| I/O expanders | All of them: CH422G, TCA9554, PCA9555, PCF8574, PCF8575, MCP23017, MCP23S17 and Waveshare's own | - |
| Network | Wi-Fi with setup by phone, web data, MQTT (with Home Assistant discovery), the clock, a web server with updates, Bluetooth LE on NimBLE, a Bluetooth speaker on Bluedroid, the player and the microphone | Home Assistant's own API, which is the ESPHome export's |
Built against ESP-IDF 5.5.5 and LVGL 9.4.0, and it builds with ESP-IDF 6.1 too. A design drawn for LVGL 8 is exported as LVGL 9 all the same. The same check the export dialog runs is behind the greyed items in the designer, so the lists above are what it will build, not an estimate.
Every file
| File | What it is |
|---|---|
CMakeLists.txt | The project, as idf.py expects it. |
sdkconfig.defaults | Flash size, PSRAM, the partition table, FreeRTOS's tick and the log level, read into a new sdkconfig the first time the target is set. After that idf.py menuconfig is where they change. |
partitions.csv | The partition table, from the layout on the Hardware tab. |
platformio.ini | The same project for PlatformIO, with framework = espidf. |
config/lv_conf.h | LVGL's settings: the widgets and fonts this design uses. |
main/main.c | The board: the lines it holds, the panel on esp_lcd, the touch panel, the backlight, and LVGL's task. |
main/idf_component.yml | LVGL and the panel's drivers from Espressif's component registry, each pinned to the release it was built with. The first build fetches them into managed_components/. |
main/src/ui/ | The screens, as the designer wrote them - the same files as the Arduino export's. |
main/src/ui/ui_events.c | The functions your events call. Written fresh by every export: keep your own copy, or put them in a file of your own. |
main/hardware.c | When the design has devices: the buses, the expanders, the inputs and outputs, and a driver in C for each part. |
main/app_logic.cpp | The design's variables, bindings and automations. |
main/lw_*.c, .cpp | When the design uses them: the network, the web server, Bluetooth, the camera and its stream, the video player, the player, the microphone, the two-way radio - the Arduino export's own modules, put in ESP-IDF's words. |
data/ | Pictures and files for the board's flash, made into a LittleFS image that idf.py flash writes with the program. |
README.md | The commands for this board, the panel's pins, and anything about this design worth knowing. |
Building and flashing
With ESP-IDF 5.5.5 or 6.1 installed and its environment set (export.sh or
export.ps1), from the project's folder:
idf.py set-target esp32s3
idf.py build
idf.py -p PORT flash monitorThe README names the right target for your board. The first build fetches the components
and takes a few minutes; later ones rebuild only what changed. If you use PlatformIO rather
than ESP-IDF's own tools, pio run -t upload builds the same project on the platform
the Arduino export pins, which carries the same ESP-IDF release.
LVGL runs in one task, lvgl_task in main.c, pinned to core 1
so that core 0 is the network's. Call LVGL from that task only; from a task of your own, take a
lock around it.
Where it differs from the Arduino export
| In the Arduino export | In the ESP-IDF export |
|---|---|
| The panel is driven by TFT_eSPI, LovyanGFX or GFX Library for Arduino | By esp_lcd, with Espressif's registry component for the controller where there is one, and otherwise the same start-up GFX Library for Arduino sends. |
| Sensors are read by their Arduino libraries | By drivers of ours in C, on i2c_master and spi_master, each checked against the Arduino library's results by a test rig. |
| Settings are kept with Preferences | In the same NVS entries Preferences used, so a board moved from one export to the other keeps its settings. |
| LVGL 8.3 or 9 | LVGL 9 only. |
| STM32 and RP2040 boards as well as Espressif's | Espressif's chips only. |
What is not here yet
A few parts the Arduino export drives through a library this one does not carry - the panels, touch controllers and the VL53L0X listed under what it covers. Each is greyed in the designer with its own sentence, and the Arduino export of the same design drives it.
Stream to card, and a video's AAC sound. Stream to card is written for the Arduino export and not ported yet. A video player's AAC soundtrack is left out, since the player here decodes MP3 and WAV: the picture still plays, on time.
Home Assistant's own API. That is the ESPHome export's. From this one the same things reach Home Assistant over MQTT, with discovery, or through its REST API with a web request.