Desk Pal buddy

A little round buddy that lives on your desk. He looks around, blinks, follows your finger, gets bored when you ignore him, falls asleep when he's tired, and wakes up grumpy if you poke him too early.

Every minute or two he does something on his own: shakes maracas, puts on pixel sunglasses, reads a book, blows a bubblegum bubble. Every hour he drinks a glass of water and reminds you to do the same.

No soldering. Print the case, click the board in, and flash the program from your browser in about two minutes.

• How a game loop makes a character feel alive, about 33 times a second
• How a face can be just 12 numbers, and how easing makes them move smoothly
• How moods come from simple stats: energy, affection and annoyance
• How to turn raw touch points into taps, double taps, long presses and pets
• How a motion sensor tells a tilt from a shake

• The board: Waveshare ESP32-S3-Touch-LCD-1.28. The round screen is his face, the touch layer is his skin, and the motion sensor is his inner ear. It has Wi-Fi too, but he doesn't need it.
• The inner ring: holds the board snugly with a notch for the USB-C port.
• The main frame: his body. The ring slides in from the front and the cable comes out of the side window.
• The foot: clips on the back and tilts him toward you.
• The cable: a USB-C data cable. It powers him all the time and loads the program once.

Open desk-buddy.ino and follow along. Each lesson points at a real piece of the program.

loop() runs thousands of times a second, but only every 30 ms does he think, move and draw:

if (now - lastFrame >= 30) {   // about 33 frames a second
  brainUpdate(dt);             // stats, moods, timers
  animate(dt);                 // move the face toward its target
  render();                    // draw in memory, then send to the screen
}

He draws the whole face into a 240 × 240 picture in memory (a sprite) and sends it to the screen in one go. That's why nothing flickers.

Try it: change 30 to 100. He still works, but moves like an old cartoon.

Every mood is one row in a table: eye width, eye height, roundness, top lid, lid slant, cheek, mouth curve, mouth open, mouth width, blush, and the size of each eye.

//  ew  eh  er  lidT  lidA  lidB  curve  open  mW  blush
{  56, 72, 20, 0.00,  0,  0.00,  0.35,  0.0, 22,  0.0 }, // neutral
{  56, 66, 16, 0.34, 11,  0.00, -0.70,  0.0, 24,  0.0 }, // grumpy

Grumpy is just a lower top lid (lidT), slanted inward (lidA), and a frown (a negative curve). He never jumps between faces. Every frame, each number moves a little closer to its target. That's called easing, and it's why expressions melt into each other.

Try it: give happy a blush of 1.0.

He keeps three numbers about how he feels:
- energy drains slowly while he's awake and refills while he sleeps
- affection goes up with taps and pets, and fades if you ignore him
- annoyance jumps with every poke and cools down fast

Every few seconds he checks them, plus how long it's been since you touched him, and picks a mood:

if (energy < 8)                              m = M_ASLEEP;
else if (energy < 25)                        m = M_SLEEPY;
else if (idleS > lonelyS && affection < 60)  m = M_SAD;
else if (idleS > boredS)                     m = M_BORED;

The personality traits at the top of the file just stretch these numbers. A cuddly buddy gets lonely sooner, and a grumpy one gets annoyed faster.

Try it: set TRAIT_GRUMPY to 10 and poke him.

The touch chip only says a finger is here, at x and y. Gestures are something we work out ourselves from time and distance:
- down and up quickly, barely moved: tap
- two taps within 0.38 s: double tap
- held still for 0.75 s: long press
- moved more than 160 pixels in total: pet

tTravel += sqrtf(dx * dx + dy * dy);   // add up how far the finger moved
if (tTravel > petTravelNext) onPet();

That's Pythagoras doing robot petting.

Try it: make petting easier by lowering 160.

The motion sensor measures acceleration in three directions. When he sits still, the only acceleration is gravity, so the reading tells him which way is down. That's tilt.

A shake is the reading changing quickly. He adds up how much it changes between readings and lets the total fade:

shakeLevel = shakeLevel * 0.9f + jerk;
if (shakeLevel > 9.0f)       onShake();   // dizzy!
else if (shakeLevel > 2.8f)  onBump();    // surprised

He also slowly learns his resting position, so he works whichever way your case holds him.

Try it: type imu in the serial monitor and tilt him.

Open a serial monitor at 115200 (the Arduino IDE Serial Monitor, or any other) and type:
- help: list commands
- status: mood, energy, affection and pets
- mood love: show a mood (happy, love, excited, surprised, curious, bored, sleepy, asleep, grumpy, sad, dizzy)
- act: list his activities. act shades or act random plays one
- remind water, remind move, remind grass: play a reminder now
- name Pixel: rename him. He remembers.
- imu: show tilt readings
- reset: wipe his memory. He'll meet you again.

Everything you'd want to change is in the YOUR SETTINGS block at the top of desk-buddy.ino:
- BUDDY_NAME and four traits from 0 to 10: TRAIT_ENERGY, TRAIT_CUDDLY, TRAIT_GRUMPY, TRAIT_CURIOUS
- EYE_COLOR: try 0xFFB000 for amber or 0x7CFF6B for green
- WIFI_SSID, WIFI_PASSWORD, TIMEZONE: adds the clock, morning greetings, an hourly bounce and a bedtime (2.4 GHz Wi-Fi only)
- WATER_EVERY_MIN, MOVE_EVERY_MIN, GRASS_EVERY_MIN: reminder timing. 0 turns one off
- ACTIVITY_MIN_SEC / ACTIVITY_MAX_SEC: how often he does activities
- SHOW_SPEECH 1: lets him talk in little speech bubbles

Easiest way: unzip the PlatformIO project, open the folder in VS Code with the PlatformIO extension, make your changes and click Upload.

Arduino IDE: install the esp32 boards by Espressif and the TFT_eSPI library by Bodmer. Replace libraries/TFT_eSPI/User_Setup.h with the contents of TFT_eSPI_Setup.h. Put desk-buddy.ino and s3_puck_pins.h in a folder called desk-buddy. Board: ESP32S3 Dev Module, Flash Size 16MB, PSRAM QSPI PSRAM. Upload.

• Black screen after flashing. Press RESET, or unplug him and plug him back in. Still black? Flash again.
• No port in the list. Try another cable first. Most problems are charge-only cables. Then hold BOOT, tap RESET, let go of BOOT and try again. On Windows you may need the WCH CH34x driver.
• His face is sideways. Change SCREEN_ROTATION (0 to 3) at the top of the code.
• His eyes look uphill when you tilt him. Flip TILT_FLIP_X or TILT_FLIP_Y.
• Nothing in the serial monitor. Set it to 115200 baud and press RESET. Close any other window using the port.
• He's always sad. He's lonely. Pet him. A high TRAIT_CUDDLY makes him lonely faster.
• He's asleep in the middle of the day. He ran out of energy. Tap to wake him, or let him nap: he's fully rested about 30 minutes after he falls asleep.