# esp32-c3-mini: an LVGL watch interface for small ESP32 boards > esp32-c3-mini is a demo LVGL watch project for the ESP32-C3 mini 240 by 240 touch board, built around a clock face, weather, notifications, settings, games and navigation screens. The genuinely interesting parts are the two watchface mechanisms, the fact that the whole UI also builds natively with SDL, and the Chronos phone app that feeds it data over BLE. **fbiego/esp32-c3-mini** — LVGL UI for ESP32 C3 mini 240*240 board (ESP32-2424S012) - Repository: https://github.com/fbiego/esp32-c3-mini - Website: https://chronos.ke/c3-ui - Stars: 546 · Forks: 150 - Language: C - License: MIT - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/fbiego-esp32-c3-mini ## A watch interface, not a widget library esp32-c3-mini is described as a demo LVGL watch project for the ESP32 C3 mini 240 by 240 touch display development board, and it can also be built natively to test the LVGL UI. The project is written in C, licensed MIT, and the default branch is main with the last push on 2026-10-08. The recent releases are v6.3.0 from 2026-03-15, v6.1.0 from 2026-03-07 and v6.0.0 from 2025-04-19. The scope is a complete watch shell rather than a set of reusable widgets, and the screen list in the README is the best description of what is actually built. There is a Time screen with time, date, day, weather icon and temperature plus custom watchfaces, a Weather screen with city, icon, temperature, update time, a one week forecast of day, icon and temperature and an hourly forecast with wind, a Notifications screen with icon, time and text, a list of ten notifications and an incoming call state, and a Settings screen with brightness, timeout, battery and about. The Control screen covers music control, find phone, Bluetooth state and camera capture. There are also screens for QR codes and contacts, games described as Simon Says and Racing with a note that they need to be enabled, and a Navigation screen whose purpose is stated plainly as getting Google Maps navigation instructions onto the ESP32. The last item on that list is the extensibility point. The README points at a sample directory for creating custom apps with LVGL, so the project is structured as a shell with a sample showing how to add a screen of your own, not as a fixed application. ## Two watchface mechanisms, and why they differ The watchface section is the most substantive part of the documentation, because it describes two fundamentally different ways to get a custom face onto the device. The first is external precompiled binary watchfaces. These are binary files converted into LVGL code and compiled along with the main code, with the list in the face README. The consequence is stated without hedging: to add or remove these watchfaces you need to recompile and flash the firmware. The README points at a separate project, esp32-lvgl-watchface, for the details of converting watchfaces from binary to LVGL code, and notes that links to pre-built binary watchfaces are included. Enabling them happens in app_hal.h according to your build platform. The warning attached to this route is about flash size. The ESP32's flash is small, the compiled-in faces consume it, and the advice is to prioritise compiling only your favourite watchfaces. That is a real constraint rather than a caveat, because a watch face is a full screen of graphical assets, and each one compiled in eats into the flash you need for everything else. The second mechanism is external installable binary watchfaces, and here the documentation is markedly more cautious. Custom watchfaces work on LVGL 8, and there is a branch for it, while work for LVGL 9 is marked as a work in progress. You need sufficient storage space on the ESP32 flash, and using the FFAT partition is recommended. The feature is flagged as experimental and may not work reliably, with the note that the partition must be mounted successfully for proper functionality, and there is a specific warning that this has issues running on the ESP32 C3 Mini due to smaller SRAM size and is not ported to LVGL 9 yet. So the two routes trade compile time for runtime risk. Precompiled faces are reliable because they are part of the firmware image, and installable faces avoid the recompile at the cost of a feature the README says may not work at all on the smallest board in the list. ## Native builds, PlatformIO, and the web flasher Three ways to get the UI onto a device, and the native one is the one that changes how you work on the project. The build environment is selected in platformio.ini by uncommenting only one default_envs entry, which is the only configuration instruction the README gives for building. When building for native you need SDL configured for your platform, following the instructions in the LVGL platformio repository, and the README warns that the SDL path might be different depending on your configuration and that you will need to update platformio.ini accordingly. That native build is the useful part for a developer. It lets you run the whole watch interface on a desktop, with a mouse and a window, and iterate on a screen in seconds rather than flashing a board and waiting for a reboot. The README also ships prebuilt native applications in the test folder, and notes that you might still require SDL installed before running them. There are also binary files for various boards. For hardware, the README points at a web flasher for ESP32 boards, with the tool available at the project page on chronos.ke under the install anchor, so the first flash does not need a local toolchain. The repository layout supports the three-way split. The hal/ directory holds the hardware abstraction layer, include/ and lib/ the headers and libraries, src/ the application code, and there are separate partition files: partitions.csv, partitions_8M.csv and partitions_16M.csv. Those three files are worth noticing, since the flash layout is the thing that determines whether the installable watchface feature has anywhere to live. There is also a scripts/ directory, a tools/ directory, a screengrabs/ directory, a support/ directory, and a DEVELOPER_NOTES.txt at the root. ## The board list, and what the hardware implies The supported boards section is a list of thirteen specific products, and reading it tells you which hardware combinations are actually exercised. The 240 by 240 square group includes the CrowPanel ESP32 Display-1.28(R), the M5 Stack Dial, the ESP32 C3 Mini 1.28, and the Waveshare S3 1.28. There are Waveshare boards at 240x280, the S3 1.69 and the RP2040 at both sizes, which is worth noting because the RP2040 entries mean the same UI is expected to run on a non-ESP32 microcontroller, with the board-specific parts isolated behind the hal/ directory. The larger and denser group is the 466 by 466 round AMOLED panels, with the Viewe SmartRing AMOLED 1.8, the Viewe Touch Knob AMOLED 1.5, the Viewe S3 AMOLED 1.5, the Viewe Echo Ear 1.85 at 360 by 360, and the Waveshare S3 1.75 AMOLED. The Waveshare S3 2.06 at 410x502 is also listed. The repository holds boards.png and boards_2.png alongside the list, which is the practical form of this information: a picture of which board maps to which configuration. The hardware spread explains a design decision in the software. A 240 by 240 round screen and a 410 by 502 rectangular one cannot share a fixed layout, so the display geometry has to be a per-board setting rather than a constant, and the same applies to input, since some of these panels are touch and the round AMOLED ones are described with touch as well. The hal/ layer and the partition variants are the two places where that variation is absorbed. There is also a video linked in the README of the C3 UI on a 466 by 466 AMOLED, which is the largest panel in the list, so the project is not only exercised on the smallest board it supports. ## The Chronos app, and BLE as the data channel The README is explicit that the Chronos app is needed for additional functions on the ESP32 hardware, and the functions list is what a phone can do that a watch cannot. Communication with the app runs over BLE, handled by the ChronosESP32 library, whose source is a separate repository. The synchronised items are time, notifications and call alerts, weather information, QR links and contacts, music control with find phone and camera, and navigation instructions. The one crossed-out entry is installing additional watchfaces, which is marked as LVGL 9 work in progress, matching the same warning that appears in the watchface section. The division of labour here is a sensible one. Weather, notifications, QR codes and navigation all originate on a phone, and pushing them over BLE keeps the watch from needing a network connection, and keeps the data model in one place on the device that owns the accounts. Time synchronisation is the simplest case in the list and the one that removes a whole class of bug, because a watch with a drifting RTC is a bad watch. The navigation entry is the one that has no obvious alternative, and it is the only screen in the project that depends on a third party service, since the Google Maps instructions have to come from somewhere. The README lists it as a screen among the others rather than describing the mechanism, so how the instructions are fetched and pushed is not something a reader can determine from this documentation. ## Where this project is the wrong base Three cases point elsewhere. The first is a product that needs the installable watchface feature on a small board. The README says the feature is experimental, that it may not work 100% reliably, that the partition must be mounted successfully, that it has issues on the ESP32 C3 Mini because of the smaller SRAM size, and that it is not ported to LVGL 9 yet. That is four separate warnings on the one feature that would make the project attractive for a product, since compiling faces into the firmware is not a substitute at scale. The second is a team that does not want a demo. The project describes itself as a demo, the screens are the ones a watch face demo would have, and there is no API for a third party to build on without forking. The sample directory for custom apps is an invitation to write your own screens inside the project rather than a stable extension point, so anything you build is a fork by the time you maintain it. The third is a project on a board outside the list, or on a display geometry the layout code does not handle. Thirteen boards are enumerated, and the geometry range runs from 240 by 240 to 466 by 466 to 410 by 502 and 360 by 360, and each of those is a set of layout constants somebody had to get right. A different panel means new work. The alternative worth weighing is writing the UI yourself in LVGL on top of an ESP32 Arduino or ESP-IDF project, and the difference in approach is where the value actually sits. A hand-written project gives you exactly the screens and the layout you need, on exactly your board, with no partition juggling and no half-finished LVGL 9 features, and it costs you the calendar, weather, notification and navigation plumbing that the Chronos library already handles. For a learning project or a one-off build, this repository saves a lot of work and shows how the pieces fit together. For a product, the demo's structure and its unresolved LVGL 9 install path are the parts you would end up replacing anyway. ## Conclusion esp32-c3-mini fits a maker building a small wearable or glanceable display on an ESP32 board, who wants a working LVGL interface to modify rather than a blank project, and who can flash firmware with the web flasher or a PlatformIO setup. It does not fit a product that needs the installable watchface feature on an ESP32-C3 mini, because the README warns of SRAM issues on that board and says the feature is not yet ported to LVGL 9. Before you start, check the board list against the hardware you have and read the partition files, because the flash layout differs between the 8M and 16M variants and the installable watchfaces need the FFAT partition mounted. ## FAQ ### What is the esp32-c3-mini project? It is a demo LVGL watch project for the ESP32 C3 mini 240 by 240 touch display development board, written in C and licensed MIT. The screens cover time with custom watchfaces, weather, notifications, settings, music and phone control, QR codes and contacts, games, and navigation instructions, and it can also be built natively to test the LVGL UI. ### How do I add a custom watchface to esp32-c3-mini? There are two mechanisms. External precompiled binary watchfaces are binary files converted into LVGL code and compiled into the firmware, so adding or removing them means recompiling and flashing, and the README advises compiling only a few because of the ESP32 flash size limits. External installable watchfaces work on LVGL 8 on a branch, with LVGL 9 still in progress, and need the FFAT partition mounted. ### What is the native build for in esp32-c3-mini? The native build runs the whole LVGL interface on a desktop so you can develop screens without flashing hardware, and it needs SDL installed for your platform with the path set in platformio.ini. The README also ships prebuilt native applications in the test folder, though SDL is still required to run them. ### What does the Chronos app add to the ESP32 watch? The ChronosESP32 library handles communication with the Chronos app over BLE, covering time synchronisation, notifications and call alerts, weather information, QR links and contacts, music control with find phone and camera, and navigation instructions. The phone app is described as necessary for these additional hardware functions. ### Which boards are supported by esp32-c3-mini? The README lists thirteen, including the CrowPanel ESP32 Display-1.28(R) 240x240, the M5 Stack Dial, the ESP32 C3 Mini 1.28, Waveshare boards at 240x240, 240x280 and 466x466, Waveshare RP2040 boards, and several Viewe round AMOLED devices including the 1.8 at 466x466 and the Echo Ear at 360x360. ## Sources - [fbiego/esp32-c3-mini on GitHub](https://github.com/fbiego/esp32-c3-mini) - [License: MIT](https://github.com/fbiego/esp32-c3-mini/blob/main/LICENSE) - [Project website](https://chronos.ke/c3-ui) - [README](https://github.com/fbiego/esp32-c3-mini/blob/main/README.md) - [Releases](https://github.com/fbiego/esp32-c3-mini/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/fbiego-esp32-c3-mini