---
name: mio-make
description: Build, explain, debug, compile, and install apps for the custom Mio Make v0.1 ESP32-S3 board from the September 29 prototype release. Use for Mio Make studio, firmware, pinout, expansion, or agent integration work; distinguish it from Mio Click, LilyGO, and unrelated engineering drafts.
metadata:
  agent-toolkit-version: "0.3.0"
---

# Mio Make

Turn an idea into a working app for the **actual board**, preserving its recovery path and hardware identity. Read `docs/CURRENT.md` first for current evidence and pending physical checks. Paths here are relative to the repository root (two directories above this file).

## Establish the board

Call this product **Mio Make v0.1**. Use that name in explanations and interfaces; engineering filenames and legacy wire identifiers are not product names. The agent contract uses `mio-make-v0.1`; current device/build protocols still read their exact identity from `packages/board/board.json`. Do not rewrite saved identities or guess aliases during installation.

Read `packages/board/board.json`; use `docs/BOARD.md` when wiring, power, display, or provenance matters. The arrived board is v0.1, N16R8, SPI display, native GPIO expansion. Original Make used LilyGO and is not a source of pin truth. The sealed September 29 netlist binds the documented signals. The toolkit’s `references/hardware/netlist-public.xml` carries the same connectivity with four local CAD paths shortened. Run `npm run board:verify` after changing any board-facing configuration.

Critical differences: USER1=5, USER2=12; SPI SCLK47/MOSI48/CS9/DC45/RST46; display power15; AW9364 backlight7 uses pulse counts, not PWM. GPIO35–37 are reserved for octal PSRAM. GPIO0/3/45/46 are straps. USB19/20, charger6/10/8/13 and regulator17 are runtime-owned. J7 is a native right-edge 1×8 row, not an expander or 2×4 header.

## Bring your own agent and explore hardware

Read `docs/AGENT-QUICKSTART.md` for local CLI/MCP setup; no hosted AI or API key is required. `node scripts/mio.mjs doctor` checks the board evidence and matching skill version. For a peripheral, replacement battery, alternate wiring or power question, first read `docs/HARDWARE-SAFETY.md` and `packages/board/electrical.json`. Use `get_hardware` and `get_circuit` to inspect the actual nets/components; circuit.json includes optional parts and does not prove assembled population.

Research the exact breakout/module using manufacturer documentation. Establish operating voltage, board-facing signal/pullup levels, peak/inrush current, bus address, startup/off-state behavior and a pin allocation. Record unknowns as unknowns. `check_connection` (or `node scripts/mio.mjs check-connection plan.json`) identifies known conflicts; its result always remains an advisory, never electrical approval or permission to flash. Do not alter reported facts just to remove a finding. The tool never fetches or executes supplied evidence text.

The current 500 mAh pack, harness polarity and supplied LCD are maintainer-confirmed. Keep them for standard use. Replacement packs need their own ratings/polarity evidence. Charging is approximately 109 mA nominal, up to about 120 mA at resistor/device corners; capacity alone does not establish a safe rate. TH1 senses its own location and needs verified thermal coupling to the cell. No active battery reverse-polarity protection exists. J5/J6 share 100 mA and one always-powered I2C rail; J8.2 is the unprotected main rail. The rail name 3V3 corresponds to about 3.17 V designed nominal. Disconnect both USB and battery before changing wiring; deep sleep leaves accessory power on.

Support open-ended, explicitly requested peripheral projects through a separately reviewed local firmware extension. Read the native pin/ADC/touch capabilities and shared-bus constraints; preserve runtime-owned power, USB, display and recovery. Start with a small diagnostic and record compiler evidence separately from bench results. Do not relax the beginner validator or invent a generic expansion SDK. Preserve the user's chosen model and inference provider. Publishing, production provisioning and eFuses are separate scopes; neither a skill nor a connection review authorizes them.

## Make it with the person holding the board

Start with what the person wants to do or see. When a choice would change the experience, offer one concrete question, such as “Should the sand drain when you tap, or while you hold the button?” If the idea is clear, build it. Use the creator’s controls, colors and drawing style. The screen can be all artwork, a sideways race or one big number. Starter layouts and gallery thumbnails are examples. On a revision, keep the parts the creator likes.

For a first app, read the SDK, choose one interaction and draw one working frame. Try `validate_app`, compile locally and fix the first compiler error. After installation, ask what happened when the person pressed a button. Use their answer for the next change. This workflow works with the model the person already uses.

