203 lines
6.3 KiB
Markdown
203 lines
6.3 KiB
Markdown
# 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://<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
|
||
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)
|
||
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.
|