FoloToy AI Passport: an ESP32-C3 firmware baseline for wearable AI agents

What FoloToy AI Passport solves, and for whom

Most wearable AI projects start with a schematic and an empty firmware tree. FoloToy AI Passport starts one level higher: the repository is the firmware development baseline for a specific board, described in the README as an ESP32-C3 with 8 MB Flash, no PSRAM, a 240 by 320 display, three physical buttons and ES8311 audio. Board support, working examples, AI workflows and validation tools sit in one tree, so the first problem it removes is bring-up: display, buttons, audio and battery already have a board support package under components/bsp.

The intended reader is someone who will write an application on that board, not someone who wants to buy a finished gadget. The README points device users at the getting-started guide and the official plays on the project website, and points builders at AGENTS.md, the AI development guide and the skills directory. The repository also assumes an AI coding tool is in the loop: the first development step is to open the repository in that tool and have it read AGENTS.md, then let it check and install the required skills. That is an unusual assumption for a C firmware repository, and it shapes the whole contribution model. If you write firmware by hand and dislike agent-oriented documentation, you will spend the first hour ignoring half the README.

How the firmware is laid out: BSP, main and demo branches

The repository splits hardware logic from application logic, and the README states that split as a rule: keep hardware logic in components/bsp and application logic in main. The board support package exposes headers such as bsp_display.h, and the README lists display, buttons, audio and battery as the reusable surface. Above that, main holds the runnable baseline, including a test menu and demo_*.c pages that exercise hardware capabilities.