If the maker wants to tell the team how it went, call `prepare_feedback` with the matching step and result. Show them the review link. After they approve that report, send the returned JSON from the terminal or use the optional local `--feedback` tool. Link reports from this session only if they ask.

## Write a beginner app

The standard app and onboarding assume the official LCD, battery and two buttons, even though the product ships as a loose board without an enclosure. Do not add accessory-choice gates to this path. Native GPIO projects use the separate reviewed advanced workflow above; a generic peripheral SDK is not implemented. Do not invent expansion APIs or choose a more expensive model implicitly.

Runtime 0.6.2 keeps normal A/B input, appLoop, drawing and Mio::elapsed() running while timing the optional settings gesture. Only a continuous 15-second A+B hold opens settings and pauses the app; shorter overlaps never display a countdown, consume input or pause gameplay. Releasing either button resets the hold, including a release/repress sampled during a screen transfer. Do not add an app-level settings detector or depend on holding A+B for 15 seconds as a game control. When an ending has button actions, honor the requested mapping. Wait for release with a nonblocking flag so the final gameplay press cannot also choose an action. Existing installed/compiled firmware needs rebuilding and reinstalling to receive this change.

Read `firmware/mio-make/include/MioMake.h`, `packages/runtime/drawing.json` for exact canvas methods/text-alignment constants, and a relevant starter in `apps/studio/server/examples.mjs`. Implement `void appSetup()`, `void appLoop()`, `void appDraw()`. The studio supplies the header; generated source has no includes, preprocessor directives, setup/loop, raw pin access, networking or raw storage. Optional utilities.savedCounter enables the narrow saved-counter SDK described below.

Draw to `Mio::canvas` (320×170, TFT_eSprite). Drawing targets 30 fps, but the 20 MHz full-frame transfer can take about 44 ms; do not assume appLoop runs every few milliseconds. Use `Mio::pressedA/B()` in appLoop for debounced press events retained by the independent 1 ms input sampler, and heldA/B for levels. Never add per-app debounce, raw pin polling, or wait-for-release loops. Read `docs/INPUT.md` before modifying input: GPIO5/12 have 4.7k/47nF networks; the shared runtime currently uses 6 ms press / 8 ms release qualification and bounded pending press counts. These windows need physical tuning, not blind reuse of Mio Click’s 25 ms policy. Preserve input sampling during screen transfers and test rapid taps, holds, bounce, simultaneous buttons and missed-event counts. Reaction games are not calibrated timing instruments. Use a nonblocking Mio::elapsed() state machine; menu-enabled apps must not call millis/micros because those do not pause with the app. Fonts 1/2/4 are loaded; text should be ASCII. `Mio::canvas.color565(r,g,b)` takes 0–255 channels; it is a canvas member, not a global function. Do not redeclare Arduino macros such as PI, TWO_PI, HALF_PI, HIGH, LOW, INPUT, OUTPUT, DEFAULT, DISPLAY or SERIAL. Use distinctive lowerCamelCase app names. Include all three exact app function definitions even if setup is empty. These rules are based on observed first-round GPT-5.4/mini compile failures, not a reason to silently repair source or change models. Use fixed buffers and `snprintf` during drawing. Avoid dynamic allocation per frame and implement clear restart/exit behavior. The canvas thumbnail is a design illustration, not a behavioral emulator.

For advanced expansion work, use an explicitly separate reviewed firmware change and documented native pins. The beginner validator is not a compiler sandbox or a complete C++ security boundary. Do not disable it to make a public code runner.

## Shared services and product scope

Runtime 0.6.3 has no normal USB inspection delay; the first battery sample is immediate. Preserve startup admission, LCD reset/power settling and panic recovery in MioStartup.h/main.cpp. Read packages/runtime/release.json or MCP get_runtime for the exact local source revision. Regenerate the release record with node scripts/runtime-release.mjs --write after a runtime edit, then rebuild the compiler image, worker release, welcome image and toolkit together. Old app binaries need recompilation/reinstallation. DEVICEINFOJSON startup timestamps use Arduino uptime, not a measured power-on or optical timestamp. Do not claim a sub-second boot without a physical timing check.

