From dc3b72bdbd50548b2fafb3c6c5a06d79112e253b Mon Sep 17 00:00:00 2001 From: dark98 Date: Sun, 6 Sep 2026 16:21:16 +0100 Subject: [PATCH] Update README --- README.md | 202 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 164 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 4fc7d0b..6437466 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,166 @@ # ABrobot ESP32-C3 0.42" OLED — Micro-OS -A modular, lightweight **Embedded Micro-OS** built for the **ABrobot ESP32-C3** development board equipped with the integrated **0.42" (72x40) monochrome OLED display**. +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. --- -## 🏛️ System Architecture +## 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_core/ # Event bus (sys_event) & global state telemetry (sys_status) -│ ├── sys_input/ # Single-button gesture engine (Click, Double-Click, Hold, Home) -│ ├── sys_gfx/ # 72x40 UI compositor, OLED driver, 5x7 & 3x5 fonts, status/action bars, widgets -│ ├── sys_app/ # App lifecycle manager, registry, and Home App Launcher -│ └── sys_cli/ # Interactive USB Serial/JTAG shell (ps, free, app, input, reboot) +│ ├── 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/ -│ │ ├── apps.h # System apps registry -│ │ ├── app_clock.c # Clock / Watchface app (multiple view modes, live seconds bar) -│ │ ├── app_sysmon.c # Real-time System Monitor (live RAM sparkline graph, tasks, specs) -│ │ ├── app_settings.c # Settings app (contrast, inverted colors, statusbar toggle, reboot) -│ │ └── app_game.c # Tiny Jump retro runner mini-game +│ │ ├── app_clock.c +│ │ ├── app_game.c +│ │ ├── app_settings.c +│ │ ├── app_sysmon.c +│ │ └── apps.h │ ├── CMakeLists.txt -│ └── main.c # OS bootstrap, LED heartbeat, and 20 FPS compositor loop -├── sdkconfig.defaults # ESP32-C3 target & USB Serial/JTAG console defaults -└── README.md +│ ├── 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 +└── ... ``` --- -## 🎮 Single-Button Gesture Controls (`GPIO 9`) +## Wi‑Fi behavior -| Gesture | Timing | Action | -| :--- | :--- | :--- | -| **Short Click** | $< 350\text{ ms}$ | **Next / Step / Jump:** Cycle menu items, change clock view, jump in mini-game | -| **Double Click** | 2 clicks in $280\text{ ms}$ | **Previous / Back:** Cycle menu backwards | -| **Long Press** | $\ge 450\text{ ms}$ | **Select / Toggle:** Launch selected app, toggle settings | -| **Hold (Home)** | $\ge 1500\text{ ms}$ | **Global Home:** Return to the system App Launcher from any app | +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. --- -## 💻 Interactive USB CLI Console +## Wi‑Fi setup flow -Connect the board via USB-C and open the serial monitor to access the live OS terminal: +### 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 @@ -55,22 +173,30 @@ esp32c3-os> help reboot Reboot the MCU ``` -### Examples: -- Switch to the game remotely: `app launch game` -- Trigger a jump remotely: `input click` -- Inspect tasks: `ps` -- Return to home menu: `app home` +Examples: + +```text +app launch game +input click +ps +app home +``` --- -## 🚀 How to Build and Flash +## Button gestures -In your ESP-IDF terminal environment: +| 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 | -```bash -# 1. Build the project -idf.py build +--- -# 2. Flash to the board and open the serial monitor -idf.py -p COMx flash monitor -``` +## 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.