Ready to dive deeper into TamaFi's details? Discover the full story, in-depth tutorials, and all the exciting features in our comprehensive documentation. Click the link and explore further!
TamaFi is a modern, WiFi-aware virtual pet.
V2 rebuilds the original project with new hardware, smarter logic, and a clean, compact PCB that actually feels like a finished device.
The pet lives on an ESP32-S3, eats nearby WiFi, evolves over time, and makes its own decisions based on the environment around it.
- ⚙ ESP32-S3 based – more performance, native USB, better room for future features
- 🖥 TFT ST7789 240×240 – full-color UI, custom sprites, status bars, menus
- 🧠 Autonomous behavior engine – the pet hunts, explores, rests, and reacts on its own
- 📶 WiFi-fed – nearby networks affect hunger, happiness, and health
- 🎛 Full menu system – Pet Status, Environment, System Info, Controls, Settings, Diagnostics
- 💾 Persistent state – age, stats, stage, settings stored in flash (Preferences)
- 🌈 4× WS2812-2020 NeoPixels – mood & activity feedback (happy/sad/wifi/rest patterns)
- 🔊 Retro sound engine – non-blocking chiptune-style beeps and sequences
- 🔋 Battery-ready – TP4056 charger + MOSFET-controlled TFT backlight
- 🖱 6 soft tactile switches – three on each side for navigation and shortcuts
- 🛠 DisplayKit-ready UI workflow – UI graphics can be designed/exported via DisplayKit
⚠️ Some advanced / sensitive behaviors are intentionally simplified or left as placeholders in the public firmware.
This project is for learning, tinkering, and fun — not for breaking things.
TamaFi isn’t just a sprite animation loop. It runs a small decision engine that constantly evaluates:
- Pet stats:
hunger,happiness,health - Traits: curiosity, activity, stress
- Environment: number of nearby networks, open/hidden networks, average RSSI
- Time: age (minutes → hours → days)
From that, it decides whether to:
- 🍖 Hunt – use WiFi scan results to “feed” and adjust hunger/happiness/health
- 👁 Explore – react to open/hidden networks and network diversity
- 😴 Rest – enter a sleep cycle with special egg animation and recovery stats
- 😐 Idle – chill on the home screen with mood-based idle animations
The pet mood changes based on stats + environment:
HUNGRY– low hungerHAPPY– good stats + decent WiFiCURIOUS– hidden/open networks nearbyBORED– no WiFi for too longSICK– low health or bad conditionsEXCITED/CALM– good conditions & variety
Mood affects:
- Idle animation speed
- LED patterns
- How often it wants to hunt / explore / rest
Age is tracked in minutes, hours, and days:
BABY→TEEN→ADULT→ELDER
Evolution depends on:
- Time alive
- Average of hunger / happiness / health
- Environment quality
Reaching a new stage triggers special SFX + animations.
All rendering goes through a 240×240 framebuffer (TFT_eSPI + TFT_eSprite) to avoid flicker.
- Pet sprite (idle / hunt / rest / special states)
- Background image
- Stats bars: Hunger, Happiness, Health
- Mood + Stage text
- Activity label in the top bar (
Idle,Hunting…,Resting…, etc.) - Overlays for special effects (e.g. hunger effect)
Navigation is done using the left 3 buttons (UP / OK / DOWN).
Main Menu:
- Pet Status – stats, mood, age, stage, short description
- Environment – WiFi network counts, hidden/open, “signal mood”
- System Info – firmware version, uptime, battery (if implemented), etc.
- Controls – brightness, LED level, sound on/off, NeoPixel on/off
- Settings – auto-sleep, auto-save interval, soft reset options
- Diagnostics – debug info, test modes (non-destructive)
- Back to Home
Changes in Controls/Settings are saved to NVS via Preferences, so they persist across reboots.
This is a summary of the V2 hardware stack.
Check thePCB/andSchematic/directories for full details.
- MCU: ESP32-S3 module
- Display: 1.3–1.54" TFT ST7789 @ 240×240
- Buttons: 6× soft tactile switches
- LEDs: 4× WS2812-2020 addressable RGB
- Buzzer: driven with PWM (LEDc) for retro SFX
- Charger: TP4056 (single-cell Li-ion/Li-Po)
- Backlight control: MOSFET on TFT LED pin, driven by PWM for brightness levels
- Power input: USB-C (on PCB)
- ESP32-S3 native USB for firmware upload
- Optional CP2102 USB-to-TTL on the board for easier flashing / serial during development
The firmware is written for Arduino IDE using:
TFT_eSPIAdafruit_NeoPixelWiFiPreferences
main.ino– hardware init, timers, logic tick, button handlingui.cpp / ui.h– rendering, menus, bar drawing, layoutui_anim.h– sprite frame tables for idle, egg, hunt, etc.sound– non-blocking retro sound sequencer using LEDcstate– pet stats, traits, persistence withPreferences
The code is structured around non-blocking updates:
nodelay()in the main logic, so animations, WiFi, sound, and UI can all coexist smoothly.
V2 is still under active development. Expect rough edges.
| Area | Status | Notes |
|---|---|---|
| Core stats | ✅ Stable | Hunger, happiness, health, age |
| Mood system | ✅ Stable | Driven by stats + WiFi environment |
| Evolution | ✅ Stable | Multi-stage, environment-aware |
| WiFi “feeding” | ✅ Stable | Logic works; tuning values ongoing |
| Rest system | ✅ Stable | Enter/exit animations + stat recovery |
| Hunt animation | ✅ Stable | Uses dedicated attack frames |
| Menus & UI | ⚠ In progress | Layout & styling still evolving |
| Sound engine | ✅ Stable | Non-blocking retro SFX |
| NeoPixel effects | ⚠ In progress | Mood + activity patterns, still tweaking |
| Desktop tooling | ⚠ Planned | Companion webapp / deeper integration |
Distributed under the MIT License. See LICENSE.txt for more information.
▶ Support me on Patreon patreon.com/cifertech
CiferTech - @twitter - CiferTech@gmali.com
Project Link: https://github.com/cifertech/TamaFi
The libraries and projects listed below are used in this software:
