Player's guide
How to play
Everything the board can do, from the first egg to the League. Read it in order the first time; after that, jump to the chapter you need.
The short version
01
Before you start
What you need, and how to get the game onto the board. About fifteen minutes.
- A Waveshare ESP32-S3-Touch-AMOLED-1.75 board (standard or -G; the -B comes in its own case and the 1.75C is a different board).
- A microSD card formatted as FAT32. It holds the sprites, the farm, the album and the backups.
- A USB-C cable and a computer with Chrome or Edge.
- Optional: a 3.7 V battery (MX1.25 plug, check the polarity first), a small speaker, and the printed Poké Ball case with 3 M2×5 self-tapping screws and 6 magnets (6×2 mm).
- 1Download tamapoke-sd.zip from the latest release, unzip it and copy the mons folder to the root of the SD card (about 290 MB). Put the card in the board.
- 2Open the web installer on the computer, plug the board in and press Install. No Arduino needed.
- 3When it restarts you see the starter screen. Go on to the next chapter.
CarefulIf the board can't read the card, it formats it. Back up anything on the card first.
TipUpdating later is the same click in the web installer, and it keeps your game: only the program is replaced.
02
The first ten minutes
A starter, an egg, your language and Wi-Fi.
- 1Pick a starter: Bulbasaur, Charmander or Squirtle. This choice only appears in a brand-new game.
- 2Hatch the egg: tap it three times (or give the board a gentle shake). Left alone it hatches by itself after 3 minutes.
- 3Language: the installer's firmware starts in English. Swipe down for settings and tap the language button to switch to 简体中文.
- 4Wi-Fi: in settings tap Wi-Fi. The board opens a hotspot called TamaPoke; join it with a phone and open 192.168.4.1. Enter up to three networks (2.4 GHz only) and, if you play, your chess.com username.
TipYou start with 10 points. Feeding, playing, bathing and sleeping never cost anything.
- With three networks saved (say home, school and a phone hotspot) the board joins the strongest one it can see. On an iPhone hotspot turn on Maximize Compatibility.
- The Wi-Fi details stay on the board and are never shown again. Leave a field empty to keep what was saved; enter - to delete it.
- Wi-Fi also sets the clock and brings the weather. Without it the pet still works; you just get no chess points.
03
Finding your way
Everything starts from the main screen: four swipes, four buttons and the pet itself.





| On the main screen | What it does |
|---|---|
| Tap the points at the top | Opens the shop |
| Long press the pet | Send it to the farm, or release it |
| Feed | Berry (free), candy, medicine; fish and fruits when you have some |
| Play | Cheers it up, costs a little energy |
| Light | Puts it to sleep or wakes it |
| Bath | Washes it and cleans up the poops |
Touching the pet
Tap to pet it, stroke back and forth, double tap to make it hop, poke its head or belly, tickle it (too much and it gets annoyed), drag it to walk, or draw a circle to spin it.
Moving the board
Tilt the board and it walks downhill. Lay it face down and it goes to sleep. Shake it hard and it gets dizzy.
The PWR button
- Short press: the screen turns off and the pet goes to sleep. Press again to wake it.
- While the screen is off, touching it does nothing. That is on purpose, so it doesn't wake up in a pocket.
- Hold for about 4 seconds: the board switches off completely (steps are not counted then).