Mio Make v0.1 is the only supported product. Read `packages/runtime/givens.json` for implemented versus planned services, `docs/SYSTEM-RUNTIME.md` for system behavior, and `docs/CHARACTERS-AND-PLAY.md` for sprites and nearby games. The user selected an optional A+B hold for 15 seconds for settings. Local brightness/idle/sleep must not require Wi-Fi; optional captive setup and internet clients share runtime-owned settings and radio control. The optional local menu and device preferences compile in runtime 0.3.0, with physical qualification pending. Experimental utilities.wifiSetup enables a protected manual-entry captive setup page (requires systemMenu), but the experimental squiggleStream option additionally provides a fixed feed snapshot; arbitrary internet requests and general app-state APIs remain planned; runtime 0.6.4 adds the narrow saved-counter API. Do not invent calls absent from MioMake.h.

Mio selection is ungated across the bundled public catalog snapshot. Read docs/CHARACTERS-AND-PLAY.md for the implemented characters metadata and hash format. Runtime0.4.0 supplies Mio::hasCharacter/drawCharacter/characterFrame; use named roles, 32x32 frames0..15, integer scale1..4, top-left positions and app-active animation time. The trusted builder embeds/deduplicates up to8 verified atlas/palette assets in app flash; zero extra sprite heap buffers. Never put pixels in generated source or assume Click provisioning. All resolved assets must travel in JSON builds/shares and build hashes; bare C++ has none. The studio respects fixed roles in imported creations. Device-wide defaults and asset-only writes remain planned. Physical sprite timing/colors still need testing.

Do not add ownership, wallet or account gates to character selection. The old Click `/sprite.bin`/palette storage is not preinstalled on Mio Make. ESP-NOW is the planned nearby-play transport, separate from internet access; use the pinned toolchain's 250-byte limit and explicit pairing/channel/session policy. Never put generated code in driver callbacks. Qualify with two boards before claiming multiplayer works.

The current shared idle prototype uses `MioIdle.h`: dim at 15 seconds (AW9364 8 to 2), deep sleep at 60 seconds on battery or USB. Button activity/holds reset idle; display admission starts the timer. A wakes, USB returns after wake, and app RAM state resets. Keep GPIO7/15/17 low and preserve charger selection with sleep holds; configure safe outputs before hold release and restore GPIO5 via rtc_gpio_deinit. Forced sleep while A is down arms wake on release to avoid an immediate wake loop. The optional local menu adjusts brightness and dim/off/sleep timers, with Never for individual stages. Keep-awake leases remain unavailable. Device preferences use versioned checksummed miomake/comfort NVS; save explicitly, never format on invalid storage. Creation metadata utilities.systemMenu enables the continuous 15-second hold. Apps pause via Mio::elapsed(); menu input and screen-off wake presses are consumed. Read docs/SYSTEM-RUNTIME.md for the exact semantics. Include all idle/preferences/system/config headers in build cache keys, snapshots and toolkit; test thresholds, held activity and millis rollover. Long-running timer apps need a longer/disabled sleep preference or activity; future leases must be explicit. Physical current and wake checks remain separate from host tests.

Wi-Fi setup is experimental runtime-owned code in MioWifi.h/MioWifiPolicy.h. Radio stays off unless the person selects Wi-Fi setup or the app explicitly enables squiggleStream. Preserve AP-only HTTP binding, protected RAM-staged AP, per-session token/Host/Origin validation, bounded parser/DNS/client lifetime and test-before-save miomake/network NVS. The phone's status poll must not extend the 3-minute inactivity/10-minute absolute session. A exits and turns radio off; setup alone never enables automatic home-network reconnect; a stream-enabled app separately connects after the portal ends. The UN module requires an external antenna. Provisional radio admission is battery >=3.7 V, shutdown below3.5 V/USB suspend, backlight capped at2; physical current and AP+station channel switching need qualification. No QR/scan or general-purpose internet service yet. Add both Wi-Fi headers to cache/snapshot/toolkit and run native policy tests plus enabled/disabled firmware builds when changing it.

