# ABrobot ESP32-C3 0.42" OLED — Micro-OS A modular embedded micro-OS for the ABrobot ESP32-C3 board with a 0.42" monochrome OLED display. The project combines a lightweight UI shell, a command interface, Wi‑Fi provisioning, and OTA firmware updates in a small, ESP-IDF-based firmware image. --- ## Features - OLED-based app launcher and system UI - Single-button input handling with click, double-click, hold, and home gestures - USB serial/JTAG CLI for runtime system control - Wi‑Fi station mode with automatic fallback to SoftAP provisioning - Wi‑Fi network scanning from the setup page - Persistent NVS Wi‑Fi credentials - OTA firmware update via a web interface at `/ota` - 4 MB flash layout with dual OTA partitions --- ## System architecture ```text d:/Projects/ESP32C3/OS/ ├── components/ │ ├── sys_app/ # App lifecycle and app registry │ ├── sys_cli/ # USB serial / JTAG shell commands │ ├── sys_core/ # Global status and event plumbing │ ├── sys_gfx/ # OLED display, fonts, UI compositor, widgets │ ├── sys_input/ # Button input handling and gestures │ ├── sys_wifi/ # Wi‑Fi initialization, station/AP logic, NVS credentials │ └── web_server/ # HTTP server and page registration │ ├── include/ │ │ ├── web_server.h │ │ └── web_server_pages.h │ ├── pages/ │ │ ├── wifi.c # Root configuration and /scan /configure handlers │ │ └── ota.c # /ota firmware upload page and OTA logic │ └── web_server.c # Starts the HTTP server and registers pages ├── main/ │ ├── apps/ │ │ ├── app_clock.c │ │ ├── app_game.c │ │ ├── app_settings.c │ │ ├── app_sysmon.c │ │ └── apps.h │ ├── CMakeLists.txt │ ├── font_5x7.h │ ├── main.c │ └── oled_display.c/h ├── CMakeLists.txt ├── partitions.csv # 4 MB dual-OTA partition table ├── sdkconfig.defaults # ESP32-C3 and project defaults ├── README.md └── ... ``` --- ## Wi‑Fi behavior The firmware is designed to work in two modes: 1. Station mode when valid saved credentials exist. 2. SoftAP provisioning mode when Wi‑Fi is enabled but no stored SSID/password is available. ### Default SoftAP provisioning When the device boots without saved credentials, it starts an access point and exposes a configuration page at: - http://192.168.4.1 This page allows the user to: - view available Wi‑Fi networks - refresh the scan list - choose a network from the list - optionally enable a hidden network - enter the password - save the credentials for the next boot The configuration form posts to `/configure`, and the firmware stores the result in NVS before switching the device into station mode. The web server is also started while the board is connected to Wi‑Fi so the same interface remains available on the board's IP address in station mode. --- ## Wi‑Fi setup flow ### Start-up logic - `sys_wifi_init()` initializes NVS and ESP-IDF Wi‑Fi - If valid saved credentials exist, the board starts in `WIFI_MODE_STA` - Otherwise, the board starts `WIFI_MODE_APSTA` and host the provisioning page ### Web endpoints - `/` — network setup page - `/scan` — JSON network scan results - `/configure` — save station credentials and connect - `/ota` — OTA upload page and firmware update endpoint --- ## OTA update support The project includes a basic web-based OTA update flow. Once the board is on Wi‑Fi or in SoftAP mode, open: - http://192.168.4.1/ota when using the provisioning AP - http:///ota while in station mode The page allows you to upload a compiled firmware binary image (`.bin`). The firmware is written to the inactive OTA partition, marked as bootable, and the device reboots into the new image. This is enabled by the custom partition table and dual-OTA layout. --- ## Flash configuration The board is configured for a 4 MB flash with dual application slots. The partition layout is defined in `partitions.csv` and enabled in `sdkconfig.defaults`. ```csv # Name, Type, SubType, Offset, Size, Flags nvs, data, nvs, 0x9000, 0x6000, otadata, data, ota, 0xF000, 0x2000, phy_init, data, phy, 0x11000, 0x1000, ota_0, app, ota_0, 0x20000, 0x1E0000, ota_1, app, ota_1, 0x200000, 0x1E0000, ``` Key config entries in `sdkconfig.defaults`: ```ini CONFIG_IDF_TARGET="esp32c3" CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y CONFIG_ESPTOOLPY_FLASHSIZE="4MB" CONFIG_PARTITION_TABLE_CUSTOM=y CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions.csv" ``` --- ## Build and flash Use an ESP-IDF v6.x environment with the ESP32-C3 toolchain configured. ```bash # Build the firmware idf.py build # Flash to the connected device idf.py -p COMx flash # Optional: open the serial monitor idf.py -p COMx monitor ``` If you are using a USB serial/JTAG console, the project is configured to expose the console over the USB port. --- ## CLI controls Connect over USB and open the serial monitor to access the runtime command interface: ```text esp32c3-os> help help List all commands ps List active FreeRTOS tasks and memory free Display system heap and RAM status app App management (list, launch , home) input Simulate button input (click, double, long, home) contrast Set OLED contrast (0-255) reboot Reboot the MCU ``` Examples: ```text app launch game input click ps app home ``` --- ## Button gestures | Gesture | Timing | Action | | :--- | :--- | :--- | | Short Click | < 350 ms | Move through the next item or action | | Double Click | 2 clicks within 280 ms | Move backward or return to prior view | | Long Press | >= 450 ms | Select or toggle current item | | Hold / Home | >= 1500 ms | Return to the system home screen | --- ## Notes - Wi‑Fi provisioning is intentionally friendly for first-time setup: if the module is enabled but not configured, it becomes a temporary access point for onboarding. - The web UI is intentionally lightweight and suitable for a small ESP32-C3-class device. - OTA support is available after the board is connected to Wi‑Fi or through the SoftAP provisioning network.