Skip to content

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

SmallTV-Ultra: back up a new unit that has no /app.json yet

Oleksii Kalentieved1906e34ba4
diff --git a/docs/hardware-compatibility.md b/docs/hardware-compatibility.md
index 05c448e..4d836d5 100644
--- a/docs/hardware-compatibility.md
+++ b/docs/hardware-compatibility.md
@@ -8,7 +8,7 @@ not "probably fine".
| Clock | Firmware web UI | What TokenTV uses | Checked |
| --- | --- | --- | --- |
| The author's 240×240 GeekMagic SmallTV-style Wi-Fi clock (receipt: ₩5,650 on a Korean AliExpress discount; prices vary by region) | Stock firmware with the **SD_PRO** web UI and a photo album | `/theme/list`, `/photo/list`, `/photo/upload`, photo theme id `2` | One unit, Linux host |
-| GeekMagic **SmallTV-Ultra** | Stock firmware `Ultra-V9.0.54` (`/v.json` reports `SmallTV-Ultra`) | `/app.json`, `/album.json`, `/doUpload?dir=/image/`, `/set?img=`, Photo Album theme `3` | The contributor's unit, running this release's code: photos and a display receipt in [#7](https://github.com/click6067-ship-it/token-tv/pull/7). The author has no Ultra |
+| GeekMagic **SmallTV-Ultra** | Stock firmware `Ultra-V9.0.54` (`/v.json` reports `SmallTV-Ultra`) | `/app.json`, `/album.json`, `/doUpload?dir=/image/`, `/set?img=`, Photo Album theme `3` | The contributor's unit, running this release's code: photos and a display receipt in [#7](https://github.com/click6067-ship-it/token-tv/pull/7). A second unit on a Raspberry Pi 4 (Linux aarch64), static and animated (GIF) faces: [#10](https://github.com/click6067-ship-it/token-tv/pull/10). The author has no Ultra |
TokenTV never flashes firmware and never deletes your photos. It uploads one picture, switches the
clock to its photo theme, and `token-tv run --restore-display` puts the original theme back.
@@ -18,11 +18,16 @@ the theme and autoplay back, but there is no known way to read which photo was s
TokenTV's picture can stay in the album. Delete `tokentv.jpg` / `tokentv.gif` on the clock's image page
if you want them gone.
+A new SmallTV-Ultra has no `/app.json` (it answers 404) until its theme is changed for the first time.
+TokenTV then records that there was no saved theme, switches to the Photo Album as usual, and on restore
+puts autoplay back but leaves the theme alone. Pick a theme on the clock's settings page afterwards if you
+want a different one.
+
## Not verified
- Other GeekMagic models, SmallTV Pro, and clones that look the same. A similar case is not evidence
of the same firmware.
-- SmallTV-Ultra on firmware other than `Ultra-V9.0.54`, and animated (GIF) faces on the Ultra.
+- SmallTV-Ultra on firmware other than `Ultra-V9.0.54`.
- Firmware without the photo album page or with different photo API paths.
- macOS and Windows hosts.
diff --git a/tests/test_device.py b/tests/test_device.py
index 5cfadf7..6c1bbbd 100644
--- a/tests/test_device.py
+++ b/tests/test_device.py
@@ -9,6 +9,7 @@ from contextlib import contextmanager
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from unittest.mock import patch
+from urllib.error import HTTPError
from urllib.parse import parse_qs, urlparse
from token_tv import live
@@ -131,6 +132,8 @@ def ultra_clock(state, calls):
if url.path == "/v.json":
return self.reply({"m": "SmallTV-Ultra", "v": "Ultra-V9.0.54"})
if url.path == "/app.json":
+ if state["theme"] is None: # a new unit has no /app.json until its theme is first set
+ return self.reply({}, 404)
return self.reply({"theme": state["theme"]})
if url.path == "/album.json":
return self.reply({"autoplay": state["autoplay"], "i_i": state["i_i"]})
@@ -224,6 +227,32 @@ class UltraTests(unittest.TestCase):
paths = [c[1] for c in self.calls]
self.assertFalse(any(word in p for p in paths for word in ("delete", "clear", "reset", "reboot", "update")))
+ def test_new_ultra_without_app_json_is_backed_up_shown_and_left_on_the_album(self):
+ # Seen on a new Ultra-V9.0.54 unit: /app.json is 404 until the theme is changed once.
+ self.state["theme"] = None
+ with serve(ultra_clock(self.state, self.calls)) as url:
+ display = open_display(url)
+ original = display.capture()
+ self.assertEqual(original, {"model": "ultra", "theme": None, "autoplay": 1, "i_i": 5})
+ self.assertEqual(json.loads(json.dumps(original)), original) # survives display-original.json
+
+ start = len(self.calls)
+ display.activate(original)
+ self.assertEqual(self.calls[start:], [("GET", "/app.json"), ("GET", "/album.json"), ("GET", "/set?i_i=5&autoplay=0"),
+ ("GET", "/set?theme=3"), ("GET", "/set?img=%2Fimage%2Ftokentv.jpg")])
+ self.assertEqual((self.state["theme"], self.state["img"]), (3, "/image/tokentv.jpg"))
+
+ # No theme was saved, so restoring puts autoplay back and does not invent a theme.
+ start = len(self.calls)
+ display.restore(original)
+ self.assertEqual(self.calls[start:], [("GET", "/set?i_i=5&autoplay=1")])
+
+ def test_ultra_app_json_errors_other_than_404_still_fail(self):
+ with serve(answering(500, b"")) as url:
+ with self.assertRaises(HTTPError) as raised:
+ UltraDisplay(url).capture()
+ self.assertEqual(raised.exception.code, 500)
+
def test_ultra_activate_does_not_copy_clock_values_into_the_query(self):
self.state["i_i"] = "5&theme=0"
with serve(ultra_clock(self.state, self.calls)) as url:
diff --git a/token_tv/device.py b/token_tv/device.py
index 0143619..301a816 100644
--- a/token_tv/device.py
+++ b/token_tv/device.py
@@ -2,6 +2,7 @@
import json
import uuid
from http.client import HTTPException
+from urllib.error import HTTPError
from urllib.parse import quote, urlencode, urlparse
from urllib.request import Request, urlopen
@@ -102,8 +103,14 @@ class UltraDisplay(PhotoDisplay):
PHOTO_THEME = 3
def capture(self):
- _, raw = self.request("/app.json")
- theme = json.loads(raw)["theme"]
+ # A new clock has no /app.json (404) until its theme is first changed: there is no saved theme to restore.
+ try:
+ _, raw = self.request("/app.json")
+ theme = json.loads(raw)["theme"]
+ except HTTPError as error:
+ if error.code != 404:
+ raise
+ theme = None
_, raw = self.request("/album.json")
album = json.loads(raw)
return {"model": self.MODEL, "theme": theme, "autoplay": album["autoplay"], "i_i": album["i_i"]}
@@ -132,7 +139,8 @@ class UltraDisplay(PhotoDisplay):
def restore(self, original):
# There is no known way to read the previously shown image, so only the album settings and theme return.
self.request(f"/set?i_i={int(original['i_i'])}&autoplay={int(original['autoplay'])}")
- self.request(f"/set?theme={int(original['theme'])}")
+ if original["theme"] is not None:
+ self.request(f"/set?theme={int(original['theme'])}")
def open_display(base_url):