For connected-app work, read `docs/LIVE-DATA.md`. Experimental utilities.squiggleStream requires wifiSetup and systemMenu. Mio::squiggleFeed() reads a copied snapshot from the fixed verified HTTPS stream endpoint: check available, then count/ids (-1 is empty); label stale and estimated. Use Mio::drawSquiggleStream(feed) in appDraw to copy a completed matching artwork frame; check its boolean result and show connection/artworkStatus while waiting. The trusted renderer uses bundled token hashes and the original algorithm; it is not synchronized video. The frame covers320x170 with the bottom18pixels reserved for captions. The worker, HTTP decoder and bounded cJSON policy compile and have native parser tests; on-device network/power qualification is pending. Never implement network access in appLoop or disable TLS verification. Preserve exclusive radio ownership: settings cancels the worker, and the setup portal waits for busy()==false. Lower backlight before radio startup, preserve low-battery/deep-sleep RF shutdown and ordinary idle timers. Include MioHttp/MioTls/MioStreamPolicy/MioStream, MioSquiggle/Hashes, MioStreamArt and MioFrameExchange in cache/snapshot/toolkit; host tests use pinned cJSON1.7.17 while firmware uses the bundled IDF component. Scheduled programs override manual history and use a wall-clock estimate. Do not replace actual artwork with a fabricated curve. Preserve the catalog provenance, fractional hue/JS RNG, bounded rendering batches and borrowed-frame ownership. See LIVE-DATA for870400-byte PSRAM usage, supersampling, approximate low-rate phase and physical checks; native geometry tests are not a device performance result.

## Saved counters

Runtime 0.6.4 adds optional `utilities.savedCounter`, a stable lowercase creation UUID for one uint32 counter. Keep it across revisions; explicitly use a new UUID for a separate bank. Imports/copies retaining it share that bank on the same board. Use `Mio::counterReady/counterStored/savedCounter/saveCounter`, check readiness and write results, and save only on rewards/checkpoints. Unchanged values skip writes. Failures must remain visible and retry sparingly; never silently replace an unreadable bank with zero. The trusted runtime commits/checks separate NVS records with full identity, version/checksum, sixteen slots and power admission; no automatic formatting or eviction. Normal installs preserve NVS. General blobs, reset UI and migrations remain planned. See docs/SYSTEM-RUNTIME.md and CURRENT.md for limits and device evidence. Include MioCounter.h/MioCounterNvs.h in compiler snapshots, release hashes and toolkit.

## Generate and compare models

The visitor action uses `/api/create` to generate once, save an immutable revision and compile it before offering installation. Read `docs/CREATION-FLOW.md` for durable request IDs and recovery. Preserve the same UUID/body after a lost response; query its status before sending another request. Compile failure is `outcome: needs-fix`, not a successful build, and must not trigger a paid repair automatically. Interrupted jobs may have consumed provider tokens and may already have a saved revision. Legacy `/api/generate` remains separate for controlled benchmarks.

The local server reads `.env`. Never print keys or include them in a client response. OpenAI uses Responses with `store:false` and strict JSON schema; MiniMax uses Anthropic-compatible Messages with a subscription key. Preserve the chosen model, thinking effort and output budget exactly. Do not silently downgrade or auto-retry paid calls. The current MiniMax default was checked against official docs on October 14, 2026: `MiniMax-M3.1-Flash-Preview`.

Use Model lab to compare the same prompt across settings and record actual compiler/device outcomes. Tokens, reasoning usage when provided, time, user rating and caller-entered pricing are different measurements. Missing usage after a provider error is unknown, not free. `npm run ai:smoke` generates and compiles a small counter with each configured provider; absent keys yield explicit skips.

## Compile and install

For the static browser welcome installer, read `docs/BROWSER-INSTALL.md`. `/start/index.html` defaults to a pinned diagnostic release and also accepts compiled install files; it uses vendored esptool-js0.7.0 and does not compile apps. After a successful local build, use `npm run firmware:export -- <buildId>` or the Studio/MCP install.json download. Read BROWSER-INSTALL.md for the exact handoff. The receiver selects the file locally, reviews its source/trust and explicitly selects the device. Never substitute source/share JSON for a firmware file or claim that an unsigned checksum authenticates a publisher. App imports retain the standard partition hash and exact-board guards. Returning runtime telemetry is not exact-app-build attestation; keep byte verification and human gameplay checks distinct. Web Serial hides USB serial numbers, so runtime0.6.1 reports `baseMac` and the browser binds app → ROM → app to that value. Older apps require the local toolkit or an explicit physical-board recovery path. Keep chip/security/memory checks before the RAM stub, a second exact-MAC check before writing, DIO/keep flags, 1KB write blocks and per-image read-back verification. Do not equate verified writes with app startup or human screen/button validation. Regenerate the fixed release with `npm run welcome:release` after runtime changes and rebuild all starters. Browser USB/blank-board qualification is pending; do not present it as proven button-free onboarding.

