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
Hardware UART Serial Console bridge (TX: GPIO 21, RX: GPIO 20) with Web Terminal UI at /serial
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

d:/Projects/ESP32C3/OS/
├── components/
│   ├── sys_app/             # App lifecycle and app registry
│   ├── sys_cli/             # USB serial / JTAG shell commands
│   ├── sys_core/            # Global status, event plumbing & sys_uart driver
│   ├── 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
│       │   └── serial.c      # /serial Web Serial Terminal and /serial/data REST API
│       └── web_server.c      # Starts the HTTP server and registers pages
├── main/
│   ├── apps/
│   │   ├── app_clock.c
│   │   ├── app_game.c
│   │   ├── app_settings.c
│   │   ├── app_sysmon.c
│   │   ├── app_serial.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:

Station mode when valid saved credentials exist.
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
/serial — Web Serial Terminal interface
/serial/data — Real-time streaming JSON endpoint for RX/TX delta bytes
/serial/tx — POST endpoint to transmit text or bytes over UART TX (GPIO 21)
/serial/baud — POST endpoint to dynamically change UART baud rate
/serial/clear — POST endpoint to clear the RX ring buffer

Web Serial Terminal

Connect over Wi-Fi and open http://192.168.4.1/serial (in SoftAP mode) or http://<board-ip>/serial (in station mode) to access the interactive web-based serial console:

Pins: TX on GPIO 21, RX on GPIO 20
Features: Live streaming terminal, color-coded RX/TX logs, auto-scroll toggle, command history (Up/Down arrow navigation), dynamic baud rate switching (9600 to 921600), macro shortcuts (PING, AT, HELP, etc.), and log file exporting.

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.

# 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:

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.

# 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:

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 <id>, home)
  input       Simulate button input (click, double, long, home)
  uart        Hardware UART control (send, baud, stats, clear)
  contrast    Set OLED contrast (0-255)
  reboot      Reboot the MCU

Examples:

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.

README.md Unescape Escape

ABrobot ESP32-C3 0.42" OLED — Micro-OS