[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81938":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":17,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":22,"topics":23,"createdAt":10,"pushedAt":10,"updatedAt":39,"readmeContent":40,"aiSummary":41,"trendingCount":13,"starSnapshotCount":13,"syncStatus":42,"lastSyncTime":43,"discoverSource":44},81938,"Pixel-Pets","marceld23\u002FPixel-Pets","marceld23","Pixel-Pets: A local, open-source virtual pet ecosystem on M5Stack. 100% AI-authored C++ (Claude) by a 10yo maker. Includes Muffin (LLM), Visu & Goo-Goo variants + companion device Pip. Built for privacy, education, and offline play.","",null,"C",24,0,23,5,1,3,42.6,"Other",false,"main",true,[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38],"digital-pet","embedded","esp-now","esp32","iot","kids","m5stack","maker","offline-ai","open-source","platformio","qwen","tamagotchi","virtual-pet","whisper","2026-06-12 04:01:36","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Flogo.jpg\" alt=\"Pixel Pets logo\" width=\"220\">\n\u003C\u002Fp>\n\n# 🐾 Pixel Pets\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets\u002Fstargazers\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Fmarceld23\u002FPixel-Pets?style=social\" alt=\"GitHub stars\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"#highlights\">Highlights\u003C\u002Fa> ·\n  \u003Ca href=\"#fastest-start\">Fastest start\u003C\u002Fa> ·\n  \u003Ca href=\"#for-parents\">For parents\u003C\u002Fa> ·\n  \u003Ca href=\"#for-makers\">For makers\u003C\u002Fa> ·\n  \u003Ca href=\"#documentation\">Documentation\u003C\u002Fa> ·\n  \u003Ca href=\"#support-the-project\">Support the project\u003C\u002Fa> ·\n  \u003Ca href=\"#contributing\">Contributing\u003C\u002Fa> ·\n  \u003Ca href=\"#version-history\">Version history\u003C\u002Fa>\n\u003C\u002Fp>\n\nA family of virtual pets on M5Stack hardware. **Three pet variants** — **Muffin** (CoreS3 + LLM), **Visu** (CoreS3 alone), **Goo-Goo** (Core2) — plus one optional **accessory**, **Pip** (M5StickC PLUS2), which acts as a pocket-sized companion device for any of the bigger pets. One source tree, five build envs (`cores3` \u002F `visu` \u002F `core2` \u002F `pip` \u002F `pip-s3`). Pet logic, animations, mini-games, ESP-NOW friends and weather\u002Flocation are target-agnostic; voice and the front camera are CoreS3-only.\n\n**Version 1.0.3** — small follow-up to 1.0.2 fixing a Pip-S3 deep-sleep wake bug + correcting the S3 download-mode docs for the K150 hardware. See [Version history](#version-history) at the bottom for the per-version scope.\n\n> **👨‍👦 A note from the makers**\n>\n> Pixel Pets started as a Sunday afternoon between a dad and his 10-year-old son, Justus, sitting on the sofa together. Every line of firmware was co-authored with Claude (Anthropic) under our direction.\n>\n> Justus checks the GitHub star count on Sundays. If you think a 10-year-old shipping a kid-safe AI pet on real M5Stack hardware is cool, [**drop a ⭐**](https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets) and make his weekend. The full story is in [`CREDITS.md`](CREDITS.md).\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fphotos\u002Fphoto_pets.jpg\" alt=\"Pixel Pets family — Muffin, two Goo-Goos and a Pip\" width=\"640\">\u003Cbr>\n  \u003Cem>The whole family on the desk: Muffin showing the dog pet, two Goo-Goos showing the bear and cat, with a Pip on the Tricks page in front.\u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"assets\u002Fvideo\u002Fdemo-en.mp4\">\n    \u003Cimg src=\"assets\u002Fvideo\u002Fdemo-en-cover.jpg\" alt=\"Pixel Pets demo (10 s, click to watch)\" width=\"320\">\n  \u003C\u002Fa>\u003Cbr>\n  \u003Cem>10 seconds with a Goo-Goo on the desk — click the cover to watch (1.5 MB MP4). German-captioned variant at \u003Ca href=\"assets\u002Fvideo\u002Fdemo-de.mp4\">demo-de.mp4\u003C\u002Fa>.\u003C\u002Fem>\n\u003C\u002Fp>\n\n## ⚡ 2-minute feature reel\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.youtube.com\u002Fshorts\u002FjGS-yNJveYc\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.youtube.com\u002Fvi\u002FjGS-yNJveYc\u002Fmaxresdefault.jpg\" alt=\"Pixel Pets feature reel (2 minutes, click to watch on YouTube)\" width=\"240\">\n  \u003C\u002Fa>\u003Cbr>\n  \u003Cem>2 minutes in action — voice control on Muffin, gift exchange between two pets via ESP-NOW Friends mode, and a Pip wrist-flick treat throw. Click to watch on YouTube.\u003C\u002Fem>\n\u003C\u002Fp>\n\n## 🎥 Project Deep-Dive\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fyoutu.be\u002F2V9dgzdXCR8\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.youtube.com\u002Fvi\u002F2V9dgzdXCR8\u002Fmaxresdefault.jpg\" alt=\"Pixel Pets Deep Dive (7 min, click to watch on YouTube)\" width=\"640\">\n  \u003C\u002Fa>\u003Cbr>\n  \u003Cem>A 7-minute deep dive into the project, safe hardware for kids, and how 10-year-old Justus built this with Claude AI. Also available \u003Ca href=\"https:\u002F\u002Fyoutu.be\u002FiCOyaJQFdys\">in German\u003C\u002Fa>.\u003C\u002Fem>\n\u003C\u002Fp>\n\n## Pick your pet animal\n\nEach device renders the same set of animals — **Bear, Cat, Dog** — chosen on first boot (and changeable later in Settings). Real screenshots from a Goo-Goo (Core2):\n\n| Bear | Cat | Dog |\n|:---:|:---:|:---:|\n| ![Bear](screenshots\u002Fpet_bear.png) | ![Cat](screenshots\u002Fpet_cat.png) | ![Dog](screenshots\u002Fpet_dog.png) |\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Fphotos\u002Fphoto_goo-goo_bear.jpg\" alt=\"Goo-Goo close-up showing the bear pet on a meadow scene\" width=\"380\">\u003Cbr>\n  \u003Cem>Goo-Goo on a meadow scene — what the bear looks like through a phone camera.\u003C\u002Fem>\n\u003C\u002Fp>\n\n**Where to find Pixel Pets:**\n\n- 🐻 [**Live landing page**](https:\u002F\u002Fmarceld23.github.io\u002FPixel-Pets\u002F) — short intro, real-hardware video and an overview of all variants. Source under [`site\u002F`](site\u002F), deployed via GitHub Actions on every push.\n- 🛠️ [**Build write-up on Hackster.io**](https:\u002F\u002Fwww.hackster.io\u002Fmarcelduetscher\u002Fpixel-pets-an-ai-assisted-virtual-pet-family-for-m5stack-baa76c) — the assembly story, build photos and Q&A in the maker-community format.\n- 💻 [**Source on GitHub**](https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets) — you're already here.\n\n## Highlights\n\n- **Three animals × three pet variants** — pick **Bear \u002F Cat \u002F Dog** on first boot (changeable later in Settings), running on **Muffin** (CoreS3 + LLM), **Visu** (CoreS3 alone) or **Goo-Goo** (Core2). Same source tree.\n- **World-aware pet** — at boot the device looks up your **location** (IP geolocation via ip-api), pulls **real weather**, **sunrise \u002F sunset times** and the **moon phase** from open-meteo, and adapts the scene to the actual time of day at your location: pale-blue **Morning** sky → clear **Day** sky → muted **Evening** dusk → dark **Night** with a crescent moon. The sun and clouds tint with the same phase. All cached in NVS so it survives reboots offline.\n- **Battery-backed clock + NTP sync** — wall-clock time is synced once a day over Wi-Fi and persisted by the RTC in between, so the time-of-day rendering and the parental session limit work even with no network on a given day.\n- **Voice control** *(Muffin only)* — wake word **\"Muffin\"**, offline **Whisper** speech-to-text + **Qwen3-0.6B** intent classifier running on the Module-LLM expansion. Plain sentences (\"eat something\", \"let's dance\", \"turn on the radio\") trigger matching actions. No cloud, no audio leaves the device.\n- **Front camera + selfies** *(Muffin \u002F Visu)* — proximity-wake when you walk past, photo button overlays the pet on a selfie, 5-slot LittleFS gallery with delete.\n- **ESP-NOW Friends + Pip accessory** — two pets in range pair with a synchronised tap and exchange gifts \u002F hearts \u002F food \u002F toys over ESP-NOW (no router needed). The optional **Pip** (M5StickC PLUS2) acts as a pocket-sized treat thrower: pick Apple \u002F Carrot \u002F Bone with BtnA, wrist-flick to throw, home pet eats it within ~200 ms.\n- **Web radio** — WDR Die Maus (DE) \u002F Fun Kids UK (EN) in the media menu, pet sways to the music; voice-triggerable on Muffin.\n- **Mini-games + scenes** — squat \u002F jump \u002F yoga workouts, butterflies \u002F mushrooms \u002F surf \u002F scorpion \u002F asteroids \u002F cross-the-street per scene, foraging for apple \u002F berry \u002F fish, five toys with boredom mechanics, scene travel between Bedroom \u002F Meadow \u002F Forest \u002F Beach \u002F City \u002F Desert \u002F Space.\n- **Parent dashboard** — captive-portal Wi-Fi setup, optional **`\u003Cpet>-setup.local`** web server for live stats and remote-edit of the daily play-session limit (5–120 min). Session expiry triggers a 30-minute lockout that survives reboots.\n- **Eleven moods + gestures** — Idle \u002F Happy \u002F Excited \u002F Love \u002F Sleepy \u002F Sleeping \u002F Sad \u002F Startled \u002F Laughing \u002F Eating \u002F Speaking, driven by happiness \u002F energy \u002F fullness needs. Touch zones (forehead \u002F cheeks \u002F mouth \u002F ears), IMU-based petting \u002F shake \u002F stand reactions, somersault on circle drag, sing-and-applause when tilted upright.\n\nSee the [Version history](#version-history) for the full per-target breakdown.\n\n## Targets\n\nThe three pets:\n\n| Target | Board | Branding | Voice | Camera | Hard buttons | Display | Audio | Web radio |\n|---|---|---|---|---|---|---|---|---|\n| `cores3` | M5Stack CoreS3 + Module-LLM    | \"Muffin\"  | ✅ Wake word + Whisper + Qwen3 | ✅ | ❌ Touch strip | 320×240 | WAV | ✅ |\n| `visu`   | M5Stack CoreS3 without module  | \"Visu\"    | ❌ | ✅ | ❌ Touch strip | 320×240 | WAV | ✅ |\n| `core2`  | M5Stack Core2                  | \"Goo-Goo\" | ❌ | ❌ | ✅ BtnA\u002FB\u002FC | 320×240 | WAV | ✅ |\n\nThe accessory:\n\n| Target | Board | Role | Display | Audio |\n|---|---|---|---|---|\n| `pip`    | M5StickC PLUS2 (ESP32 PICO)   | Pocket-sized companion to a bigger pet — sends treats and gestures over ESP-NOW. Doubles as a tiny pet face when out of range. | 135×240 | Buzzer |\n| `pip-s3` | M5StickC PLUS2 (S3 revision)  | Same role, ESP32-S3 board variant. | 135×240 | Buzzer |\n\n## Hardware shopping list\n\nPick **one pet** plus optionally **a Pip** as a pocket-sized accessory. Direct links to the M5Stack official store; all USB-C, no soldering, no breadboard.\n\n### Pets — pick one\n\n| Pet | Required parts | M5Stack store links |\n|---|---|---|\n| **Muffin** | M5Stack CoreS3 + **M5Stack Module LLM (AX630C)** + **Battery Module 13.2** (1500 mAh — separate purchase, not bundled with the LLM module). | [CoreS3](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5stack-cores3-esp32s3-iotdevelopment-kit) · [Module LLM (AX630C)](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5stack-llm-large-language-model-module-kit-ax630c) · [Battery Module 13.2](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fbattery-module-13-2-1500mah) |\n| **Visu** | M5Stack CoreS3 + **M5GO Battery Bottom3** (500 mAh, official CoreS3 accessory). | [CoreS3](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5stack-cores3-esp32s3-iotdevelopment-kit) · [Battery Bottom3](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5go-battery-bottom3-for-cores3-only) |\n| **Goo-Goo** | M5Stack Core2 (built-in 500 mAh battery, no extra parts). | [Core2](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5stack-core2-esp32-iot-development-kit-v1-1) |\n\n### Pip — optional pocket accessory\n\n| | |\n|---|---|\n| **Pip** | M5StickC PLUS2 (built-in 200 mAh battery, no extra parts). [StickC PLUS2](https:\u002F\u002Fshop.m5stack.com\u002Fproducts\u002Fm5stickc-plus2-esp32-mini-iot-development-kit) |\n\nPip is **not** a fourth pet. It's a tiny ESP-NOW remote that pairs with any of the three home pets above. Display shows the next treat the kid will throw (Apple \u002F Carrot \u002F Bone, BtnA cycles); a quick wrist-flick fires an ESP-NOW broadcast and within ~200 ms the home pet eats the treat (`Face::Eating` + Eat sound + Apple\u002FHeart floats + happiness\u002Ffullness boost).\n\nPet-mode owners enable reception via **Settings → Pip mode** (page 4). The toggle is off by default — the always-on listener costs ~20 % battery runtime on the bigger pet, so opt-in is honest. Pip itself stays radio-off until each shake (sender powers up the radio for ~150 ms per throw), so its 200 mAh battery is essentially unaffected.\n\nThe treat-thrower flow is shipped end-to-end and verified on hardware. See [`src\u002Fpip_link.h`](src\u002Fpip_link.h) (listener API), [`src\u002Fpip\u002Fpip_link_send.h`](src\u002Fpip\u002Fpip_link_send.h) (Pip-side sender). Other companion ideas (egg\u002Fhatchling, pet-mail, remote shutter) are sketched in [`docs\u002Fconcept.md`](docs\u002Fconcept.md) but not on the immediate roadmap — Pip is treated as feature-complete for now.\n\nWeb radio (in the media menu) plays **WDR Die Maus** in German and **Fun Kids UK** in English — no negative side effects, with note-symbol animation and body sway. On cores3 it can also be triggered by voice command (\"turn on the radio\").\n\nOn Muffin and Visu additionally: **Photo** and **Gallery** in the media menu. Photo opens the front camera with the pet overlaid in the lower-left corner (pet selfie), tap = capture. Gallery walks through the last five photos with left\u002Fright-tap navigation. Both reward happiness without negative effects.\n\n## For parents\n\nPixel Pets is a DIY maker project, but it is designed with families in mind.\n\n- No cloud account is required for the core pet experience.\n- No tracking or subscription model is built into the firmware.\n- The code is open source and can be inspected, changed and flashed yourself.\n- A configurable parental session limit is included.\n- The project works best as a shared maker activity: assemble, flash, test, name the pet and invent new interactions together.\n\nPixel Pets is not a certified commercial toy. Adult setup and supervision are recommended.\n\n## For makers\n\nPixel Pets is also a compact playground for embedded interaction design:\n\n- ESP32 \u002F M5Stack firmware with PlatformIO\n- one source tree with multiple hardware targets\n- shared pet state and rendering logic\n- touch, buttons, IMU, camera and audio integration\n- ESP-NOW communication between devices\n- optional offline voice pipeline on CoreS3 + Module-LLM\n- world data via WiFi, cached locally\n- native unit tests for pure logic modules\n\nGood places to start hacking are new scenes, mini-games, face animations, sounds, Pip interactions or new pet personalities.\n\n## Fastest start\n\nSorted from easiest to hardest setup. Each row links to a self-contained per-pet guide that covers everything (USB driver, env, flashing quirks, gotchas).\n\n💾 **Don't want to install PlatformIO?** Every [GitHub release](https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets\u002Freleases\u002Flatest) ships pre-built `pixel-pets-vX.Y.Z-\u003Cpet>.bin` files — single-file flash images at offset `0x0`. Use [M5Burner](https:\u002F\u002Fdocs.m5stack.com\u002Fen\u002Fuiflow\u002Fm5burner\u002Fintro) (\"Custom Firmware\" → upload .bin) or `esptool.py --chip \u003Cesp32|esp32s3> write_flash 0x0 pixel-pets-…bin`. Muffin's voice features still need the Module-LLM Linux setup from [`docs\u002Fsetup-muffin.md`](docs\u002Fsetup-muffin.md) on top of the binary.\n\n| Pet | Hardware | Difficulty | Setup guide |\n|---|---|---|---|\n| **Goo-Goo** | M5Stack Core2 | 🟢 Easiest — plug, flash, run | [`docs\u002Fsetup-goo-goo.md`](docs\u002Fsetup-goo-goo.md) |\n| **Visu** | M5Stack CoreS3 | 🟢 Easy — same idea on CoreS3 | [`docs\u002Fsetup-visu.md`](docs\u002Fsetup-visu.md) |\n| **Pip** | M5StickC PLUS2 (ESP32-PICO or S3 rev.) | 🟡 Medium — the S3 revision needs a manual download-mode procedure | [`docs\u002Fsetup-pip.md`](docs\u002Fsetup-pip.md) |\n| **Muffin** | M5Stack CoreS3 + Module-LLM | 🔴 Advanced — extra hardware + ADB \u002F Linux setup on the LLM module (Whisper, Qwen3, gotchas) | [`docs\u002Fsetup-muffin.md`](docs\u002Fsetup-muffin.md) |\n\nIf you're new to the project, start with **Goo-Goo** (if you have a Core2) or **Visu** (if you have a CoreS3) — both are roughly an hour from unbox to running pet. Muffin adds another evening for the Module-LLM setup. Pip is optional and only useful once a bigger home pet is running.\n\n## Build & flash\n\n```bash\npio run -e cores3                              # Muffin (CoreS3 + LLM, default)\npio run -e cores3 -t upload                    # Muffin build + flash\npio run -e visu                                # Visu (CoreS3 alone)\npio run -e core2                               # Goo-Goo (Core2)\npio run -e pip                                 # Pip accessory (StickC PLUS2 PICO)\npio run -e pip-s3                              # Pip accessory (StickC PLUS2 S3)\npio run -e cores3 -e visu -e core2 -e pip-s3   # build all\n```\n\nFor per-pet setup details (USB driver, env, flashing quirks, Module-LLM workflow), see the [Fastest start](#fastest-start) table above — every pet has its own dedicated guide under [`docs\u002Fsetup-*.md`](docs\u002F).\n\n## Repository layout\n\n```\nsrc\u002F\n  target_caps.h            ← TARGET_HAS_LLM \u002F HAS_CAMERA \u002F HAS_HARD_BUTTONS \u002F ...\n  main.cpp                 ← orchestrator (setup + loop) for the big pets\n  main_pip.cpp             ← Pip orchestrator (replaces main.cpp on the pip env)\n  face.{h,cpp}             ← renderer (PetView-driven)\n  pet_state.{h,cpp}        ← pet runtime: RTC, persistence, gaze, touch zones\n  needs_logic.{h,cpp}      ← pure happiness\u002Fenergy\u002Ffullness logic (native-testable)\n  voice_pipeline.{h,cpp}   ← wake \u002F VAD \u002F Whisper \u002F Qwen3 over UART (HAS_LLM only)\n  face_detect.{h,cpp}      ← front-camera face detection + JPEG capture (HAS_CAMERA only)\n  photo_store.{h,cpp}      ← LittleFS-backed selfie storage (HAS_CAMERA only)\n  webradio.{h,cpp}         ← MP3 stream decoder (HAS_WIFI only)\n  pip_link.{h,cpp}         ← ESP-NOW listener for treats\u002Ftricks from a paired Pip\n  net.{h,cpp}              ← WiFi, captive portal, NTP, ESP-NOW friends, parent server\n  world.{h,cpp}            ← IP geolocation + open-meteo + moon phase\n  i18n.{h,cpp}             ← string table (DE + EN, switchable at runtime)\n  wifi_config.h            ← compile-time WiFi credential defaults\n  screenshot.{h,cpp}       ← canvas dumper (SCREENSHOT_MODE only, *-shots envs)\n  sounds\u002F                  ← embedded WAV headers (xxd -i)\n  pip\u002F                     ← StickC Plus 2-only renderer + tone-based sound engine\n\ndocs\u002F\n  concept.md               ← gameplay & high-level design\n  architecture.md          ← software architecture (modules, build flow, state)\n  hardware.md              ← per-pet setup index + capability matrix\n  setup-goo-goo.md         ← Core2 (Goo-Goo) setup guide — easiest\n  setup-visu.md            ← CoreS3 (Visu) setup guide — easy\n  setup-pip.md             ← StickC PLUS2 (Pip) setup guide — medium, S3 download-mode\n  setup-muffin.md          ← CoreS3 + Module-LLM (Muffin) setup guide — advanced; Module-LLM ADB workflow + Qwen3 gotchas\n  sound_assets.md          ← WAV sample spec and trigger map\n\nsite\u002F                      ← GitHub Pages landing page (index.html + scripts + assets)\nassets\u002F                    ← master media: logo.jpg, photos\u002F, sounds\u002F, video\u002F\nscreenshots\u002F               ← real-hardware Bear \u002F Cat \u002F Dog captures used in this README\ntools\u002F                     ← Python helpers (uv-managed): shot.py, listen.py, extract_screenshots.py\ntest\u002Ftest_needs_logic\u002F     ← Unity tests for the pure-logic needs module (`pio test -e native`)\npkgs\u002F                      ← Module-LLM .deb packages (audio \u002F framework \u002F models \u002F services; .debs gitignored)\n.github\u002Fworkflows\u002F         ← ci.yml (matrix builds + native tests), pages.yml (Pages deploy)\n\nplatformio.ini             ← [env:cores3] + [env:core2] + [env:visu] + [env:pip] + [env:pip-s3] + *-shots variants\npartitions_cores3_16MB.csv ← partition table for CoreS3 \u002F Visu (incl. LittleFS)\npartitions_core2_16MB.csv  ← partition table for Core2\npartitions_pip_8MB.csv     ← partition table for StickC Plus 2\nCREDITS.md                 ← father-and-son project credits\nLICENSE                    ← MIT\n```\n\n## Documentation\n\n- [`docs\u002Fconcept.md`](docs\u002Fconcept.md) — how the pet ticks: needs, input (touch \u002F IMU \u002F hard buttons \u002F voice \u002F camera), world, mini-games, parental session limit, persistence.\n- [`docs\u002Farchitecture.md`](docs\u002Farchitecture.md) — software architecture: module overview, build-target system, state model, render pipeline.\n- [`docs\u002Fhardware.md`](docs\u002Fhardware.md) — overview index with the build-target capability matrix; links to the per-pet setup guides:\n  - [`docs\u002Fsetup-goo-goo.md`](docs\u002Fsetup-goo-goo.md) — Core2 (🟢 easiest)\n  - [`docs\u002Fsetup-visu.md`](docs\u002Fsetup-visu.md) — CoreS3 (🟢 easy)\n  - [`docs\u002Fsetup-pip.md`](docs\u002Fsetup-pip.md) — StickC PLUS2 (🟡 medium, S3 download-mode dance)\n  - [`docs\u002Fsetup-muffin.md`](docs\u002Fsetup-muffin.md) — CoreS3 + Module-LLM (🔴 advanced, includes the ADB workflow + Qwen3 gotchas)\n- [`docs\u002Fsound_assets.md`](docs\u002Fsound_assets.md) — WAV spec, sample list, trigger map (Pip uses tone sequences instead).\n\n## Continuous integration\n\nGitHub Actions in [`.github\u002Fworkflows\u002Fci.yml`](.github\u002Fworkflows\u002Fci.yml):\n\n- **Matrix build** for all four firmware targets (`cores3` \u002F `core2` \u002F `visu` \u002F `pip`). Fails any PR that breaks a build.\n- **Native unit tests** (`pio test -e native`) for the pure-logic modules in [`src\u002Fneeds_logic.cpp`](src\u002Fneeds_logic.cpp). Tests live under [`test\u002Ftest_needs_logic\u002F`](test\u002Ftest_needs_logic\u002F) and use Unity. Run locally with `pio test -e native` (Linux\u002FmacOS, or Windows with MinGW gcc on PATH).\n\n## Screenshots for the docs\n\nThe firmware has a built-in canvas dumper, gated behind the dedicated **`*-shots` envs** in [`platformio.ini`](platformio.ini) so it never lands in production builds. Flash one of `cores3-shots` \u002F `visu-shots` \u002F `core2-shots`, navigate to the screen you want to capture and **hold the PWR button ≥ 2 s** — the canvas is dumped over Serial as base64 RGB565. The host-side decoder in [`tools\u002Fextract_screenshots.py`](tools\u002Fextract_screenshots.py) turns it into PNGs.\n\nPython tooling is managed with [`uv`](https:\u002F\u002Fdocs.astral.sh\u002Fuv\u002F) — see [`tools\u002FREADME.md`](tools\u002FREADME.md) for the full workflow.\n\n## Authors\n\nA father-and-son project: **Justus Dütscher** (10) — ideas, design decisions, tireless field-testing — and **Marcel Dütscher** (Papa) — translating Justus's ideas for the AI doing the actual coding, plus the bits of technical know-how that don't fit on a kid's whiteboard. The first beta was finished on a Sunday afternoon; the boring polish was Papa's evening work.\n\nEvery line of firmware was written by AI assistants — primarily **Claude (Anthropic)** — under our direction. `git log --format=\"%an %ae\"` shows which model touched which commit.\n\nSee [`CREDITS.md`](CREDITS.md) for the full story, and the in-app credits screen via Settings → Credits.\n\n## Support the project\n\nPixel Pets is a family project — not a startup, no roadmap, no metrics dashboard. But we'd love for it to find more kids and dads who want to tinker. The cheapest things that genuinely help:\n\n- **Drop a ⭐ on the repo.** It's the cheapest signal that something resonated, and it really does help the project surface to other curious people scrolling GitHub. Justus checks the count on Sundays.\n- **Or leave a \"respect\" on Hackster.io** — same idea, different community: project page at [hackster.io\u002Fmarcelduetscher\u002Fpixel-pets-…](https:\u002F\u002Fwww.hackster.io\u002Fmarcelduetscher\u002Fpixel-pets-an-ai-assisted-virtual-pet-family-for-m5stack-baa76c).\n- **Try it with a kid you know.** That's actually the most valuable feedback we get — what works, what confuses, what's missing for a 7-year-old vs a 10-year-old.\n\n## Contributing\n\nWe'd love your help — code, ideas, bug reports, translations, a new sound, a face animation, an extra language string, a photo of a kid trying it out. All welcome. No CLA, no contributor agreement, no Slack to join. Just GitHub.\n\n- 📘 [**Contributing guide**](CONTRIBUTING.md) — setup, conventions, how to get a PR merged. Good first contributions: a new sound, a new scene, a face animation, a mini-game, an extra language string. [`docs\u002Farchitecture.md`](docs\u002Farchitecture.md) explains where things live.\n- 💬 [**Discussions**](https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets\u002Fdiscussions) — questions, share what you built, show-and-tell.\n- 🐛 [**Issues**](https:\u002F\u002Fgithub.com\u002Fmarceld23\u002FPixel-Pets\u002Fissues) — bug reports, feature requests, \"Justus has Strong Opinions™ on what feels right; pitch yours\".\n\n## Version history\n\n### 1.0.3 — May 2026\n\nSmall follow-up to 1.0.2. One firmware fix that closes a regression introduced in 1.0.2, and a docs correction so the next person doesn't lose hours to the same wrong setup steps.\n\n**Pip-S3 deep sleep now actually wakes back up:**\n\n- 1.0.2's \"real deep sleep after 3 min idle\" plus the USB-PHY detach were both correct, but together they exposed a third bug: `M5Unified::Power_Class::_setupBoard()` has no case for `board_M5StickS3` in the `_wakeupPin` switch, so `_wakeupPin` stayed at `255` (`GPIO_NUM_MAX`). `M5.Power.deepSleep(0, true)` then skipped its `esp_sleep_enable_ext0\u002F1_wakeup()` call, the chip entered deep sleep with **no wakeup source at all**, and the only way back was a PMIC power-cycle (long-press to force-off → short-press to cold-boot)\n- 1.0.3 manually configures BtnA (GPIO11, RTC-capable on ESP32-S3) as an `ext1` active-low wakeup source before handing off to `M5.Power.deepSleep()`. Same one-line workaround applied in the brownout-protection boot path so a low-battery sleep doesn't strand the device either. After the fix: a short BtnA press wakes the Stick S3 cleanly from deep sleep, just like the StickC Plus 2 variant has worked all along\n- The StickC Plus 2 path (`pip` env, ESP32-PICO) is unchanged — its wakeup pin (GPIO35 = power button) was already correctly mapped in M5Unified\n\n**Pip setup docs corrected for the M5StickS3 (K150) hardware:**\n\n- The old `docs\u002Fsetup-pip.md` \"S3 revision\" procedure was: \"hold BtnA, press the side reset button for ~2 s.\" That's the **original PLUS2 S3 revision** procedure, where BtnA happens to be wired in parallel with GPIO0 (the strap pin) and there's a separate hardware reset button on the side. On the **newer M5StickS3 (SKU K150)** — which is what most people now buy — BtnA is GPIO11 (not GPIO0), and there is no separate reset button (only the PM1 PMIC power button). The published procedure simply could not trigger download mode on K150 hardware\n- The setup doc now splits the S3 path into two clearly-labelled variants: PLUS2 S3 keeps the BtnA + reset procedure, K150 gets a **Hat2-Bus G0 ↔ GND bridge** procedure with a PMIC cold-boot trigger. Includes the full 16-pin Hat2-Bus pinout table (G0 on pin 4, GND on pin 1, plus the UART pins for the recovery path below)\n- Documented the slow ~1 Hz green LED blink as the visual confirmation that the chip is in ROM bootloader — no need to guess from \"display is dark, did it work?\"\n- Added a **UART recovery-flash recipe** for the case where the Stick S3's USB-C connector has developed loose D+\u002FD- contacts (power pins still work, hence LED + charging, but USB enumeration is dead even on a fresh OS install). Wire a USB-TTL adapter to Hat2-Bus G43 (TX) \u002F G44 (RX) \u002F GND, enter download mode the usual way, and flash through the adapter with `esptool --before no_reset`. Confirmed working as the only path back for one user's stick after the USB-C port wore out across many cold-boot cycles\n\n### 1.0.2 — May 2026\n\nSmall follow-up to 1.0.1. Two real fixes plus a homepage tweak.\n\n**Motion-gesture reliability — Spielen \u002F Regen \u002F Singen now clearly distinguishable:**\n\n- Lowered the magnitude threshold for both shake gestures (1.0 g → 0.7 g for the play-shake and the rain-shower vertical shake). Reproducibly hard for kid-sized wrist motions to reach 1 g; 0.7 g triggers cleanly without false-firing on accidental jostles\n- Vertical-shake dominance ratio relaxed (1.0 → 0.6) so realistic up-down hand motions, which always carry some sideways jitter, qualify for \"rain\". Required vertical peaks dropped from 2 to 1 — one decisive down-flick is enough; users intuitively flick once for \"shower\"\n- Singing gesture redesigned: was an \"upright + tilt-left + tilt-right rising-edge sequence\" that broke whenever the pet was already slightly tilted at sequence start (the rising edge never fired). Now it's \"**heave-up + tilt-left + tilt-right**\": the user must transition the pet from low (gy\u003C0.4) to upright (gy>0.7) within 800 ms, then complete the L+R tilt within 5 s. The heave guarantees gx ≈ 0 at sequence start so the rising edge fires reliably; a pet just sitting on the desk doesn't trigger because there's no fresh transition\n- Help-page 8 updated in DE + EN: \"Hochheben, links + rechts kippen\" \u002F \"Lift it up, tilt left + right\"\n\n**Pip-S3 robust USB-PHY detach before deep sleep:**\n\n- 1.0.1's `Serial.flush()` + `Serial.end()` + 100 ms grace turned out not to be aggressive enough on every M5-Stick variant — one tested device still disappeared from the host after deep sleep, and only the 60-second-unplug recovery brought it back\n- 1.0.2 explicitly drives GPIO19 \u002F GPIO20 (the D- \u002F D+ pins on the ESP32-S3) to input + pull-mode floating before `esp_deep_sleep_start()`. This collapses the 1.5 kΩ D+ pull-up so the host sees an unambiguous detach instead of a frozen-but-attached device. Grace bumped 100 → 200 ms because Windows sometimes doesn't register the detach in under 200 ms\n- Plus: `M5.Power.isCharging()` is now polled up to 8× with 50 ms gaps at boot. The PMIC's charging-detect isn't stable for the first few ms after power-up — reading it once immediately could falsely return `false`, sending the brownout-protection branch straight into deep sleep with USB plugged in (and looking like a \"won't boot\" device to the user)\n\n**Site:**\n\n- New 2-minute YouTube-Short feature reel section between the hero demo and the deep-dive embed (covers voice control on Muffin, ESP-NOW Friends gift exchange, and a Pip wrist-flick treat throw — all on real hardware). Caption translated DE \u002F EN, `iframe` aspect-ratio 9:16 to match the vertical Short format\n\n### 1.0.1 — May 2026\n\nReliability release — same features as 1.0.0, but the rough edges that surfaced in the days after launch are fixed. No protocol changes; existing pets keep their NVS state when upgraded.\n\n**Friends mode — now actually reliable across all pet pairs:**\n\n- Switched the ESP-NOW PHY from LR to standard 802.11 B\u002FG\u002FN. The LR mode had reproducible interop problems between ESP32 (Goo-Goo) and ESP32-S3 (Muffin \u002F Visu) — packets sent in LR didn't decode on the other side\n- Pets now run in `WIFI_AP_STA` instead of pure `WIFI_STA` — the ESP32-S3 stack silently dropped most ESP-NOW broadcast frames in disconnected-STA mode\n- Once the partner's MAC is known, gift packets switch from broadcast to unicast. 802.11 unicast has ACK + retry at the MAC layer; broadcast was fire-and-forget and the CoreS3 RX path frequently lost it\n- Reach-back Ready in the Sending state — the faster tapper used to go silent the moment they matched, leaving the slower partner stuck on \"Waiting for friend\" until the 60 s timeout\n- Smaller initial bursts (1 packet instead of 3-4) and jittered re-broadcast intervals — avoids the \"two pets burst into each other\" RF collision that froze the rendezvous\n\n**Web radio — stutter-free, knacks-free, and tap-resilient:**\n\n- Audio decoder now runs on its own FreeRTOS task pinned to core 1, separate from the main loop. Pet animations \u002F touch sampling \u002F friends ticks no longer starve the MP3 decoder mid-frame\n- `WiFi.setSleep(false)` while streaming — keeps the radio listening continuously instead of waking only on DTIM beacons\n- Display sleep no longer kills the audio: the main loop stays at 1 ms cadence as long as media is active\n- Pet sound effects (greet \u002F tickle \u002F eat …) are suppressed during radio playback so they don't fight the audio library for the I2S bus — fixes the audible knacks\n- Volume slider now actually applies to the stream, live: was hardcoded to ~80 %\n- Listen-lock: while the radio plays, the pet ignores every interaction except a tap on the Media button (which still toggles the radio off). Hard buttons A \u002F B \u002F C are gated too. Touching the pet no longer yanks it into a sound-effect animation that stops the music\n- \"Brauche WLAN\" overlay when the radio is tapped without any saved WiFi credentials — bounces back to the chooser instead of silently timing out after 10 s\n\n**Pip — no more \"bricked-looking\" Stick S3:**\n\n- The Pip-S3 firmware now explicitly tears down the USB-CDC stack before deep sleep. Without this, the ESP32-S3's D+ pull-up stayed asserted across deep sleep — the host never saw a detach, and on the next reset the device was *invisible* (no COM port, no `VID 303A` enumeration). Recovery used to require a 60 s unplug or holding the reset pinhole; that's no longer needed\n- Pip's treat \u002F wand sender is now on B\u002FG\u002FN + AP_STA to match the home-pet receiver after the Friends-mode PHY switch above. Without this fix Pip's announcements wouldn't reach Goo-Goo \u002F Muffin \u002F Visu\n\n**Site \u002F CI \u002F docs:**\n\n- Site supports `?lang=de` \u002F `?lang=en` URL overrides for shareable language-pinned links\n- README split into separate Support and Contributing sections, Star-History chart added\n- Module-LLM setup script extracted from the README into `scripts\u002Fsetup-module-llm.sh` with a CI lint\n- Release workflow has a manual dry-run mode for testing before tagging\n- Per-env firmware artifacts (`firmware-cores3` \u002F `firmware-core2` \u002F `firmware-visu` \u002F `firmware-pip`) uploaded on every CI run, downloadable for 14 days from the Actions page\n- Dependabot, typos, CodeQL, lychee + `pio check` CI added; CodeQL findings cleared\n\n**Smaller bug fixes:**\n\n- WiFi-setup screen now shows the correct AP name per target (`muffin-setup` \u002F `goo-goo-setup` \u002F `visu-setup`) instead of always saying `muffin-setup`\n- Web radio plays sound on its second start in the same session (was silent because `M5.Speaker.begin()` had grabbed the I2S bus back)\n\n### 1.0.0 — May 2026\n\nFirst stable release. Three pet variants and one accessory, all verified end-to-end on hardware.\n\n**The pets** (Muffin \u002F Visu \u002F Goo-Goo):\n\n- 11 moods driven by happiness \u002F energy \u002F fullness needs\n- Touch zones (forehead \u002F cheeks \u002F eyes \u002F mouth) + IMU-based petting \u002F shake \u002F stand reactions\n- Gestures: somersault on circle drag, wobble on two-finger pull, snuggle on long hold\n- Mini-games per scene (squat \u002F jump \u002F yoga \u002F butterflies \u002F mushrooms \u002F surf \u002F scorpion \u002F asteroids \u002F cross-the-street), foraging for apple\u002Fberry\u002Ffish, toy play with five toys + boredom, scene travel between Bedroom \u002F Meadow \u002F Forest \u002F Beach \u002F City \u002F Desert \u002F Space\n- Singing + applause: tilt sequence triggers the pet to sing, mic listens for a loud peak afterwards\n- Real weather + sunrise\u002Fsunset (open-meteo) and local moon-phase, IP-based location lookup (ip-api), all cached in NVS\n- Egg-timer screen with vibration + Goo-Goo cue when it expires\n- Parental session limit (5–120 min, configurable via parent web server) with a 30-minute lockout after expiry\n- ESP-NOW Friends mode between any two home pets — rendezvous handshake, gift exchange, LR PHY for asymmetric-RF reliability\n\n**Muffin only** (CoreS3 + Module-LLM):\n\n- Wake word \"Muffin\" + on-device speech recognition (Whisper) + Qwen3-0.6B intent classifier\n- Whisper-first bypass for ~80 % of commands (sub-second latency, no LLM round-trip)\n- Voice-triggerable actions (eat, sleep, dance, radio …)\n- TTS \u002F wake-WAV side effects neutralised on the LLM module\n\n**Muffin \u002F Visu** (CoreS3 with front camera):\n\n- Front camera + face \u002F proximity detection — pet greets you when you walk past\n- Photo + 5-slot gallery (LittleFS), pet-overlay selfies\n\n**Goo-Goo \u002F Visu \u002F Muffin** (everything but Pip):\n\n- Web radio (WDR Die Maus \u002F Fun Kids UK), pet sways to the music\n- Captive-portal WiFi setup\n- Optional parent web server (mDNS `\u003Cpet>-setup.local`) for stats + session-limit edits\n\n**The accessory** (Pip — M5StickC PLUS2):\n\n- Pocket companion that pairs with any of the three home pets via ESP-NOW\n- Five-page menu (BtnA cycles): \"Wähle aus\" (safe-carry mode, no shake response) → Apple → Carrot → Bone → Tricks\n- Treat thrower: wrist-flick fires a 3-packet broadcast, home pet eats it within ~200 ms\n- Tricks: peak-counted gesture → home pet visibly hops N times in a row (giggle sound + heart per landing)\n- First-run language picker (DE \u002F EN flags only, no text)\n- Long-press BtnA = sleep; auto-sleep after 60 s idle; sleep-click regression on the buzzer fixed\n\n**Other lanes that grew along the way:**\n\n- GitHub Pages site rebuilt around \"three pets + one accessory\" framing, click-and-poke browser pet, hardware shopping list\n- CI matrix builds all 5 envs on every push; native unit tests for the pure-logic needs module\n\n## License\n\n[MIT License](LICENSE) — open source, free to use, modify and redistribute.\n\nNote: the web radio feature links against [`schreibfaul1\u002FESP32-audioI2S`](https:\u002F\u002Fgithub.com\u002Fschreibfaul1\u002FESP32-audioI2S), which is GPL v3.0. Binaries built from the `cores3` \u002F `core2` \u002F `visu` envs therefore inherit GPL v3.0 obligations when redistributed. The `pip` env doesn't link the audio library and stays MIT all the way through. Source code in this repository is MIT regardless of which env you build. See [`LICENSE`](LICENSE) for the full third-party-licenses block.\n\n## Star History\n\n\u003Ca href=\"https:\u002F\u002Fwww.star-history.com\u002F?repos=marceld23%2FPixel-Pets&type=date&legend=top-left\">\n \u003Cpicture>\n   \u003Csource media=\"(prefers-color-scheme: dark)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=marceld23\u002FPixel-Pets&type=date&theme=dark&legend=top-left\" \u002F>\n   \u003Csource media=\"(prefers-color-scheme: light)\" srcset=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=marceld23\u002FPixel-Pets&type=date&legend=top-left\" \u002F>\n   \u003Cimg alt=\"Star History Chart\" src=\"https:\u002F\u002Fapi.star-history.com\u002Fchart?repos=marceld23\u002FPixel-Pets&type=date&legend=top-left\" \u002F>\n \u003C\u002Fpicture>\n\u003C\u002Fa>\n","Pixel-Pets 是一个基于 M5Stack 硬件的开源虚拟宠物生态系统。项目包含三种宠物变体：Muffin（支持LLM）、Visu 和 Goo-Goo，以及一个可选配件 Pip（作为便携式伴侣设备）。这些宠物支持动画、迷你游戏、通过 ESP-NOW 与朋友互动及天气\u002F位置信息等功能，其中语音和前置摄像头功能仅限于 CoreS3 版本。该项目完全由 C++ 编写，并利用 Claude AI 完成代码编写，旨在提供隐私保护、教育价值和离线娱乐体验。它非常适合希望在家中为孩子提供安全且富有教育意义的数字宠物体验的家庭使用。",2,"2026-06-11 04:07:16","CREATED_QUERY"]