Update README
This commit is contained in:
dark98
@@ -1,48 +1,166 @@
|
|||||||
# ABrobot ESP32-C3 0.42" OLED — Micro-OS
|
# 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/
|
d:/Projects/ESP32C3/OS/
|
||||||
├── components/
|
├── components/
|
||||||
│ ├── sys_core/ # Event bus (sys_event) & global state telemetry (sys_status)
|
│ ├── sys_app/ # App lifecycle and app registry
|
||||||
│ ├── sys_input/ # Single-button gesture engine (Click, Double-Click, Hold, Home)
|
│ ├── sys_cli/ # USB serial / JTAG shell commands
|
||||||
│ ├── sys_gfx/ # 72x40 UI compositor, OLED driver, 5x7 & 3x5 fonts, status/action bars, widgets
|
│ ├── sys_core/ # Global status and event plumbing
|
||||||
│ ├── sys_app/ # App lifecycle manager, registry, and Home App Launcher
|
│ ├── sys_gfx/ # OLED display, fonts, UI compositor, widgets
|
||||||
│ └── sys_cli/ # Interactive USB Serial/JTAG shell (ps, free, app, input, reboot)
|
│ ├── 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/
|
├── main/
|
||||||
│ ├── apps/
|
│ ├── apps/
|
||||||
│ │ ├── apps.h # System apps registry
|
│ │ ├── app_clock.c
|
||||||
│ │ ├── app_clock.c # Clock / Watchface app (multiple view modes, live seconds bar)
|
│ │ ├── app_game.c
|
||||||
│ │ ├── app_sysmon.c # Real-time System Monitor (live RAM sparkline graph, tasks, specs)
|
│ │ ├── app_settings.c
|
||||||
│ │ ├── app_settings.c # Settings app (contrast, inverted colors, statusbar toggle, reboot)
|
│ │ ├── app_sysmon.c
|
||||||
│ │ └── app_game.c # Tiny Jump retro runner mini-game
|
│ │ └── apps.h
|
||||||
│ ├── CMakeLists.txt
|
│ ├── CMakeLists.txt
|
||||||
│ └── main.c # OS bootstrap, LED heartbeat, and 20 FPS compositor loop
|
│ ├── font_5x7.h
|
||||||
├── sdkconfig.defaults # ESP32-C3 target & USB Serial/JTAG console defaults
|
│ ├── main.c
|
||||||
└── README.md
|
│ └── 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 |
|
The firmware is designed to work in two modes:
|
||||||
| :--- | :--- | :--- |
|
|
||||||
| **Short Click** | $< 350\text{ ms}$ | **Next / Step / Jump:** Cycle menu items, change clock view, jump in mini-game |
|
1. Station mode when valid saved credentials exist.
|
||||||
| **Double Click** | 2 clicks in $280\text{ ms}$ | **Previous / Back:** Cycle menu backwards |
|
2. SoftAP provisioning mode when Wi‑Fi is enabled but no stored SSID/password is available.
|
||||||
| **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 |
|
### 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
|
```text
|
||||||
esp32c3-os> help
|
esp32c3-os> help
|
||||||
@@ -55,22 +173,30 @@ esp32c3-os> help
|
|||||||
reboot Reboot the MCU
|
reboot Reboot the MCU
|
||||||
```
|
```
|
||||||
|
|
||||||
### Examples:
|
Examples:
|
||||||
- Switch to the game remotely: `app launch game`
|
|
||||||
- Trigger a jump remotely: `input click`
|
```text
|
||||||
- Inspect tasks: `ps`
|
app launch game
|
||||||
- Return to home menu: `app home`
|
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
|
## Notes
|
||||||
idf.py -p COMx flash monitor
|
|
||||||
```
|
- 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user