04
Daily care
Four needs from 0 to 100. Keep them up and your friend stays healthy, happy and on time for its evolution.
| Need | How it drops | How to raise it |
|---|---|---|
| Food | The fastest: about 2 a minute while awake | Feed a berry: +25, free |
| Joy | About 1 a minute, faster when hungry or dirty | Play: +25. Petting +5, stroking +8 |
| Energy | Slowly while awake; playing costs 10 | Sleep: it comes back in a few minutes |
| Hygiene | About 1 a minute, much faster with poops around | Bath: back to 100, poops gone |
What goes wrong
- A need at 10 or below is a care mistake (at most one an hour). Each mistake delays evolution by 2 hours.
- Two or more poops, being overweight, or a need at 20 or below can make it sick. Give medicine; every 2 hours sick is another mistake.
- If it stays sick and awake for 10 minutes it takes a medicine from the bag by itself. It never spends your points: with no medicine in the bag it waits for you.
- All four needs at 0 for an hour: a run-away button appears.
Sleep protects it
While it sleeps, energy comes back, the other needs drop about four times slower and they stop at a floor: food 30, joy 35, hygiene 45. Asleep it makes no care mistakes and doesn't get sick. So whenever you leave, let it sleep.
| Situation | What happens |
|---|---|
| Night, light still on | It falls asleep by itself at 23:00 and wakes at 07:00 |
| You press PWR | Screen off, pet asleep. Only PWR wakes it |
| On battery, untouched for 5 minutes | The same as pressing PWR, by itself |
| Plugged in, untouched for 90 seconds | The standby clock: time, date and weather |
| Plugged in, untouched for 10 minutes | Self-care: any need below 40 goes back to 50, one a minute, silently (no animation, no sound), and it can't get sick. This doesn't count as your care |
Natures
Each pet hatches with a nature: easygoing, glutton, playful, tidy or lazy. One need drops a little faster, and its favourite care gives more (a glutton gets +30 from a berry, a playful one +30 from play, a tidy one enjoys its bath).
TipA simple routine: berry, bath and play in the morning and after school, and PWR (or the light) when you leave. Candy is tasty but fattening, and being overweight makes it sick.