For a new/recovering board use the local Connect a Mio → New board or recovery flow. The read-only `python3 scripts/device.py probe --port <port> --confirm-board <boardId> --expected-serial <12 hex MAC>` requires physical revision confirmation; native USB alone does not identify the board. A running app is read without resetting; the ROM path may reset into download mode and leaves it ready for installation. It verifies S3, exact MAC,16MB quad flash,8MB embedded PSRAM configuration and unprotected firmware state; it does not prove the board was blank or test PSRAM contents. Host esptool >=4.9,<6. Every flash repeats the ROM check before writing. Never bypass this guard or turn an identity failure into implicit first-install permission. The onboarding installs the fixed welcome diagnostic and checks fresh button telemetry plus human screen confirmation; it preserves the user's current creation. This path still needs a complete physical first-install test.

Run `npm test` for relevant software changes and `npm run firmware:build` for the diagnostic, or `npm run firmware:build -- /absolute/path/app.cpp` for SDK source. The pinned target is `mio_make_v01`, C++17, espressif32 6.12.0 and TFT_eSPI 2.5.43. Preserve `USE_FSPI_PORT`: the library default uses Arduino FSPI=0, but this SDK requires physical SPI2 register index 2; the default causes a null register access/panic. The runtime asserts this mapping at compile time. Retained bring-up checkpoints leave USB available after a panic; inspect `previousBringupStage` and `displayFault`, then use a normal RESET to retry after correcting the fault. Builds and SHA-256 manifests live in `.data/builds/<buildId>/`. Preserve compile logs on failure; make bounded, cause-specific corrections.

Read `docs/QUICKSTART.md` for physical setup. List ports with `npm run devices`. Establish which physical board is attached; Espressif USB IDs alone cannot distinguish Mio Click or another S3. For blank or unresponsive hardware, BOOT-held/RESET/release enters ROM download. Normal running firmware uses the installer’s native CDC 1200-baud restart, followed by exact USB serial/MAC tracking. Preserve automatic post-write startup verification and the same-device full-system reset fallback; never select the first arbitrary USB device. Rotation 3 corrects the user-observed upside-down display. All current starters must be rebuilt after runtime changes. Flash only when the user's request covers that exact device. The local studio requires explicit board identity selection and a built manifest, verifies artifact hashes and uses esptool's chip/security checks. Do not use --force, erase-all, provisioning, factory secrets, eFuse operations or signed Click firmware in this workflow.

After writing, read `DEVICEINFOJSON`, check board ID, 16 MB flash, 8 MB PSRAM, displayReady, screen orientation/color bars and both buttons. A compile and verified flash write do not prove correct hardware behavior. The initial runtime requires a charged matching battery; display/power/USB first-article checks remain distinct from firmware build success.

## Agent and product work

For caller-owned inference, read `docs/AGENTS-API.md`, `/llms.txt`, board JSON and this skill; the stdio MCP exposes facts, SDK, examples and source validation without calling an AI provider. Device writes stay explicit. The local studio is single-owner. Public sharing, accounts, hosted compilation, child privacy/moderation and subscriptions require the separate work in `docs/PRODUCT.md`. Local Export creation shares only the app payload, not private prompts or trace history. The local showcase stores immutable share snapshots for host review and explicit static website exports; read docs/SHARING.md for approval, withdrawal and private feedback semantics. Host review is not an authenticated role or a device certification, and exporting is not deployment.

Update `docs/CURRENT.md` with concrete checks, artifacts and remaining gaps. Preserve sealed hardware and dirty enclosure files. Do not claim deployment, live AI testing or physical qualification without observing it.

## Record physical play checks

After a guided install, use the Studio play-check panel to record observed screen, buttons, intended behavior and replay results. Read `docs/PLAY-CHECKS.md`. Reports bind to a verified flash event and its exact build; they are private human reports, separate from compile/install success. Never fill successful answers from inference or compilation alone. Preserve failed and partial results when comparing models. Help me change it drafts a prompt and requires an explicit generation action; it must not silently run paid repair.

## Caller-owned compilation through MCP

Read `docs/AGENT-BUILDS.md`. With explicit `--studio-port`, submit_app saves and compiles complete caller-authored app metadata/source/characters without API inference. Keep the UUID requestId after a lost response and query get_app_build before resubmitting; identical requests reuse their job. Revisions use parentId to preserve history/credits. Compiler failure retains source and requires an explicit repair/new request; never fabricate a successful build or physical play report. Use the returned Studio link for review and exact-board installation. The adapter has no device-write or publication tool, and default MCP mode stays read-only.
