Niu Lai for FoloToy AI Passport

English | 简体中文

An offline interactive “Niu Lai” soundboard for the ESP32-C3-based FoloToy AI Passport. It combines character animation, dialogue playback, battery status, volume control, and user-recorded replacement voices in one small firmware image.

Important

This is an unofficial fan prototype. The MIT license covers the source code only. Movie images and audio may have separate rights; review the asset source and distribution notice before redistributing firmware or media.

Features

• Full-screen poster and two-frame Niu Lai/Mama animations.
• Built-in 16 kHz mono dialogue with software volume control.
• Up to 10 seconds of replacement voice recording per character.
• Power-loss-safe, dual-bank recording storage in a dedicated flash partition.
• iOS-style battery indicator with a voltage fallback when CW2017 SOC is unavailable.
• Three-button UI; no network or account is required.

Controls

See the user guide for installation, recording behavior, and troubleshooting.

Install a release

Download the newest artifacts from GitHub Releases.

• Flash *-full.bin at address 0x0 for the first installation or whenever the partition table changes.
• Flash *-app.bin at address 0x10000 only when the device already has this project's partition table.
• Verify downloads with SHA256SUMS.

The recording feature depends on the recordings partition. An app-only image cannot create it.

Build from source

Requirements: FoloToy AI Passport, USB data cable, Git, and ESP-IDF 5.5.3.

git clone https://github.com/JollySun/folo-ai-passport-niulai.git
cd folo-ai-passport-niulai
source "$HOME/esp/esp-idf/export.sh"
scripts/test.sh
idf.py build
idf.py flash monitor

Detailed setup, packaging, and flashing commands are in Building.

Repository layout

components/bsp/       Board drivers and hardware constants
main/                 Application state, UI, audio, and recording storage
main/assets/niulai/   Firmware-ready RGB565 and PCM assets
assets/niulai/        Human-viewable previews and provenance
tests/                Hardware-independent C tests
scripts/              Test and firmware-packaging entry points
docs/                 User, build, architecture, and hardware documentation

The application keeps hardware-independent state in niulai_model, persistent voice storage in niulai_voice_store, and board access behind the BSP interfaces. See Architecture for the runtime and flash layout.

Development

scripts/test.sh
idf.py build
scripts/package-firmware.sh build dist dev

Pull requests run host tests and a complete ESP-IDF build. Tags matching v* create a GitHub Release with full, app-only, bootloader, partition-table, and checksum artifacts.

Read Contributing, Security, and the changelog before submitting a change.

License and acknowledgments

Source code is licensed under the MIT License. Media assets are not automatically covered by that license; see SOURCES.md.

Built for the FoloToy AI Passport using ESP-IDF, LVGL, esp_lvgl_port, button, and esp_codec_dev.