English · 简体中文

FoloToy AI PASSPORT

Wear it. Flash it. Make it anything.
Simple and open. Anyone can build.

Website · Start building · Community projects · Documentation

---

FoloToy AI Passport is an open wearable AI platform made for people to shape, remix, and create. Start with a simple idea, build your own experience, and make it anything—from a pocket companion to something no one has imagined yet.

Open and remixable	Easy to start	Yours to create
Open firmware and reusable examples give you room to shape your own experience.	Start from an idea and follow clear guides to make it real, even if this is your first build.	Make a companion, a tool, a game—or anything you can imagine.

Find your starting point

I want to…	Start here
Use the device or try an official play	Getting started · Official plays
Build a custom application with AI	Agent instructions · AI development guide · Required skills
Prepare my environment and build firmware	Environment setup · Build and test
Explore the board or contribute	Hardware guide · Contributing

Important

main is a minimal, runnable hardware-test baseline, not a finished application. Derivative applications must design their own UI; the current demo test menu and screens must not be reused. BSP APIs and non-UI logic remain reusable.

Start development with one requirement

1. Open the repository in your AI coding tool and have it read AGENTS.md.
2. Let it check and install the five required skills, with any permissions your environment requires.
3. Describe what you want to build. Start from main on a new feature/* branch.

Copy this prompt and adapt it to your idea:

Build an offline habit-tracking application for FoloToy AI Passport.
Use the three physical buttons and the 240×320 display, and preserve records across power loss.
Start from `main`, create a `feature/*` branch, and develop the application there.
Follow AGENTS.md and docs/hardware-design/AI_HARDWARE_DEVELOPMENT_GUIDE.md.
Inspect relevant demo branches and docs/reference/ application archives first.
Keep hardware logic in components/bsp and application logic in main.
Deliver a runnable implementation with tests; report build results,
unexecuted device checks, and on-device acceptance steps separately.
Redesign the application's UI; do not use the current demo test menu or screens.

Before starting, check docs/reference/ for an existing or reference application and previously recorded, reusable experience, and the demo branches. See what is already built and reusable.

Write a clearer requirement — pages, controls, data, and acceptance

The more specific the requirement, the more likely the assistant is to implement it correctly in one pass. Useful details include:

• User flow: what each page displays and what short press, double press, and long press do for each button.
• State and data: whether the application needs timing, persistence across power loss, networking, recording, or communication with a computer.
• Experience goals: fonts, colors, animation, sound, response time, and error states.
• Constraints: application navigation and controls, permitted dependencies, and Flash/data usage. The baseline test menu is not an application UI option.
• Acceptance criteria: which behaviors require automated tests and which must be observed on real hardware.

When details are omitted, the assistant may choose conservative defaults that do not change the product direction, but it must list those assumptions in the delivery. Decisions involving new wiring, electrical safety, board revisions, or irreversible data formats require confirmation first.

Note

A successful build is not hardware validation. Test the application on a real device after implementation; flashing requires your approval. Deliver a verified merged full.bin for flashing at 0x0. No original-firmware backup is required, but a merged flash may reset stored data. See the flashing policy.

Demo branches are design cases, not a feature pile

Each demo/* branch evolves the baseline into an independent application. The branches demonstrate how specific problems were solved. New applications should normally branch from main and consult relevant examples instead of merging multiple demos wholesale.

The menu and demo_*.c pages on main are hardware-capability tests, not an application UI. Every derivative application must redesign and implement its own screens and interaction flow; using the current test menu, screens, or visual shell is prohibited. Renaming or recoloring them does not satisfy this requirement. BSP APIs, ordinary LVGL widgets, lifecycle patterns, and isolated logic may still be reused. See the mandatory UI redesign rule; maintenance of the baseline hardware-test demo itself is a separate task.

Branch	Application	Patterns worth reusing
demo/stopwatch	Stopwatch	Minimal timer application, separation of pure logic from LVGL, host-side logic tests
demo/cat-themed-pomodoro-timer	Cat-themed Pomodoro timer	Monotonic time, pause/resume, NVS persistence, a detailed PRD, and a state model
demo/rock-paper-scissors	Rock paper scissors	RGB565 image assets, asset-generation scripts, and Flash resource tradeoffs
demo/tetris-game	Three-button Tetris	Real-time game loop, low-latency PRESS input, partial refresh, a pure game model, audio, and microphone interaction
demo/claude-buddy-port	Desktop AI hardware companion	Replacing the demo menu with a complete application, encrypted BLE, protocol parsing, state reduction, task communication, and extensive host tests

Explore a demo and create your application branch

Inspect an example without switching the current working tree:

git branch -r --list 'origin/demo/*'
git diff main...origin/demo/tetris-game -- main components tests
git show origin/demo/tetris-game:main/demo_tetris.c

Start a new application. This repository hosts several independent projects on one baseline: after starting from main, create a feature/* branch and develop the application there — do not develop directly on main. Each project's final branch is feature/* (e.g. feature/my-passport-app), kept separate so main stays a clean upstream baseline and the projects do not entangle.

git switch main
git switch -c feature/my-passport-app

Example branches may change the same menu, configuration, or driver in incompatible ways. Understand the differences before extracting a state model, asset pipeline, or concurrency pattern. Code appearing in an example branch is not automatically part of the current main BSP contract.

Hardware capability contract

ESP32-C3 · 8 MB Flash · no PSRAM · 240 × 320 display · three physical buttons

The default layout contains only NVS, PHY data, and one factory application spanning the remaining Flash. User firmware may use another valid 8 MB layout. See firmware layout.

Expand the capability table — interfaces, limits, and implementation details

The table below describes the application capabilities implemented by the current main branch. It is not a list of everything that might be possible according to the chip datasheet.

Capability	Confirmed implementation	Application interface	Boundaries that must be respected
Display	ST7789P3, 240 × 320 portrait RGB565, SPI2 at 40 MHz; LEDC backlight	bsp_display_*, bsp_lvgl_*	The ESP32-C3 has no PSRAM; the current design uses a small single DMA buffer; the BSP exposes no LCD MISO, touch, or TE interface
Input	UP, DOWN, and OK share an ADC resistor ladder on GPIO0	bsp_button_init(), bsp_button_read_mv()	Callbacks run in the button component task and must not block; do not create a second ADC1 unit
Audio	ES8311 with full-duplex PCM over I2S0, supporting playback, microphone capture, and software suspend/resume	bsp_audio_*	PCM reads and writes block and belong in a worker task; stop PCM I/O before codec sleep; format changes must retain the BSP close/open sequence
Battery	CW2017 state-of-charge and voltage readings	bsp_battery_*	This capability is optional at runtime; accuracy depends on the cell and battery profile and is not equivalent to a calibrated result
Wi-Fi	On-demand 2.4 GHz STA scan demo	main/demo_wifi.c	Scans only; it does not connect, store credentials, or validate antenna/RF performance
Bluetooth LE	On-demand non-connectable NimBLE advertising as FoloPassport	main/demo_ble.c	ESP32-C3 does not support Bluetooth Classic; radio range, coexistence, and power draw require device measurements
Low power	Two-second light sleep and five-second deep sleep, both with RTC timer wakeup	main/demo_low_power.c	Both modes force and verify ES8311 suspend; light sleep restores audio, while deep sleep first suspends CW2017, releases I2S/shared-I2C pins, sleeps and holds the LCD pins, then restarts on wake; the current demo exposes RTC timer wake only
Shared bus	ES8311 and CW2017 share I2C0	bsp_i2c_*	Every device must reuse the bus owned by the BSP; do not create another bus on the same port for scanning or a new device
Logging and flashing	Native ESP32-C3 USB Serial/JTAG	ESP-IDF console	GPIO18/19 are reserved for USB; the default UART0 TX on GPIO21 conflicts with the backlight

All pins, addresses, panel parameters, and button voltage windows are defined only in components/bsp/include/bsp_pins.h. Application code must not duplicate these constants. See the AI Hardware Development Guide for the complete pin map, panel initialization, ADC thresholds, I2C addressing rules, audio clocks, and memory details.

Applications may also use ESP-IDF timers, FreeRTOS tasks, and internal Flash/NVS; the Pomodoro branch contains an NVS example. Wi-Fi and Bluetooth LE remain ESP-IDF application services rather than BSP APIs: their menu pages initialize each stack only while open and release it on exit. demo/claude-buddy-port remains a fuller BLE application architecture reference, not a substitute for measuring the current board's antenna, RF performance, power consumption, and coexistence behavior.

Capabilities outside the current contract

The public firmware contract is limited to the interfaces listed above. Do not infer additional board interfaces from the ESP32-C3 feature list. New hardware interfaces require an explicit BSP definition and on-device acceptance criteria.

Project structure

Board support lives in components/bsp; application pages, state, and tasks live in main. Keep that boundary when building your own firmware.

Browse the repository map

components/bsp/include/  Public BSP APIs and bsp_pins.h hardware facts
components/bsp/src/      Display, button, audio, battery, and shared-I2C implementations
main/                    Minimal menu, LVGL UI, and independent hardware demo pages
tests/                   Lightweight logic tests that can run without hardware
tools/                   Shared local/CI validation and firmware verification scripts
docs/                    Project docs, changelog, engineering/contribution rules, and design references
.github/                 GitHub community files, PR template, issue forms, and CI workflows
sdkconfig.defaults       ESP32-C3, USB console, Flash, and LVGL defaults
partitions.csv           Minimal default: NVS, PHY data, and one factory application
dependencies.lock        Reproducible ESP-IDF Managed Component resolution
AGENTS.md                Mandatory AI-agent entry point (paired with AGENTS.zh_CN.md)
CLAUDE.md                Claude Code pointer to AGENTS.md (paired Chinese version)
LICENSE                  Repository license

Documentation index

Engineering and contribution guides define the rules; examples and archives provide reference material. Choose the entry that matches your task.

Resource	What you will find
Development	AI workflow, engineering conventions, CI, and release guidance
AI skills	Development, environment setup, builds, device testing, and debugging
Hardware	Board facts, interface boundaries, acceptance checklists, and troubleshooting
Chinese fonts	Glyph coverage, widget font selection, and blank-text troubleshooting
Wi-Fi provisioning	Bluetooth provisioning reference and companion mini program
Community projects and experience	Playbooks and reusable knowledge under docs/reference/<username>/
Contributing	Documentation, commits, and pull-request conventions
Brand assets	Product visual references and brand language
Fork guide · Changelog	Downstream workflows and release history

---

Contribute · Get help · Code of conduct · Security · MIT License

AI agents: start with AGENTS.md and follow its task-specific routing.