Demo branches are the second mechanism. Each demo/* branch evolves the baseline into an independent application, and the README describes them as design cases rather than a feature pile: they show how a specific problem was solved. New applications are expected to branch from main and consult the relevant examples instead of merging several demos wholesale. The baseline itself is built with CMake, partitions.csv, sdkconfig.defaults and a locked dependency set in dependencies.lock, with tests in tests/ and helper scripts in tools/.

The constraint that matters most is stated in a callout: main is a minimal, runnable hardware-test baseline, not a finished application. The test menu and its screens are hardware-capability tests, and the README prohibits reusing them as an application UI. Renaming or recoloring them does not count. BSP APIs, ordinary LVGL widgets, lifecycle patterns and isolated logic remain reusable, so the boundary is the interface shell, not the plumbing.

Setting up ESP-IDF 5.5.3 and getting a first build

The README badges the toolchain as ESP-IDF 5.5.3 and links environment setup to docs/development/engineering/environment-setup.md, with build and test steps in docs/development/engineering/build-and-test.md. Those two documents are where the exact commands live; the repository does not restate them in the README. What the README does give is the shape of the work: prepare the environment, build and test on the host, then validate on the device.

A first real use is to clone the repository and let an AI coding tool read the agent instructions, which is step one of the documented workflow:

git clone https://github.com/FoloToy/ai-passport.git
cd ai-passport

From there the README tells you to have your tool read AGENTS.md and install the five required skills listed in skills/README.md, with whatever permissions your environment needs. The requirement you then describe becomes the application. The README supplies a copyable prompt for an offline habit-tracking application that uses the three buttons and the 240x320 display, preserves records across power loss, branches from main as feature/*, and keeps hardware logic in components/bsp and application logic in main. The prompt also instructs the assistant to report build results, unexecuted device checks and on-device acceptance steps separately, which tells you what a finished delivery is expected to contain.

The README is explicit that a successful build is not hardware validation. Flashing requires your approval, and the deliverable for flashing is a verified merged full.bin written at address 0x0. It also warns that no original-firmware backup is required but a merged flash may reset stored data, and links the flashing policy in docs/development/engineering/firmware-layout.md. Read that page before you flash anything you care about.

Where the baseline gets in your way

The mandatory UI redesign is the sharpest limitation, and it is deliberate. You cannot ship the baseline screens, and the README closes the obvious loopholes in advance: renaming or recoloring the test menu does not satisfy the rule. If your goal is a quick demo that looks like the reference hardware, this repository is the wrong tool, because the reference UI is exactly what you are told not to use. Budget LVGL work from the start.

The hardware ceiling is the second constraint. The board has 8 MB Flash and no PSRAM, so everything the application holds in RAM competes with the display buffers and audio path. The README lists Flash and data usage as a constraint worth stating in your requirement, which is a hint about where projects fail. An application that wants large asset sets, long recordings or a rich animation layer will feel that ceiling quickly.

There is also no release history to lean on. No releases were retrieved for this repository, so there is no tagged version to pin and no changelog describing what changed between builds. You are tracking main or a demo branch. The README's own framing supports that: main is a baseline that moves, and demo branches are separate evolutions rather than a versioned product line. Teams that need a frozen artifact will have to create one themselves. Finally, the AI-tool workflow is a dependency, not a convenience. If your environment cannot install the skills or grant the permissions they request, steps one and two of the documented path do not complete, and you are back to reading the engineering docs and doing it manually.

Alternatives: vendor SDK examples versus a board baseline

The closest alternative is not another wearable firmware but the vendor stack underneath it: Espressif's ESP-IDF examples plus the component registry, or a board vendor's own demo firmware. The difference in approach is scope and opinion. ESP-IDF examples isolate one peripheral at a time, with no opinion about display, audio and buttons coexisting, no partition layout for a merged image, and no rules about what a derivative application may reuse. FoloToy AI Passport is the opposite: it is opinionated about structure, it ships a working combination of display, buttons, audio and battery on one board, and it enforces a separation between components/bsp and main.

That opinionation is why the UI rule exists. A vendor example is a snippet you copy and forget; this repository is a baseline you are expected to keep clean, which is why the README treats the test menu as scaffolding rather than a starting design. The trade-off is real: if you only need to blink an LED or read one sensor on an ESP32-C3, the vendor examples are smaller and carry no conventions to satisfy. If you are building a wearable with a screen, three buttons and audio, the baseline saves bring-up work that the examples do not cover. If you have already standardized on a different RTOS or a different display stack, adopting this baseline means adopting its BSP and LVGL assumptions along with it.

Maintenance, upgrades and the MIT licence

The repository is not archived, and its last push was on 2026-09-17, so the tree is current. That said, there are no retrieved releases, so upgrades are commits rather than versions. The practical consequence is that you should treat dependencies.lock as the thing that pins your build and expect to read diffs when you move forward, because there is no changelog to summarize them for you. The tools/ and tests/ directories exist precisely so that a move can be checked: the README's workflow runs host tests and produces a verified merged image before anything reaches a device.

The licence is MIT, which is permissive and places few conditions on redistribution or modification. This article is not legal advice, and there is one detail worth checking yourself rather than assuming: the README links /LICENSE for the licence badge, so confirm which files the licence text covers in your checkout before you redistribute a merged firmware image or vendor assets from assets/ and docs/. The README does not document rollback. It states that no original-firmware backup is required, but also that a merged flash may reset stored data, so if you need to return a device to a previous state, that procedure is not described here and you should decide your own before flashing.

Editorial conclusion

Adopt FoloToy AI Passport if you write firmware for ESP32-C3 hardware and want BSP APIs, working demos and host tests as a starting point instead of an empty project. Do not adopt it if you want a ready-made wearable application: the README states that main is a minimal hardware-test baseline, that the demo menu and screens are capability tests, and that every derivative application must redesign its own UI. Before committing, verify the board revision and pin map in the hardware guide against your own unit, confirm that ESP-IDF 5.5.3 is the version your toolchain resolves, and read the flashing policy in docs/development/engineering/firmware-layout.md, which states that a merged flash may reset stored data.

Frequently asked questions

Official sources

1. FoloToy/ai-passport on GitHub
2. Issues
3. License: MIT
4. Project website
5. README