From 99d8c0af78b817849c0ffdcd4552ce2bb05770ee Mon Sep 17 00:00:00 2001
From: Franck Nijhof <git@frenck.dev>
Date: Sat, 3 Oct 2026 11:42:52 +0000
Subject: [PATCH] Document what testing on real devices turned up

A TIME accepts the screen_off screensaver mode, answering with success,
but only switches its other modes off. The screensaver is then left
without any mode at all. Only pick a mode the device reports.

Streaming is not available on an LM 37X8 TIME on firmware 2.3.9, which
reports API 2.3.0 and answers the stream endpoints with a 404. The
docstring claimed API 2.3.0 was enough. The stream example now checks
whether the device lists the stream endpoints first.
---
 README.md               |  5 +++--
 examples/stream.py      |  7 +++++++
 src/demetriek/device.py | 11 ++++++++---
 3 files changed, 18 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 1eb8a635..6a309f8e 100644
--- a/README.md
+++ b/README.md
@@ -27,8 +27,9 @@ Besides the local device API, it can:
 
 - Talk to the LaMetric cloud, to list the devices on your account, including
   their local IP address and API key.
-- Stream frames straight to the screen of the device, see
-  [`examples/stream.py`](examples/stream.py).
+- Stream frames straight to the screen of devices that support it, see
+  [`examples/stream.py`](examples/stream.py). An LM 37X8 TIME on firmware 2.x
+  does not.
 
 ## Installation
 
diff --git a/examples/stream.py b/examples/stream.py
index ae4f5a21..3e0fcc00 100644
--- a/examples/stream.py
+++ b/examples/stream.py
@@ -10,6 +10,13 @@
 async def main() -> None:
     """Show a green bar sweeping across the screen of your LaMetric device."""
     async with LaMetricDevice(HOST, api_key="DEVICE_API_KEY") as lametric:
+        # Not every device can stream, for example an LM 37X8 TIME on
+        # firmware 2.x. The device lists the stream endpoints when it can.
+        api = await lametric.api()
+        if "stream_url" not in api.endpoints:
+            print("This device does not support streaming")
+            return
+
         # The canvas size differs per device, so ask the device for it.
         status = await lametric.stream()
         if status.canvas.pixel is None:
diff --git a/src/demetriek/device.py b/src/demetriek/device.py
index ca7bcaf4..248f4ce4 100644
--- a/src/demetriek/device.py
+++ b/src/demetriek/device.py
@@ -303,7 +303,10 @@ async def display(  # noqa: PLR0913 # pylint: disable=too-many-arguments
             brightness: Brightness level to set.
             brightness_mode: Brightness mode to set.
             screensaver_enabled: Whether the screensaver should be enabled.
-            screensaver_mode: Screensaver mode to configure.
+            screensaver_mode: Screensaver mode to configure. Only pick a mode
+                the device reports in `screensaver.modes`. A TIME accepts
+                screen_off, but only switches its other modes off, leaving
+                the screensaver without any mode at all.
             screensaver_mode_enabled: Whether to enable the screensaver mode.
             screensaver_start_time: Time in GMT the screensaver starts,
                 for the time based mode.
@@ -712,8 +715,10 @@ async def notification_queue(self) -> list[Notification]:
     async def stream(self) -> Stream:
         """Get the stream state and canvas size of the device.
 
-        Streaming needs API 2.3.0 or newer, and is not available on every
-        device. `api()` lists the stream endpoints when the device has them.
+        Streaming is not available on every device. An LM 37X8 TIME on
+        firmware 2.3.9 (API 2.3.0) does not have it and answers with a 404,
+        an sa8 TIME on firmware 3.2.6 (API 2.4.0) does. `api()` lists the
+        stream endpoints when the device has them.
 
         Returns
         -------