05
Earning points
Points buy items, eggs and fun. They come from real life: mostly chess, a little from walking.
Chess
Once a chess.com username is saved on the Wi-Fi page, the board reads that account's public games once a day at midnight (or at the next start if it was off). Sync now in settings does it right away.
| What you did | Points |
|---|---|
| Finished a game with 10 minutes or more on the clock, or a daily game | 1 |
| Won it | 10 |
| A new best rapid or daily rating | 20 |
| Each new hundred in rapid (1000, 1100...) | 50 |
| A new best in tactics or Puzzle Rush | 10 |
CarefulBullet, blitz and games against bots don't count. The first sync (and the first after changing the username) only records where you stand: no points for old games.
Other ways
- Steps: 1 point per 1,000 steps, up to 5 a day, and 10 more the day you reach 10,000. The board counts them itself, also with the screen off.
- Hockey practice (from an iPhone shortcut): 1 point every 5 minutes, up to 6 a day.
- Rewards from home (from a parent's iPhone shortcut): 1 to 10 points at a time for anything the parent likes, up to 20 a day.
- Completing a region's Pokédex: 200 points, a crown and a shiny legendary egg of that region.
- The farm gives a small harvest every day after 07:00.
The points book
The last page of the shop (or tap the points at the top of the shop) shows this week day by day: earned in green, spent in orange, where it came from and where it went, plus last week. Every Monday the main screen shows a short summary.


06
Shop and bag
Tap the points at the top of the main screen.
Swipe left to move through the pages: shop, bag, harvest (what you got from Fun), accessories and the points book. Buying always asks first (YES / NO).
| Item | Points | What it's for |
|---|---|---|
| Candy | 2 | Food +10 and joy +12, but fattening |
| Medicine | 3 | Cures a sick pet |
| Stamina potion | 5 | Raises stamina: energy drops more slowly |
| Vitality potion | 5 | Raises vitality: joy drops more slowly |
| Common / rare / legendary egg | 10 / 30 / 100 | Your next companion |
| Shiny charm | 50 | Makes the next egg four times as likely to be shiny |
| Evolution potion | 100 | Evolve now, without waiting |
| Mega Stone | 150 | Mega Evolution for 24 hours |
| Accessories | 15-80 | Bow, flower, cap, witch hat, top hat, crown |
TipOne win at chess is 10 points: five candies, or three medicines and a candy. A Mega Stone is also the prize for the first tournament gold of the day, so you rarely need to buy one.
CarefulAn egg can only be opened when you have no companion. Send the current one to the farm first (long press it).




07
Growing up
Levels, evolution, abilities, and what happens when a companion grows old.
- Level: one level for every hour of its life, asleep or awake.
- Evolution goes by age, the same for every Pokémon: the first at 3 days, the second at 5 days. All four needs must be at 40 or more, and each care mistake adds 2 hours.
- When it is ready a button appears: evolve, or keep the form you like. An evolution potion skips the wait.
- Retiring: 7 days after reaching its final form it asks to retire (you can stay together a while longer). It moves to the farm, the album keeps its page, and you open a new egg.
Abilities
Three abilities from 0 to 100 (there are no battles): stamina slows energy loss by up to half, vitality slows joy loss by up to half, and resistance cuts the chance of getting sick by up to 60%. Potions raise the first two; resistance grows by 1 for every 3 hours of good care (all needs at 40 or more). Fruits from the orchard raise them as training, which also counts in the tournament and the gyms.
Eggs and shinies
| Egg | Rare species | Legendary |
|---|---|---|
| Common | 10% | 3% |
| Rare | 20% | 6% |
| Legendary | 30% | 10% |
These are the base chances; good care of the companion before it improves them. Eggs only bring species from regions you have opened, and never one that is already in your farm. About 1 egg in 48 is shiny (1 in 24 after a proper farewell); a shiny charm in the bag is used on the next egg and makes it four times as likely.
Mega Evolution
Use a Mega Stone from the bag: 41 species (Charizard X, Mewtwo Y, Gengar, Lucario, Rayquaza...) Mega Evolve for 24 hours and then change back. It adds 15% in the tournament and the gyms. If your companion has no Mega form the stone is not used up.



08
Pokédex, farm and album
1,025 Pokémon in nine regions, and a home for everyone you have raised.
Pokédex
- Swipe right from the main screen: one cover per region. Swipe on for the next region, tap a cover for its grid (up and down for pages), tap a Pokémon for its page.
- A species is registered when you raise it: by hatching it or by evolving into it.
- The nine regions open in order: the next one opens once every common and rare species of the current one is registered.
- Completing a region gives 200 points, a crown and a shiny legendary egg of that region.
Farm
- Long press your companion to send it to the farm. Swipe left for activities and tap Farm to visit.
- Farm Pokémon keep growing at a tenth of the speed (without evolving), come back healthy, and sometimes walk across the main screen.
- You can take one back at any time. You need two in the farm to enter the gyms, and different types open more of Fun.
Album and backup
The album button is at the bottom of the farm: one page for every companion that has left, with its dates, level, medals and how it ended. The whole game is backed up to the SD card once a day (Wi-Fi details are not included). In settings, BACKUP saves a fresh copy at any moment or restores it; both ask first.





09
Tournament
Eleven sports events. Nobody fights and nobody taps: you choose the event and watch.
Swipe left, tap Tournament and pick an event. Your companion competes against two Pokémon drawn at random. The result depends on its species' stats (each event weighs them its own way), its training, its evolution stage, Mega Evolution (+15%), its type and a little luck, so the strongest doesn't always win.
| Event | What counts | Type bonus |
|---|---|---|
| 100m dash | Speed | Electric +15%, Fighting +10% (Rock, Steel -10%) |
| Hurdles | Speed and spring | Fighting +15%, Bug +10% (Rock, Steel -10%) |
| 50m swim | Speed and stamina | Water +25%, Ice +10% (Fire, Rock -15%) |
| Long jump | Power and speed | Fighting, Flying +15% (Rock, Steel -10%) |
| High jump | Power | Flying +25%, Psychic +15% (Rock, Steel -15%) |
| Weights | Power and steadiness | Fighting +20%, Steel, Rock +15% (Flying, Fairy, Bug -10%) |
| Climbing | Power and agility | Rock +20%, Ground +15%, Bug +10% (Water, Steel -10%) |
| Diving | Technique | Water +20%, Psychic, Flying, Fairy +10% (Fire, Rock -15%) |
| Skating | Speed | Ice +25%, Fairy +10% (Fire -15%) |
| Torch run | Stamina | Fire +25%, Dragon +10% (Water, Ice -10%) |
| Trail run | A bit of everything | Dark, Ghost +15%, Poison, Grass +10% (Steel, Rock -10%) |
TipPick the event that suits its type: a Water type in the pool, a Fire type in the torch run. The first gold of the day gives a Mega Stone.
Competing tires it a little. It can't take part while asleep, sick or very tired.



10
Gyms and the League
72 gyms with the leaders and badges from the games. Still sport: a three-against-three team contest.
- 1Swipe left and tap Gyms. The list is also your badge case; swipe left and right to change region.
- 2Your team is your companion plus two Pokémon from the farm. Each gym picks the three events that suit its type best.
- 3Before starting you can swap who does which event. The leader puts each of theirs where it does best.
- 4Each event is one against one. Win two of the three and the badge is yours.
- Gyms open with their region and go in order: you need the badge of the one before. One try per gym per day.
- Each gym is harder than the last: the leaders' Pokémon get better genes and more training.
- Badges 2, 4 and 6 of a region also give a rare egg; badge 8 gives a legendary egg.
- With all 8 badges the region's League opens: the Elite Four and then the Champion, one after the other (one try a day). The first win gives a legendary egg and a shiny charm.
TipTeammates use their own training, so feed orchard fruits to the farm Pokémon you take to the gyms.



11
Fun
Four little activities, one for every type. They cost points and never give any.
Swipe left and tap Fun. Your companion goes if it is the right type (and awake, healthy and not too tired); otherwise you pick one of the right type from the farm. That is why collecting different types pays off.
| Activity | Types | Cost | How | What you get |
|---|---|---|---|---|
| Orchard | Grass, Bug, Ground, Poison, Fairy | 8 per plot | 3 plots in real time: plant, water once (ripe in 12 h, or 24 h without water), harvest | 2-3 fruits |
| Fishing | Water, Ice, Dragon | 5 | Cast, then tap when the float dips | Fish, pearls, now and then a water-type egg |
| Mining | Rock, Steel, Fighting, Fire | 10 | Tap the rock until it breaks | Mega Stone shards (10 make a stone), sometimes a fossil egg |
| Treasure | Normal, Flying, Electric, Psychic, Ghost, Dark | 8 | It sets off for an hour, then you collect | Candy, medicine, potions, an accessory, rarely a shiny charm |
TipChess brings luck the same day: if you played, one more thing from every activity; if you won, rare finds are twice as likely.
- Fruits raise training: stamina, resistance and vitality fruit +3 each; the gold fruit +3 to all three and full joy. Up to 3 a day per Pokémon count (after that they are just a snack).
- Farm Pokémon can eat fruits too: open one in the farm and tap a fruit at the top of its page.
- Fish fills it up and a pearl makes it very happy. Both, and the fruits, appear as a second row in the Feed menu.
- While your companion is out on a treasure hunt, the main screen shows a sign with the minutes left.



12
Friends: meet and mail
When a friend has a board too. Meeting and mail never give points.
Becoming friends
- 1Put the two boards side by side. On both, swipe left, tap Friends and then Meet.
- 2Each board finds the other. Tap the other board and say yes on both.
- 3Both screens show the same 4-digit code. If it matches, you are friends.
While the Meet page is open the boards talk to each other directly by radio and home Wi-Fi pauses; it comes back when you close the page or after 3 idle minutes.
With a friend nearby
- Play: the two Pokémon run, catch and dance together. Tap your own Pokémon at the same moment and they high-five.
- Gift: pick something from the bag. It only goes if your friend accepts; otherwise it comes back.
- Race and gyms together: a tournament race with a third random rival; at a gym the one who invites brings two and the friend's companion is the third.
- Photo: one per friend per day, the first time you meet, kept on the SD card. The Pokédex also marks the species a friend has raised.
Mail, when you are apart
- Visit: your companion goes to their screen, says hello and stays a few minutes.
- Postcard: a messenger (your companion or a farm Pokémon) carries one of 12 phrases and one of 8 pictures.
- Gift: an item from the bag, taken out when it is sent.
Mail arrives at the next sync: every 15 minutes when plugged in, with the weather on battery, or right away with Sync now on the friend's page. The messenger walks onto your friend's main screen and waits with an envelope or a gift box until it is tapped. A gift that never arrives comes back after 14 days. Everything is encrypted with the key the two boards made when they paired.




13
More to discover
Surprises in the grass, real weather, holidays, and points from a phone.
Surprises in the grass
Now and then a tuft of grass rustles on the main screen. Tap it. There is one a day (two candies, a medicine, a potion or a common egg), one a week from Monday (a rare egg, a shiny charm or both potions; blue sparkles) and one a month (a legendary egg, a Mega Stone or an evolution potion; gold sparkles). They never give points.
Weather, seasons and holidays
- With Wi-Fi the board shows the real weather where you live: rain, snow, fog and storms, with sunrise and sunset. Weather changes moods by type: Water types enjoy rain, Ice types enjoy snow, Grass types enjoy sun.
- The scenery follows the seasons and thirteen holidays, from New Year and Lunar New Year to Halloween and Christmas, and there is a birthday too.
- Standby clock: plugged in and untouched for 90 seconds, the screen becomes a large clock with the date and the weather. Tap to go back.
Steps from an iPhone
Handy when the board stays at home. The board must be plugged in and on the home Wi-Fi, the phone on the same network. Your code is on the stats page (settings, then stats).
- 1In the Shortcuts app: Automation, New Automation, Time of Day (for example 9:00 PM, daily), Run Immediately.
- 2Add Find Health Samples: Type is Steps, Start Date is Today.
- 3Add Calculate Statistics: Sum of the Health Samples.
- 4Add Get Contents of URL: http://tamapoke.local/steps?n= + the Sum + &k= + your code.
The first time, allow local network access. The board keeps the higher of the phone's count and its own, so nothing is counted twice.
Hockey practice from an iPhone
- 1A new shortcut with Ask for Input: type Number, prompt “Minutes of hockey practice?”.
- 2Add Get Contents of URL: http://tamapoke.local/hockey?min= + Provided Input + &k= + your code (the same one as for steps).
1 point every 5 minutes, up to 6 a day. Keep the shortcut on a parent's phone so the points stay honest.
Rewards from a parent's iPhone
- 1A new shortcut with Ask for Input: type Number, prompt “How many points? (1-10)”.
- 2Add Get Contents of URL: http://tamapoke.local/reward?pts= + Provided Input + &k= + your code (the same one as for steps).
1 to 10 points at a time, for chores, reading or a good day, up to 20 a day. The board wakes up and shows the reward; the points book has a line for it. Same conditions: board plugged in, phone on the same Wi-Fi.
Voice control
With a Stack-chan or another xiaozhi voice assistant, the board can be asked how the pet is and told to feed it, play, bathe it or put it to bed. The setup is in the README.




14
If something looks wrong
The questions that come up most.
The screen is black and touching it does nothing.
Press PWR. The screen was turned off with the button, or by itself after 5 minutes on battery, and then only the button turns it back on. If nothing happens, the battery may be empty or the board switched off: plug it in.
I played chess and got no points.
Check four things: the game had 10 minutes or more on the clock (bullet, blitz and bots don't count); the username on the Wi-Fi page is right; the board has synced since (at midnight, at the next start, or with Sync now); and it wasn't the very first sync, which only records where you stand.
It won't connect to Wi-Fi.
The board only uses 2.4 GHz networks. On an iPhone hotspot turn on Maximize Compatibility. To change a network, open the Wi-Fi page again and fill in only the field you want to change.
I bought an egg but can't open it.
An egg opens only when you have no companion. Long press your current one and send it to the farm; you can take it back later.
The gyms won't let me in.
You need two Pokémon in the farm for the team, and the badge of the gym before. Each gym allows one try a day.
It is sick.
Feed, then Medicine (3 points in the shop). If there is one in the bag, it takes it by itself after 10 minutes awake. Clean up poops and go easy on candy to keep it healthy.
The evolution button doesn't appear.
All four needs must be at 40 or more, and each care mistake adds 2 hours to the wait. An evolution potion (100 points) evolves it at once.
I got a new board. Can I move my game to it?
Yes. On the old board open settings, tap BACKUP and SAVE NOW. Put its SD card in the new board (the card also holds the farm, the album and the friend photos). Flash the new board, pick any starter, set up Wi-Fi so the clock is right, then tap BACKUP and RESTORE. Wi-Fi details are the only thing that does not move. When the new board looks right, erase the old one with the web installer so two boards don't share one game.
Will an update erase my game?
No. The web installer only replaces the program. The backup on the SD card is a second copy: tap BACKUP and SAVE NOW in settings before updating if you want it fresh, and RESTORE brings it back.