ESP32C3_0.42OLED/ESP32C3-0.42OLED-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README

Browse Source
This commit is contained in:
dark98
2026-09-06 16:21:16 +01:00
parent ee046a001e
commit dc3b72bdbd
1 changed files with 164 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+164 -38
View File
@@ -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://<board-ip>/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.