Skip to content

Turn a ~$5 AliExpress clock into a physical AI usage dashboard (Claude, Codex, multi-account). No firmware flashing.

Add a runnable Game Boy face customization example

click6067-ship-it0a3f48dbbac0
diff --git a/docs/clock-faces.md b/docs/clock-faces.md
index 86464ac..659579f 100644
--- a/docs/clock-faces.md
+++ b/docs/clock-faces.md
@@ -98,3 +98,7 @@ It is not a live ranking. Older installs show "update TokenTV" instead of downlo
- **One picture, 240×240, JPEG.** `render_page` saves the image; animated faces return GIF
bytes like `token_tv/space.py`.
- Fonts must be in `token_tv/web/` with their license file next to them.
+
+## Worked example
+
+[Pixel → Game Boy](../examples/gameboy/README.md) includes the render function, the same sample data before and after, and an old/missing-data check. It was made with Claude Code and runs without a clock or account.
diff --git a/examples/gameboy/README.md b/examples/gameboy/README.md
new file mode 100644
index 0000000..11d794d
--- /dev/null
+++ b/examples/gameboy/README.md
@@ -0,0 +1,30 @@
+# Game Boy style face — example
+
+**Request:** «게임보이 스타일로 시계 화면 바꿔줘» ("change the clock face to a Game Boy style")
+**Made by:** the TokenTV author with Claude Code (CC). Sample data only, not a real account.
+This is a separate example. It is **not** registered as a product theme and was not applied to any clock.
+
+| before (built-in Pixel) | after (Game Boy) | after, old + unknown |
+| --- | --- | --- |
+| ![before](before.png) | ![after](after.png) | ![old/unknown](after-old-unknown.png) |
+
+The first two images use the same sample: Claude A 25% (5H, 3h 41m), Codex A 72% (WK, 2d 6h), Grok A 94% (BUD, 12d 3h).
+The third image marks Codex as an old reading and gives Grok no data.
+
+## Run
+
+```bash
+PYTHONPATH=. python3 examples/gameboy/gameboy.py
+```
+
+## What the face does
+
+- Four LCD shades only (`#0f380f #306230 #8bac0f #9bbc0f`). The final image is snapped to those four.
+- Each pixel bot uses the darkest shade; text is the Press Start 2P pixel font bundled with TokenTV.
+- Keeps the meaning of every value: used %, window (5H/WK/BUD), reset time, account label.
+- Old reading: "OLD" next to the window and a hatched gauge. No data: a dash, "NO DATA" and an empty dotted gauge, never 0%.
+
+## Checked (2026-10-04)
+
+- All three images are 240×240. `after.png` and `after-old-unknown.png` contain exactly 4 colours.
+- Viewed at real size (1×) and 3×; labels, numbers and reset times are readable. The smallest text ("RESET", 7 px) is legible but small.
diff --git a/examples/gameboy/after-old-unknown.png b/examples/gameboy/after-old-unknown.png
new file mode 100644
index 0000000..b414599
Binary files /dev/null and b/examples/gameboy/after-old-unknown.png differ
diff --git a/examples/gameboy/after.png b/examples/gameboy/after.png
new file mode 100644
index 0000000..f1a95ea
Binary files /dev/null and b/examples/gameboy/after.png differ
diff --git a/examples/gameboy/before.png b/examples/gameboy/before.png
new file mode 100644
index 0000000..509dad2
Binary files /dev/null and b/examples/gameboy/before.png differ
diff --git a/examples/gameboy/comparison.png b/examples/gameboy/comparison.png
new file mode 100644
index 0000000..57e587a
Binary files /dev/null and b/examples/gameboy/comparison.png differ
diff --git a/examples/gameboy/gameboy.py b/examples/gameboy/gameboy.py
new file mode 100644
index 0000000..544664c
--- /dev/null
+++ b/examples/gameboy/gameboy.py
@@ -0,0 +1,70 @@
+"""Game Boy style clock face, written for the request «게임보이 스타일로 시계 화면 바꿔줘».
+
+A separate example: it is not registered as a product theme. Four-shade LCD palette only.
+Run from the repository root:
+ PYTHONPATH=. python3 examples/gameboy/gameboy.py
+"""
+import io
+import sys
+import time
+from pathlib import Path
+
+from PIL import Image
+
+from token_tv.display import account_label, overview_rows, render_page, row_shift
+from token_tv.sample import D, H, snapshot
+from token_tv.themes import Canvas, bot_sprite, face, gauge, number_text, place_bot, reading
+
+DARKEST, DARK, LIGHT, LIGHTEST = '#0f380f', '#306230', '#8bac0f', '#9bbc0f'
+PALETTE = [DARKEST, DARK, LIGHT, LIGHTEST]
+OUT = Path(__file__).resolve().parent
+
+
+def to_four_shades(image):
+ """Snap every pixel to the nearest of the four LCD shades (the real Game Boy had only four)."""
+ palette = Image.new('P', (1, 1))
+ flat = [int(c[i:i + 2], 16) for c in PALETTE for i in (1, 3, 5)]
+ palette.putpalette(flat + [0] * (768 - len(flat)))
+ return image.convert('RGB').quantize(palette=palette, dither=Image.Dither.NONE).convert('RGB')
+
+
+def render_gameboy(data):
+ cv = Canvas(LIGHTEST)
+ pixel = lambda size: face('press-start-2p.ttf', size)
+ rows = overview_rows(data)
+ pitch = 79
+ for index, row in enumerate(rows):
+ y = 3 + index * pitch + row_shift(len(rows), pitch)
+ used, period, old, reset = reading(row) # used is None when nothing was reported
+ cv.draw.rectangle((4, y, 235, y + 74), outline=DARKEST, width=2)
+ cv.draw.rectangle((7, y + 3, 232, y + 71), outline=DARK, width=1)
+ place_bot(cv.ink, bot_sprite(row['provider'], 22, 18, DARKEST, LIGHTEST), (11, y + 7, 22, 18))
+ cv.text((38, y + 11), account_label(row), pixel(8), DARKEST)
+ cv.text((229, y + 11), ('OLD ' if old else '') + period, pixel(8), DARK, anchor='ra')
+ cv.text((12, y + 31), number_text(used), pixel(20), DARKEST) # a dash, never a fake 0
+ if used is not None:
+ cv.text((12 + cv.draw.textlength(number_text(used), font=pixel(20)) + 2, y + 39), '%', pixel(10), DARKEST)
+ cv.text((229, y + 34), 'RESET', pixel(7), DARK, anchor='ra')
+ cv.text((229, y + 45), reset, pixel(8), DARKEST, anchor='ra')
+ gauge(cv, (12, y + 58, 227, y + 66), used, (DARKEST, DARK), gap=2, track=LIGHT, empty=DARK, stale=old)
+ return to_four_shades(cv.finish())
+
+
+def sample(stale_and_unknown=False):
+ data = snapshot(time.time(), [
+ ('claude_a', 'CLAUDE A', 'claude', [('5H', 25, 3 * H + 41 * 60)]),
+ ('codex_a', 'CODEX A', 'codex', [('WEEK', 72, 2 * D + 6 * H)]),
+ ('grok_a', 'GROK A', 'grok', [] if stale_and_unknown else [('BUDGET', 94, 12 * D + 3 * H)]),
+ ])
+ if stale_and_unknown:
+ data['accounts']['codex_a']['status'] = 'stale'
+ return data
+
+
+if __name__ == '__main__':
+ before = Image.open(io.BytesIO(render_page(sample(), style='pixel'))).convert('RGB')
+ before.save(OUT / 'before.png')
+ render_gameboy(sample()).save(OUT / 'after.png')
+ render_gameboy(sample(stale_and_unknown=True)).save(OUT / 'after-old-unknown.png')
+ print('wrote before.png, after.png, after-old-unknown.png')
+ sys.exit(0)