A magic 8-ball you print yourself. Ask a yes-or-no question, shake or tap, and a blue triangle swirls up with your answer. Print two parts, click in an ESP32-S3 touch screen, and learn how states, random numbers and motion sensors work.
| Qty | Part | Type |
|---|---|---|
| 1 |
Waveshare ESP32-S3-Touch-LCD-1.28 board
The brain, a round 1.28-inch touch screen and a motion sensor in one board. No soldering.
|
electronics |
| 2 |
Printed parts
Back cup and front ring. Both are in the 3MF below on one plate, no supports.
|
printed |
| 1 |
USB-C data cable
Powers the board and loads the program. It must be a data cable, not a charge-only one.
|
electronics |
| 11 g |
PLA filament
Black makes it look like a real 8-ball. Any PLA works.
|
consumable |
| 1 |
Chrome or Edge browser
Loads the program onto the board straight from this page. Nothing to install.
|
| 1 |
VS Code + PlatformIO (optional)
Free. Only needed if you want to change the code later. See 'Level up' at the end.
|
Flash writes a precompiled image over USB-C in Chrome or Edge. The .ino below is the source — you do not need Arduino IDE unless you want to change the sketch.
A magic 8-ball that fits in your hand. Ask it a yes-or-no question, then shake it or tap the glass. The big 8 fades away, a window opens, and a blue triangle floats up with your answer. Twenty answers, including a few that only a 3D-printing fan would give.
No soldering. No wires. You print two parts, drop in one board, push the halves together, plug in one cable, and click one button on this page to load the program.
It isn't magic, it's maths. The answer is picked by a random number generator inside the chip, the same way a video game rolls dice. The swirl is only there to build suspense. (So maybe don't use it for big decisions.)
Same case, different toy. This round case is shared with the touch doodle. Black looks like a real 8-ball, but any colour works.
Before you start. The printer works on its own for about 25 minutes. You do about 5 minutes of clicking parts together and 2 minutes of loading the program. No tools needed.
One plate, two parts, one colour. Start the printer, then read Part 2 while it works.
Grab Print-ready 3MF from Files & downloads above and open it in Bambu Studio. Using another slicer? Open the STL instead; both parts are in it, already lying flat.
Settings are already in the file: 0.2 mm layers, 2 walls, 15% infill, no supports. The cup prints with its back on the plate, open side up, and the ring prints flat. About 25 minutes on a Bambu P1S.
Run a fingertip around the inside of the cup and the ring. Pick off any strings or blobs, especially around the USB-C window in the side of the cup and the notch in the ring. The board has to slide in without catching.
No glue, no screws. Three moves: board into the ring, ring into the cup, check the port. If a part feels tight, wiggle it; never force it.
Lay the front ring on the table. Put the board in screen-down, so you are looking at the back of the board with all the little chips. Turn it until the USB-C port sits in the notch of the ring.
Pick up the ring with the board in it. Tilt it and slide the USB-C end in first, so the port pokes into the window in the side of the cup. Then lower the other side down.
Press around the ring until it sits flush with the cup all the way round. Look at the side window: the USB-C port should sit right in the middle, so the cable plugs in straight and doesn't pull the board sideways.
New boards come with a factory demo. You are going to replace it with the 8-ball program, straight from this web page. That takes about a minute.
Word to know: flash. Flashing means copying a program onto a chip. The chip keeps it even when unplugged, like saving a game.
Connect the USB-C cable from the board to a computer (Windows, Mac, Chromebook or Linux). It must be a data cable, not a charge-only one.
Scroll up to Files & downloads and click Flash to board. Use Chrome or Edge. Pick the port that appears, click Install, and wait for the green tick.
A black ball with a big white 8 appears. It's waiting for your first question.
No port in the list? The BOOT button is hidden inside the case. Push the board out through the slot in the back, hold BOOT while you plug the cable in, let go, then click Flash again. Phones and Safari can't flash; use a computer.
Ask it anything with a yes or no answer. Then:
Hold the puck and its cable together and give it a firm shake. The 8 fades, the blue window swirls, and after about a second and a half the triangle rises with your answer.
Don't feel like shaking? Tap the glass once. Same thing.
Too much suspense? Tap while it swirls and the answer appears straight away.
When you've read it, tap once and the 8 comes back, ready for the next question.
A hard shake makes a longer, wilder swirl: 2.4 seconds instead of 1.6, with extra particles. The answer is just as random either way.
You don't need to read the whole program (it's in Files & downloads if you're curious). Each lesson below shows the one small piece of code that does the job, and gives you something to try.
At any moment the 8-ball is doing exactly one of three things: idle (showing the 8), swirl (building suspense) or reveal (showing the answer). Programmers call this a state machine.
The same tap means something different in each state. That's why one finger is enough to ask, skip and go back.
enum State { ST_IDLE, ST_SWIRL, ST_REVEAL }; // the only three things it can be doing
static void onTap() {
if (state == ST_SWIRL) { startReveal(now); return; } // impatient? jump to the answer
if (state == ST_REVEAL) { goIdle(); return; } // done reading: back to the 8
startSwirl(now, false); // waiting: a tap asks the question
}Simplified from onTap().
Try it: draw the three states as bubbles on paper and add an arrow for every way to get from one to the next (tap, shake, time's up). How many arrows do you need? (Hint: the swirl ends by itself after 1.6 seconds, so that's an arrow too.)
The board has a motion sensor that measures pushes in three directions (an accelerometer) and spinning (a gyroscope). Lying still, it feels exactly 1 g: gravity. A shake pushes it far above or below 1 g.
One bump shouldn't ask a question, so the program uses a leaky bucket. Every reading, the bucket loses 16% of what's in it and each jolt pours a little in. A single bump leaks away. A real shake fills it past the line. After that, it ignores motion for 0.9 seconds, so one shake asks one question.
const float dev = fabsf(mag - 1.0f); // how far from plain gravity (1 g)?
const float accTerm = dev > 0.28f ? (dev - 0.28f) * 0.48f : 0; // ignore tiny wobbles
const float gyroTerm = gyro > 130 ? (gyro - 130) / 1300.0f : 0; // spinning counts too
shakeEnergy = shakeEnergy * 0.84f + accTerm + gyroTerm; // the leaky bucket
if (shakeEnergy > 2.35f) shaking = true; // full enough: that's a shake
if (state == ST_IDLE && shaking) startSwirl(now, shakeEnergy > 3.2f); // over 3.2 = big swirlSimplified from updateMotion().
Try it: put the puck on the table and tap the table hard. Does it ask a question? Usually not: one bump leaks out of the bucket before it fills. Now pick it up and shake. Type status in the Serial Monitor straight after to see the energy= number.
esp_random() asks the chip's built-in random number generator for a huge random number. The % sign means remainder after dividing: any number % 20 gives something from 0 to 19, one for each answer. Like rolling a 20-sided dice.
Real randomness can give the same answer twice in a row, which feels broken. So if the new answer matches the last one, it rolls again.
static void pickFortune() {
int next = esp_random() % FORTUNE_COUNT; // roll a 20-sided dice: 0 to 19
while (next == lastFortune) { // same as last time?
next = esp_random() % FORTUNE_COUNT; // roll again
}
fortuneIndex = next;
lastFortune = next;
}Simplified from pickFortune().
Try it: ask 20 questions and tick off each answer you get. Do you see all 20? Almost certainly not! On average you need about 70 shakes to collect every answer. Mathematicians call this the coupon collector's problem, and it's why sticker albums take forever to fill.
When the swirl starts, the program sets a stopwatch. Every frame it works out how far through the swirl it is, as a number u from 0 (just started) to 1 (finished). Every moving part is worked out from that one number: the 8 fades in the first 22%, the window opens by 38%, the triangle rises after halfway, and the words appear at the very end.
easeOut makes things start fast and slow down gently, like a ball rolling to a stop. That's why it feels smooth instead of robotic.
float u = (now - swirlAt) / (float)swirlMs; // 0 at the start, 1 at the end
eight = 1 - easeOut(u / 0.22f); // the 8 fades in the first 22%
winR = WIN_R * easeOut(u / 0.38f); // the window opens by 38%
triRise = easeOut((u - 0.48f) / 0.40f); // the triangle rises after halfway
textFade = easeInOut((u - 0.82f) / 0.16f); // the words appear at the very endSimplified from drawFrame(). The real code also clamps each value so it stays between 0 and 1.
Try it: watch a swirl and spot the four moments: 8 fades, window opens, triangle rises, words appear. Then do a hard shake: same four moments, stretched over 2.4 seconds.
Why doesn't it flicker? Every frame is drawn into a sprite: a 240 × 240 picture kept in memory (about 115 KB). Only when it's finished does the program copy it to the screen in one go. Like finishing a drawing before you hold it up.
Your computer can chat with the board through the same USB-C cable. That chat is called serial. Open the Serial Monitor in VS Code (the plug icon in the PlatformIO bar) or any serial app at 115200, type a word, press Enter.
| Type this | What happens |
|---|---|
help |
lists the commands |
tap |
same as tapping the glass |
shake |
starts a swirl without shaking |
fortune |
shows a new answer instantly, no swirl |
status |
tells you the state (idle, swirl or reveal), the answer number and the shake energy |
Spy on the answers. Every time an answer appears, the board also types it into the Serial Monitor, like fortune: THE SPAGHETTI KNOWS. Leave the monitor open and you get a list of every answer it has given.
Ready to make it yours? The easiest way to change the code is PlatformIO, a free add-on for VS Code. It downloads the right libraries and settings for this board by itself.
fortune-8ball-platformio folder in VS Code (File → Open Folder).fortune-8ball/fortune-8ball.ino. Find the FORTUNES list near the top.Ideas, easiest first:
SWIRL_MS = 1600 to 3000.SHAKE_ENTER from 2.35f to 1.8f.static const Fortune FORTUNES[] = {
{"IT IS", "CERTAIN"},
...
{"ASK YOUR", "PRINTER"},
{"THE SPAGHETTI", "KNOWS"},
{"PIZZA FOR", "DINNER"}, // your own answer: top line, bottom line
};One answer is one line. The program counts the answers by itself.
Licensed under CC BY-SA 4.0. Check with the author before commercial use.
Built this? Share a photo of your print so others can see how it turned out.
Flash firmware
