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 dialogue with adjustable playback volume.
• Up to 10 seconds of replacement voice recording per character.
• Saved recordings survive restarts, and an interrupted save keeps the previous recording intact.
• Custom-voice animations stop when the recorded voice finishes.
• iOS-style battery indicator with a voltage fallback when CW2017 SOC is unavailable.
• Three-button UI; no network or account is required.

Controls

The settings footer always shows the current button actions and a second-line Hold OK to return reminder.

After 30 seconds without input, the LCD backlight turns off without changing the current caption. The next complete button gesture wakes the display without triggering its normal action.

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.

If recording is unavailable after an app-only update, reinstall with the full image.

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.