# FoloToy AI Passport: An Open Wearable AI Platform for Custom Embedded Applications > FoloToy AI Passport is an open, MIT-licensed wearable AI platform with open firmware and a development workflow that uses AI coding assistants to build applications for the device. The main branch provides a minimal hardware-test baseline from which developers branch to create custom applications using the three physical buttons, the 240x320 display, and optional network, audio, and Bluetooth features. **FoloToy/ai-passport** — FOLOTOY AI Passport develop resources for Agent - Repository: https://github.com/FoloToy/ai-passport - Website: https://ai-passport.folotoy.cn - Stars: 502 · Forks: 193 - Language: C - License: MIT - Published: 2026-09-17 · Updated: 2026-09-17 · Language: en - Canonical page: https://hysenlabs.com/projects/folotoy-ai-passport ## What FoloToy AI Passport Is and Who It Is For FoloToy AI Passport is an open wearable AI hardware platform. The repository provides the firmware, build infrastructure, and development workflow for building custom applications on the physical device. The device has three physical buttons and a 240 by 320 display. The top-level entries include a `CMakeLists.txt` and an `sdkconfig.defaults`, which indicate an ESP-IDF-based build system. The platform targets two audiences: end users who want to use official plays on the device, and developers who want to build their own applications using AI coding tools. The README's orientation table presents a starting point for each: end users go to the getting-started guide and the official plays directory; developers go to AGENTS.md, the AI development guide, and the required skills list. The repository was last pushed on 2026-09-28. It is MIT-licensed. The firmware is open, and BSP APIs and non-UI logic are reusable across applications. ## The Hardware Baseline and the Mandatory UI Redesign Rule The main branch contains what the README describes as a minimal, runnable hardware-test baseline. This is not a finished application. The demo test menu and screens on main are hardware-capability tests, not an application UI. The README states an explicit, mandatory constraint: 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 the existing elements does not satisfy this requirement. BSP APIs, LVGL widgets, lifecycle patterns, and isolated logic can still be reused, but the UI must be built from scratch. This is a design decision, not a legal restriction. The README's stated rationale is that the current test menu is a capability demonstration, not a product, and applications built on top of it would ship something that looks like a hardware test, not a user product. The `components/bsp/` directory holds hardware logic and the `main/` directory holds application logic, and the README specifies keeping that separation in any derived application. ## Starting Development: Cloning and Reading AGENTS.md Clone the repository first: ```bash git clone https://github.com/FoloToy/ai-passport.git cd ai-passport ``` The intended development workflow then starts with an AI coding tool. The README instructs developers to open the repository in their AI coding tool and have it read `AGENTS.md`. The AI checks and installs five required skills from the `skills/` directory, then the developer describes what they want to build. The README provides guidance on writing a clear requirement: the user flow for each page, what each button press does, what state must survive power loss, whether networking or audio or Bluetooth is needed, and what acceptance criteria will be verified on real hardware. Build and environment setup details are in `docs/development/engineering/environment-setup.md` and `docs/development/engineering/build-and-test.md`, linked from the README. The `docs/reference/` directory holds an archive of previously built applications and recorded experience. The README directs developers to inspect this directory before starting, to avoid rebuilding patterns that are already documented. The demo branches serve a similar function: each `demo/*` branch shows one complete application and the specific patterns it demonstrates. Flashing the compiled firmware requires the developer's approval. The README notes that a merged `full.bin` is delivered for flashing at address `0x0`, and that a merged flash may reset stored data. ## The Demo Branches as Concrete Design References The repository includes five demo branches, each a standalone application that evolved from the main baseline. The README documents each branch along with the patterns worth studying. The `demo/stopwatch` branch shows a minimal timer application and the separation of pure logic from LVGL display code. The `demo/cat-themed-pomodoro-timer` branch covers monotonic time, pause and resume behaviour, NVS persistence across power cycles, a detailed product requirements document, and a state model. The `demo/rock-paper-scissors` branch addresses RGB565 image assets, asset-generation scripts, and Flash resource tradeoffs. The `demo/tetris-game` branch demonstrates a real-time game loop with low-latency input handling, partial display refresh, a pure game model, audio, and microphone interaction. The `demo/claude-buddy-port` branch is the most complex: it shows a complete application replacing the demo menu, including encrypted Bluetooth Low Energy, protocol parsing, state reduction, inter-task communication, and extensive host-side tests. The README describes this as the reference for developers replacing the demo menu with a full application. The README's guidance is explicit: new applications should branch from main and consult the relevant demo examples, not merge multiple demos wholesale. ## Limitations and What Developers Must Provide Themselves The repository does not include a traditional C API reference document or function-level documentation. The development interface is AGENTS.md plus the AI coding tool. Developers who prefer to read documentation before writing code will need to inspect the source directly in `components/bsp/` and `main/`. The README notes that a successful build is not hardware validation. Physical testing on a real device is required for any application before it is considered complete, and flashing requires explicit developer approval. There is no emulator or hardware-in-the-loop simulation documented in the README. Decisions involving new wiring, electrical safety, board revisions, or irreversible data formats require confirmation before the AI implements them. The README makes this a documented constraint rather than leaving it implicit. The repository has no GitHub releases. Developers tracking specific stable versions will need to rely on commit hashes. ## Comparison with Traditional Embedded Development Frameworks ESP-IDF, which is the build system this project uses (indicated by `CMakeLists.txt` and `sdkconfig.defaults`), provides a conventional embedded development framework with C APIs, example projects, and component documentation that does not require an AI coding assistant. A developer comfortable with ESP-IDF could work with this repository's BSP layer directly in C without using the AGENTS.md workflow, but the README is designed for the AI-assisted path. Arduino provides a higher-level abstraction for embedded development with a much larger library ecosystem and a code-focused workflow that does not involve AI assistants. Arduino targets a wider range of devices but does not provide the specific BSP abstractions and display integration that the FoloToy hardware requires. The FoloToy AI Passport's distinctive approach is treating the AI coding assistant as the primary development interface rather than an optional accelerator. The AGENTS.md file defines how the AI should interact with the repository, which is a design pattern not present in either ESP-IDF or Arduino. ## Conclusion Embedded developers who want to build custom applications for a wearable AI device and who are comfortable using AI coding assistants as the primary development interface will find FoloToy AI Passport well-suited. Developers expecting a traditional embedded SDK with documented C APIs and example code that runs without an AI assistant will face a steeper ramp: the intended workflow is to describe the application to the AI and let it implement from AGENTS.md. All application UIs must be fully redesigned from the baseline; reusing the existing test menu is explicitly prohibited. ## FAQ ### What is an AI passport? In the context of this repository, FoloToy AI Passport is the name of a wearable AI hardware device with an open firmware platform. Developers use it to build custom AI-powered applications on a compact wearable using an AI coding assistant as the primary development tool. ### Can I reuse the existing demo menu in my FoloToy AI Passport application? No. The README states explicitly that the current demo test menu and screens must not be reused in derivative applications. Every application must redesign and implement its own UI. BSP APIs, LVGL widgets, and isolated logic remain reusable. ### Does FoloToy AI Passport require an AI coding assistant to develop? The intended workflow uses an AI coding assistant that reads AGENTS.md and the required skills. The README does not provide a traditional API reference for working without one, but the source code in components/bsp/ and main/ is available for direct inspection. ## Sources - [FoloToy/ai-passport on GitHub](https://github.com/FoloToy/ai-passport) - [Issues](https://github.com/FoloToy/ai-passport/issues) - [License: MIT](https://github.com/FoloToy/ai-passport/blob/main/LICENSE) - [Project website](https://ai-passport.folotoy.cn) - [README](https://github.com/FoloToy/ai-passport/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/folotoy-ai-passport