DOCUMENTATION

Build the firmware, run the app, and understand the Bluetooth protocol.

Build guide

Prerequisites, PlatformIO firmware build, Flutter app builds and platform configuration.

BLE protocol

The complete Nexo wire protocol, v2: framing, opcodes, codecs and the Wi-Fi HTTP API.

Troubleshooting

Known issues and fixes for audio, Bluetooth and the build toolchain.

Quick start

Firmware

cd firmware
export PATH="$HOME/Library/Python/3.13/bin:$PATH"
pio run -e m5stack-cardputer   # -> .pio/build/m5stack-cardputer/firmware.bin
pio test -e native             # portable core unit tests

Companion app

cd app
flutter pub get
flutter test
flutter analyze
flutter build macos --release
flutter build apk --release --target-platform android-arm64

Hardware

MCU: ESP32-S3 (M5Stack Cardputer / Stamp-S3A, 8 MB flash).
Audio: ES8311 codec over I²C, I²S to the speaker (AMP_EN on GPIO46).
Display: 240×135 ST7789.
Storage: microSD for music, LittleFS on flash for notes, homework and settings.

Protocol at a glance

All device communication uses one GATT service. Requests are framed and authenticated with a PIN; the first response byte is a status code. Highlights of v2:

Notes & homework CRUD with revisions, tombstones and delta sync.
Device info, time sync (the Cardputer has no RTC), find / reboot / factory reset.
Music list, playback control, now-playing and delete.
Optional Wi-Fi HTTP API for bulk music transfer and OTA updates.

See docs/PROTOCOL.md for the full specification.

Source

The firmware and app live together in one repository.

Repository README Issues