cube32esp/cube32_bsp

# CUBE32 BSP [![ESP-IDF](https://img.shields.io/badge/ESP--IDF-%3E%3D5.4.0-red?logo=espressif)](https://github.com/espressif/esp-idf) [![Target](https://img.shields.io/badge/target-ESP32--S3-blue?logo=espressif)](https://www.espressif.com/en/products/socs/esp32-s3) [![LVGL](https://img.shields.io/badge/LVGL-9.x-darkgreen)](https://lvgl.io) [![Component Registry](https://components.espressif.com/components/cube32esp/cube32_bsp/badge.svg)](https://components.espressif.com/components/cube32esp/cube32_bsp) [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE) **CUBE32 BSP** is a turnkey ESP32-S3 board support package designed for AI-assisted and vibe-coded IoT development. Drop it into any ESP-IDF project with one command. Every on-board peripheral — display, touch, IMU, audio, camera, LTE modem, PMU, RTC — initialises with a single `cube32_init()` call so you can skip the boilerplate and focus entirely on your application logic. --- ## Hardware — CUBE32-S3 Core | Peripheral | Details | |---|---| | **MCU** | ESP32-S3 — dual-core Xtensa LX7 @ 240 MHz, 8 MB PSRAM (Octal), 16 MB Flash | | **Display** | Auto-detected RGB565 TFT boards — 1.54″ 240×240 (ST7789), 2.0″ 240×320 (ST7789), 320×320 (ST7796S) | | **Touch** | Capacitive touch panel — CST816S, FT6336 or GT911 (matched to the display board) | | **IMU** | LSM6DSOX 6-axis IMU with on-chip Machine Learning Core (MLC) | | **Magnetometer** | LIS3MDL 3-axis magnetometer | | **PMU** | AXP2101 — battery charging, rail management, fuel gauge | | **RTC** | BM8563 — battery-backed real-time clock | | **Audio** | ES8311 DAC + ES7210 ADC — stereo speaker & 4-channel microphone, 16 kHz default (8–48 kHz configurable) | | **Camera** | OV2640 (up to UXGA) | | **SD Card** | SDMMC — FATFS mount at `/sdcard` | | **LTE Modem** | SIMCom A7670 — USB or UART AT commands, PPP data; connection type fixed at build time or chosen at runtime over BLE | | **USB HID** | USB keyboard + mouse input (host) | | **ADC Buttons** | 6-button array on single ADC channel | | **IO Expander** | TCA9554 (×2) — GPIO expansion, modem & audio power control | | **LVGL** | LVGL 9.x with esp_lvgl_port — thread-safe UI with DMA rendering | --- ## Quick Start ### 1. Add the component ```bash idf.py add-dependency "cube32esp/cube32_bsp" ``` Or add manually to your project's `main/idf_component.yml`: ```yaml dependencies: cube32esp/cube32_bsp: "*" ``` ### 2. Set target ```bash idf.py set-target esp32s3 ``` ### 3. Write your application ```cpp #include "cube32.h" extern "C" void app_main(void) { // Initialise all CUBE32 hardware drivers in the correct order esp_err_t ret = cube32_init(); if (ret != ESP_OK) { ESP_LOGE("app", "Board init failed: %s", esp_err_to_name(ret)); return; } // Display is up — draw something with LVGL cube32::LvglDisplay &lvgl = cube32::LvglDisplay::instance(); lvgl.lock(); lv_obj_t *label = lv_label_create(lv_screen_active()); lv_label_set_text(label, "Hello CUBE32!"); lv_obj_center(label); lvgl.unlock(); } ``` ### 4. Build and flash ```bash idf.py build flash monitor ``` --- ## Driver Overview Every driver follows the singleton pattern and returns `cube32_result_t` from `begin()`. Drivers are enabled/disabled via Kconfig so unused peripherals never enter your binary. | Driver | Kconfig Key | Description | |---|---|---| | **PMU** | `CUBE32_PMU_ENABLED` | AXP2101 power management — battery %, voltage, charge state, power rails | | **Display** | `CUBE32_DISPLAY_ENABLED` | ST7789 / ST7796S SPI display with DMA — board model auto-detected from the touch controller at boot | | **Touch** | `CUBE32_TOUCH_ENABLED` | Auto-detects CST816S, FT6336 or GT911 capacitive touch | | **LVGL** | `CUBE32_LVGL_ENABLED` | LVGL 9.x with esp_lvgl_port — `lock()`/`unlock()` thread safety | | **RTC** | `CUBE32_RTC_ENABLED` | BM8563 battery-backed RTC — get/set time, alarms, timers | | **IMU** | `CUBE32_IMU_ENABLED` | LSM6DSOX 6-axis (accel + gyro) with Machine Learning Core (MLC) | | **Magnetometer** | `CUBE32_MAG_ENABLED` | LIS3MDL 3-axis — raw field data, calibration | | **Audio** | `CUBE32_AUDIO_ENABLED` | ES8311+ES7210 — speaker playback, 4-ch microphone, 16 kHz default | | **Camera** | `CUBE32_CAMERA_ENABLED` | OV2640 — configurable frame size and pixel format | | **SD Card** | `CUBE32_SDCARD_ENABLED` | SDMMC FATFS — `/sdcard` mount, 1-bit or 4-bit mode | | **LTE Modem** | `CUBE32_MODEM_ENABLED` | A7670 over USB or UART (default: runtime-selectable) — AT commands, PPP internet, async init | | **USB HID** | `CUBE32_USB_INPUT_ENABLED` | USB keyboard & mouse host — LVGL pointer integration | | **ADC Buttons** | `CUBE32_ADC_BUTTON_ENABLED` | 6-button resistor ladder on one ADC pin | | **IO Expander** | `CUBE32_IO_EXPANDER_ENABLED` | TCA9554 GPIO expander — modem power, audio PA enable | | **BLE OTA** | `CUBE32_BLE_OTA_ENABLED` | NimBLE-based OTA firmware update over BLE | | **Safe Mode** | `CUBE32_SAFE_MODE_ENABLED` | Crash-loop recovery over BLE — `cube32_init()` does not return, so no app code runs | | **Log Capture** | `CUBE32_LOG_CAPTURE_ENABLED` | Mirrors `ESP_LOG` output into a PSRAM buffer from the start of `cube32_init()`, retrievable over BLE OTA | | **Servo** | `CUBE32_SERVO_ENABLED` | PWM servo control via LEDC | --- ## Kconfig Highlights Run `idf.py menuconfig` → **CUBE32 Board Configuration** to fine-tune: | Option | Default | Description | |---|---|---| | Board model | `CUBE32-S3 Core` | Hardware variant selection | | LVGL double buffer | `y` | Enable for tear-free rendering | | IMU Machine Learning Core | `n` | On-device activity recognition | | Audio input / output sample rate | `16000` | Sample rate in Hz (8000–48000); keep input and output equal | | Modem connection type | `Runtime` | `USB` (fixed), `UART` (fixed) or `Runtime` (chosen over BLE, stored in NVS, applied after restart; falls back to USB until set) | | Safe mode | `y` | BLE crash-loop recovery | | Log capture | `y` | Boot/runtime log buffer for BLE OTA retrieval (32 KB boot buffer) | | Allow eFuse security features | `n` | Build fails on settings that would block UART0 recovery (Secure Boot, release-mode flash encryption, …) | The display board model is auto-detected at boot from the touch controller's I2C address, so there is no display-model option. --- ## Partition Layout The standard CUBE32 partition layout targets 16 MB flash with dual OTA banks, a core dump partition, and an assets partition for fonts, audio clips, and ML models: | Partition | Type | Size | Purpose | |---|---|---|---| | `nvs` | data/nvs | 16 KB | Key-value storage (WiFi credentials, config) | | `otadata` | data/ota | 8 KB | OTA slot tracking | | `phy_init` | data/phy | 4 KB | RF calibration data | | `coredump` | data/coredump | 64 KB | Crash core dump | | `ota_0` | app/ota_0 | 5 MB | Application image (slot A) | | `ota_1` | app/ota_1 | 5 MB | Application image (slot B) | | `assets` | data/spiffs | 5.875 MB | Fonts, images, audio, ML models | See `examples/hello_world/partitions/partitions.csv` for the full CSV definition. --- ## Examples | Example | Description | |---|---| | [`hello_world`](examples/hello_world/) | Interactive 3D cube (IMU gyro + touch) and driver status screen | | [`hello_display`](examples/hello_display/) | LVGL display demo — widgets, animations, and touch input | | [`hello_camera`](examples/hello_camera/) | OV2640 camera capture streamed live to the TFT display | | [`hello_audio_player`](examples/hello_audio_player/) | WAV and MP3 playback from SD card with LVGL file browser UI | | [`hello_audio_recorder`](examples/hello_audio_recorder/) | Microphone recording to WAV on SD card with LVGL record/play controls | | [`hello_aec_test`](examples/hello_aec_test/) | Acoustic Echo Cancellation comparison — records three WAV files in different AEC modes | | [`hello_rtc_ntp`](examples/hello_rtc_ntp/) | BM8563 RTC synced via NTP over WiFi or LTE modem (A7670) with LVGL clock UI | | [`hello_activity`](examples/hello_activity/) | Threshold-based activity recognition from LSM6DSOX accelerometer/gyro data | | [`hello_ble_ota`](examples/hello_ble_ota/) | BLE OTA driver demo with live BLE status, commands and responses on LVGL | | [`hello_compass`](examples/hello_compass/) | Tilt-compensated digital compass (LSM6DSO + LIS3MDL) with hard-iron calibration | | [`hello_imu_mag`](examples/hello_imu_mag/) | Live IMU and magnetometer readings on an LVGL screen and the console | | [`hello_lvgl`](examples/hello_lvgl/) | Minimal LVGL 9 + touch demo — widgets, touch events, swipe-to-rotate | | [`hello_mlc_activity`](examples/hello_mlc_activity/) | LSM6DSOX Machine Learning Core activity recognition | | [`hello_modem_console`](examples/hello_modem_console/) | A7670 LTE modem AT-command console over USB or UART | | [`hello_mqtt`](examples/hello_mqtt/) | MQTT client with AWS IoT support over WiFi or LTE modem, TLS, LVGL UI | | [`hello_pwm_servo`](examples/hello_pwm_servo/) | LEDC PWM servo control with console interface and LVGL feedback | | [`hello_rtc_timer`](examples/hello_rtc_timer/) | BM8563 timer and alarm demo, including RTC power-on from the off state | | [`hello_sdcard`](examples/hello_sdcard/) | SDMMC SD card test with LVGL results GUI | | [`hello_spirit_level`](examples/hello_spirit_level/) | Digital spirit level (inclinometer) shown as a bubble on an LVGL canvas | | [`hello_touch`](examples/hello_touch/) | Raw touch-panel demo without LVGL — draws a trace and prints coordinates | | [`hello_usb_input`](examples/hello_usb_input/) | USB HID keyboard and mouse input with LVGL | | [`hello_web_cam`](examples/hello_web_cam/) | HTTP MJPEG camera streaming server with web-based camera controls | | [`hello_audio_loopback`](examples/hello_audio_loopback/) | Real-time microphone-to-speaker loopback for interactive AEC evaluation | See [`examples/README.md`](examples/README.md) for build and flash instructions. --- ## Speech Recognition (Optional) `esp-sr` (Espressif's speech recognition + AEC library) is **not included** in the BSP by default — it adds ~8 MB to the binary. If your application requires wake-word detection, AEC, or voice commands, add it to your project's `idf_component.yml`: ```yaml dependencies: cube32esp/cube32_bsp: "*" espressif/esp-sr: "~2.1.5" ``` --- ## Build Requirements | Requirement | Version | |---|---| | ESP-IDF | ≥ 5.4.0 | | Target | `esp32s3` | | Python | ≥ 3.8 (for IDF tools) | ```bash # Install ESP-IDF if not already set up # https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/get-started/ idf.py set-target esp32s3 idf.py menuconfig # optional — review CUBE32 Board Configuration idf.py build ``` --- ## Why CUBE32 for AI / Vibe Coding? CUBE32 eliminates the hardware integration tax that typically consumes 80 % of embedded AI project time: - **Single init call** — `cube32_init()` handles driver ordering, retry logic, and conflict resolution automatically - **AI-friendly API** — predictable singleton interface across all drivers; easy for LLM-generated code to target - **Rich sensor suite** — IMU with on-chip MLC activity recognition, 4-channel microphone, camera, and LTE modem — everything an edge AI demo needs in one board - **Vibe-coding ready** — comprehensive Kconfig, consistent result codes (`cube32_result_t`), and guard macros (`#if CONFIG_CUBE32_*`) make it straightforward for AI assistants to generate correct, conditionally-compiled application code --- ## License MIT © cube32esp — see [LICENSE](LICENSE).

Readme

Links

Target

Tags

Stats

Badge