python-aidot-cameras 1.0.0b3__tar.gz → 1.0.0b5__tar.gz

{python_aidot_cameras-1.0.0b3/python_aidot_cameras.egg-info → python_aidot_cameras-1.0.0b5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-aidot-cameras
-Version: 1.0.0b3
+Version: 1.0.0b5
 Summary: Control AiDot/Leedarson WiFi lights and cameras (WebRTC streaming, two-way audio, PTZ, controls)
 Author-email: cbrightly <chris.brightly@gmail.com>
 License-Expression: MIT
@@ -66,6 +66,33 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Known characteristics
+
+Two behaviours that are measured, understood as far as the evidence allows, and
+not going to change in this release. Neither is a fault to report.
+
+**Recorded video is retrievable only from cloud storage.** Whether a camera
+records to the cloud or to its own SD card is per-camera, not per-model, and the
+device reports it as `IsSupportPlayback`. This library retrieves cloud
+recordings (`async_get_cloud_recordings`, `async_open_cloud_playback`) and has
+no SD-card equivalent, so a camera storing to a card records normally and
+nothing here can play it back. On the reference fleet that is four of seven
+cameras. The vendor's own commands for it are identified but their responses
+have never been decoded; see `docs/ROAD-TO-1.0.md` item 6.
+
+**The A001064 (PTZ) streams at roughly 2.2 Mbps, about 24% above the vendor
+app.** Measured from a capture of the app on the same camera: it takes about
+1796 Kbps on HD and about 866 Kbps on SD. An earlier version of this note
+repeated a figure of 225-500 Kbps for the app - that was never measured here,
+and the capture contradicts it at both quality settings.
+
+So the practical difference is a quarter more bandwidth at equivalent quality,
+plus a roughly 2:1 saving that the app's SD control achieves and this library's
+does not. The command sent here is byte-for-byte the app's, in-band and
+mid-session on the same transport, and it does not change the rate; the app's
+does. Streaming is correct either way and the cost is bandwidth, which matters
+on a metered or congested link.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol

{python_aidot_cameras-1.0.0b3 → python_aidot_cameras-1.0.0b5}/README.md

@@ -35,6 +35,33 @@ Other battery models (A001108, A001360) are recognized in code with the same
 battery handling. See [`docs/CAMERAS.md`](docs/CAMERAS.md#supported-cameras) for
 the authoritative table and per-model notes.
 
+## Known characteristics
+
+Two behaviours that are measured, understood as far as the evidence allows, and
+not going to change in this release. Neither is a fault to report.
+
+**Recorded video is retrievable only from cloud storage.** Whether a camera
+records to the cloud or to its own SD card is per-camera, not per-model, and the
+device reports it as `IsSupportPlayback`. This library retrieves cloud
+recordings (`async_get_cloud_recordings`, `async_open_cloud_playback`) and has
+no SD-card equivalent, so a camera storing to a card records normally and
+nothing here can play it back. On the reference fleet that is four of seven
+cameras. The vendor's own commands for it are identified but their responses
+have never been decoded; see `docs/ROAD-TO-1.0.md` item 6.
+
+**The A001064 (PTZ) streams at roughly 2.2 Mbps, about 24% above the vendor
+app.** Measured from a capture of the app on the same camera: it takes about
+1796 Kbps on HD and about 866 Kbps on SD. An earlier version of this note
+repeated a figure of 225-500 Kbps for the app - that was never measured here,
+and the capture contradicts it at both quality settings.
+
+So the practical difference is a quarter more bandwidth at equivalent quality,
+plus a roughly 2:1 saving that the app's SD control achieves and this library's
+does not. The command sent here is byte-for-byte the app's, in-band and
+mid-session on the same transport, and it does not change the rate; the app's
+does. Streaming is correct either way and the cost is bandwidth, which matters
+on a metered or congested link.
+
 ## Local (LAN) control and account ownership
 
 Local control over the devices' TCP:10000 channel - both the light/plug protocol

{python_aidot_cameras-1.0.0b3 → python_aidot_cameras-1.0.0b5}/aidot_cameras/camera/client.py

@@ -46,6 +46,7 @@ from .playback import (  # re-exported (split into playback.py)
 from .webrtc import WebRTCSession  # re-exported (split into webrtc.py)
 from .sdes import SdesSession  # noqa: F401 - re-exported (split into sdes.py); used by sdes_open mixin
 from .controls import _CameraControlsMixin
+from .sd_listing import _CameraSdMixin
 from .webrtc_open import _WebRTCOpenMixin
 from .sdes_open import _SdesOpenMixin
 from .protocol import (  # noqa: F401 - used here and/or by the webrtc_open mixin; kept re-exported for back-compat
@@ -859,7 +860,7 @@ def _ack_matches_seq(msg, seq):
     return code if isinstance(code, int) else False
 
 
-class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
+class CameraMixin(_CameraControlsMixin, _CameraSdMixin, _WebRTCOpenMixin, _SdesOpenMixin):
     """All camera/streaming methods, mixed into DeviceClient via inheritance."""
 
     # Devices without an aesKey never get this set by the core constructor;
@@ -2391,6 +2392,88 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         )
         return None
 
+    async def async_get_recent_recordings(self, total: int = 10) -> "List[dict]":
+        """The camera's most recent cloud event recordings.
+
+        A second listing API, and the one the vendor app actually uses on its
+        event page. Captured 2026-04-05:
+
+            POST /api/ipc/playback/getRecentEventRecordingList
+                 {"deviceIds": [...], "total": 3}
+
+        **Both listings work; the zeros were the account** (measured
+        2026-08-11). Every fleet run had reported zero events from every camera
+        through this call AND through `async_get_cloud_recordings`, which read
+        as two broken listings. On the OWNER account, on the same fleet, ninety
+        minutes after a run that reported zero: this call returns the full count
+        it asks for on six of seven cameras, and the range query returns a full
+        first page against server totals of 121-1517 over thirty days. The
+        seventh camera has no events by any method.
+
+        The fleet runs use a shared-home member. The same runs report no cloud
+        thumbnail either, and the owner/member thumbnail split was measured
+        separately on 2026-08-09 - so an account seeing neither is behaving as
+        the member, not meeting a defect. Read a zero from this method as a
+        question about the account before reading it as a fault.
+
+        Two shape differences from every other call in this class, and both
+        would break the usual handling:
+
+        * the response is a BARE JSON ARRAY, not the ``{"code": ..., "data":
+          ...}`` envelope, so there is no code to check and no ``data`` to
+          unwrap;
+        * there is no pagination - ``total`` is "how many do you want", not a
+          page size.
+
+        Each item carries ``eventUuid``, ``eventTime`` (epoch ms), ``deviceId``,
+        ``deviceName``, ``eventCodeList``, ``eventDescList`` and ``picUrl``.
+        Filtered to THIS camera, because the app asks for a whole house at once
+        and the reply is not per-device.
+        """
+        import aiohttp
+
+        body = {"deviceIds": [self.device_id], "total": max(1, int(total))}
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self._aidot_v32_base}/playback/getRecentEventRecordingList",
+                    json=body,
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            data = await _fetch()
+            # The auth check reads a dict; a list is already a success here.
+            if isinstance(data, dict):
+                if self._is_auth_error(data) and await self._async_refresh_auth_token():
+                    data = await _fetch()
+            if isinstance(data, dict):
+                # An envelope means an error, since success is a bare array.
+                _LOGGER.warning(
+                    "getRecentEventRecordingList code=%s msg=%s for %s",
+                    data.get("code"), data.get("desc") or data.get("msg"),
+                    self.device_id,
+                )
+                return []
+            if not isinstance(data, list):
+                return []
+            mine = [e for e in data
+                    if isinstance(e, dict)
+                    and e.get("deviceId") in (None, self.device_id)]
+            _LOGGER.info(
+                "getRecentEventRecordingList for %s: %d of %d event(s)",
+                self.device_id, len(mine), len(data),
+            )
+            return mine
+        except Exception as exc:
+            _LOGGER.warning(
+                "getRecentEventRecordingList failed for %s: %s",
+                self.device_id, exc)
+            return []
+
     async def async_get_cloud_recordings(
         self,
         start_ts: int,
@@ -2403,6 +2486,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
 
         start_ts / end_ts: Unix timestamps in milliseconds.
         page: 1-indexed page number (the server uses 1-based pagination).
+        The server caps a page at 10 items whatever ``page_size`` says -
+        measured 2026-08-11 across seven cameras, and the vendor's own client
+        hard-overwrites the field to 10 (5 for a multi-device request), so it
+        is the server's rule rather than a quirk of one account. A caller that
+        asks for 30 gets 10 and no indication that it was truncated, which is
+        how the Home Assistant browser came to show 10 events out of 1517.
+        Page; do not raise ``page_size``. ``data.total`` in the reply is the
+        true count for the window, and is correct even on a one-item page.
         Returns list of dicts from the server (each has eventUuid, eventDesc, picUrl, etc.).
 
         Uses /api/ipc/playback/eventRecordingList (confirmed from EventListRepos.java).
@@ -2456,6 +2547,106 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
             )
             return []
 
+    async def async_count_cloud_recordings(
+        self, start_ts: int, end_ts: int
+    ) -> Optional[int]:
+        """How many cloud events a window holds, in one request.
+
+        The listing endpoint reports the window's true ``total`` alongside
+        whatever page it serves, and that total is correct even on a one-item
+        page - measured 2026-08-11 across seven cameras. So a count costs one
+        request, where counting by paging costs one per ten events: a day
+        holding 1517 events is 152 requests, and a seven-day view that counts
+        by paging fires hundreds every time it is opened.
+
+        Returns None when the call fails. A caller must not read that as zero -
+        "the server did not answer" and "the window is empty" lead to opposite
+        conclusions in a UI, and collapsing them is a defect this project has
+        had to fix before.
+        """
+        import aiohttp
+
+        _body = {
+            "deviceIds": [self.device_id],
+            "pageNum":   1,
+            "pageSize":  1,
+            "recordSta": start_ts,
+            "recordEnd": end_ts,
+        }
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"{self._aidot_v32_base}/playback/eventRecordingList",
+                    json=_body,
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=30),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            body = await _fetch()
+            if self._is_auth_error(body) and await self._async_refresh_auth_token():
+                body = await _fetch()
+            if not isinstance(body, dict) or body.get("code") != 200:
+                _LOGGER.debug(
+                    "eventRecordingList count for %s: %s", self.device_id, body)
+                return None
+            total = (body.get("data") or {}).get("total")
+            return int(total) if isinstance(total, int) else None
+        except Exception as exc:
+            _LOGGER.debug(
+                "eventRecordingList count failed for %s: %s", self.device_id, exc)
+            return None
+
+    async def async_get_cloud_plan(self) -> Optional[dict]:
+        """The camera's cloud recording subscription, or None.
+
+        Answers the question an empty event list cannot: whether there are no
+        events, or no longer a plan under which events would be kept. Measured
+        2026-08-11 on seven cameras - an active plan reads
+
+            {"packageName": "AI Protection ", "packageType": 1,
+             "subscribeStatus": 1, "startTime": <ms>, "endTime": <ms>,
+             "expiredDays": 15, "videoLength": 60}
+
+        Times are epoch milliseconds. ``videoLength`` is the clip length in
+        seconds.
+
+        Returns None on any failure rather than an empty dict: the caller's
+        question is "is there a plan", and {} answers it wrong.
+
+        Source: the vendor app's own JS bundle -
+        GET /api/ipc/recordPlanController/getPackageInfoByDevId?deviceId=
+        """
+        import aiohttp
+
+        async def _fetch():
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    f"{self._aidot_v32_base}/recordPlanController"
+                    "/getPackageInfoByDevId",
+                    params={"deviceId": self.device_id},
+                    headers=self._aidot_headers(),
+                    timeout=aiohttp.ClientTimeout(total=15),
+                ) as resp:
+                    return await resp.json(content_type=None)
+
+        try:
+            body = await _fetch()
+            if self._is_auth_error(body) and await self._async_refresh_auth_token():
+                body = await _fetch()
+            if not isinstance(body, dict) or body.get("code") != 200:
+                _LOGGER.debug(
+                    "getPackageInfoByDevId for %s: %s", self.device_id, body)
+                return None
+            data = body.get("data")
+            return data if isinstance(data, dict) and data else None
+        except Exception as exc:
+            _LOGGER.debug(
+                "getPackageInfoByDevId failed for %s: %s", self.device_id, exc)
+            return None
+
     async def async_get_event_video_media(
         self, event_uuid: str
     ) -> Optional[tuple[str, str]]:
@@ -2465,6 +2656,14 @@ class CameraMixin(_CameraControlsMixin, _WebRTCOpenMixin, _SdesOpenMixin):
         most browsers handle direct MP4 more reliably than HLS with signed CDN
         segments.  Falls back to whatever is available.
 
+        **That preference has never once been exercised.** Measured 2026-08-11
+        on the owner account, three cameras across three model families
+        (A001064, A001513, A000088): every reply carried exactly ONE entry, and
+        it was type 2. So playback here is HLS in practice, and anything built
+        on it should be designed for HLS rather than for the MP4 this docstring
+        would lead a reader to expect. The branch is kept because it costs
+        nothing and the field exists in the app's own decoder.
+
         From CloudPlaybackFragment.java / EventListRepos.java:
           POST /api/ipc/playback/getEventVideoUrl
           body: {deviceId, eventList: [{eventUuid}]}

python_aidot_cameras-1.0.0b5/aidot_cameras/camera/sd_events.py

@@ -0,0 +1,305 @@
+"""Build the camera's recording-list requests, and decode its replies.
+
+Both halves live here because they are one wire format, and because the
+selector lesson below belongs next to the code that sends it: the requests used
+to exist only in ``scripts/sd_event_probe.py``, which the package cannot import,
+so every caller either duplicated them or could not ask at all.
+
+The decoder was written from the vendor client's own decoder rather than from a
+capture. What is CONFIRMED from ``KVSWebRTCChannel``'s 0x319 handler:
+
+  * the reply is matched by the SEQUENCE NUMBER of the request, not by the
+    command alone - the handler's first act is ``if getListSeq != seq: return``;
+  * a four-byte little-endian value is assembled and named ``listEventTotalTime``
+    (its name says time, not count, and this module does not pretend otherwise);
+  * a single byte is read as ``listEventEndFlag`` - the reply is PAGED, and a
+    caller that stops at the first packet gets a truncated list;
+  * a single byte is read as ``listEventCount`` - how many records this packet
+    carries;
+  * records are **twelve bytes each**, copied out with an explicit
+    ``arraycopy(..., 12)``, and each begins with a two-byte year read via
+    ``byteToShort`` - an ``STimeDay``.
+
+**The header is now measured, not inferred (2026-08-11, run 31497241870).** The
+first version of this module used the published TUTK layout - two STimeDays then
+the counters, 24 bytes - and refused to decode the real replies because they
+were shorter than that. Refusing was correct, and it is how the true layout came
+back readable instead of being forced into the wrong one.
+
+Two live replies, and a 12-byte header fits both exactly:
+
+    HASLISTEVENT_RESP  00000000 01000000 0001a800  + 168 bytes
+    LISTEVENT_RESP     00000000 01000000 00010000  + 0 bytes
+
+    channel  uint32 LE   total  uint32 LE   index  end_flag  count  reserved
+
+`count` equals the body length in both - 168 and 0. And 168 is exactly the
+7-day range that was requested, one byte per hour, which is what HASLISTEVENT
+means: a per-hour occupancy map rather than a list. LISTEVENT carries 12-byte
+records in the same body.
+"""
+import struct
+import time
+from typing import List, NamedTuple, Optional
+
+#: One record. The size is confirmed from the vendor's own arraycopy.
+EVENT_RECORD_LEN = 12
+
+#: Measured from two live replies, not taken from the published struct - the
+#: published one is 24 bytes and neither reply is that long.
+_HEADER_LEN = 12
+
+
+class SdEvent(NamedTuple):
+    """One recording the camera says it holds."""
+
+    #: UTC, from the record's STimeDay.
+    year: int
+    month: int
+    day: int
+    hour: int
+    minute: int
+    second: int
+    channel: int
+    event: int
+    status: int
+
+    def isoformat(self) -> str:
+        return (f"{self.year:04d}-{self.month:02d}-{self.day:02d}"
+                f"T{self.hour:02d}:{self.minute:02d}:{self.second:02d}Z")
+
+
+class SdEventPage(NamedTuple):
+    """One packet of the paged reply.
+
+    ``end_flag`` is why this is a page and not a list: the camera answers a
+    range in several packets and a caller that reads only the first silently
+    truncates the recording list. Nothing here hides that.
+    """
+
+    events: List[SdEvent]
+    channel: int
+    total: int
+    #: Named page_index / record_count, not index / count: a NamedTuple field
+    #: called `index` or `count` shadows tuple.index() and tuple.count(), so
+    #: `page.count` would stop being callable and read as a number instead.
+    page_index: int
+    end_flag: int
+    record_count: int
+    #: True when the payload length matches the count the header declared.
+    consistent: bool
+    #: Bytes left over after the declared records - non-zero means the layout
+    #: read here is wrong, and says so rather than dropping them.
+    trailing: int
+
+
+class SdRecordingList(NamedTuple):
+    """What one camera says its card holds over one window.
+
+    ``records`` is the list and is always the primary answer. ``hours`` is the
+    HASLISTEVENT occupancy map when the camera gave one - optional, never
+    load-bearing. Measured 2026-08-11: the camera that returned four real
+    records returned an ALL-ZERO map for the same window, so a consumer that
+    trusted the map over the records would have shown an empty card.
+
+    ``start_ts``/``end_ts`` are the window that was asked for. The map is one
+    byte per hour counting from ``start_ts``, so without them a byte cannot be
+    placed on a clock.
+    """
+
+    records: List[SdEvent]
+    hours: Optional[bytes]
+    #: True when the camera replied to at least one of the two requests.
+    #:
+    #: Without this, a camera that says NOTHING and a camera that says "my card
+    #: is empty" both arrive as an empty list, and a browser has no way to tell
+    #: "we asked and got silence" from "there is nothing there" - so it prints
+    #: the second when the first is true. That collapse is the exact failure
+    #: this subsystem exists to prevent, and it is worth a field rather than a
+    #: convention: an empty ``records`` is only a statement about the card when
+    #: ``answered`` is True.
+    answered: bool
+    #: Whether the list that came back is the whole list. False when the
+    #: reply's end flag never arrived, and False when a reply arrived that could
+    #: not be decoded - in both cases there may be more than is shown.
+    #:
+    #: Only meaningful when ``answered`` is True. Silence carries no end flag,
+    #: so it says nothing about completeness either way.
+    complete: bool
+    start_ts: float
+    end_ts: float
+
+
+#: Reply command ids, so a caller that knows which question it asked can say so.
+LISTEVENT_RESP_CMD = 0x319
+HASLISTEVENT_RESP_CMD = 0x4B6
+
+#: Request command ids, from AVIOCTRLDEFs in the vendor's own client.
+HASLISTEVENT_REQ_CMD = 0x4B5
+LISTEVENT_REQ_CMD = 0x318
+
+#: The event selector the vendor's app sends, read off
+#: KVSWebRTCChannel.getSDRecordList: `const/16 v1, 0x12`.
+#:
+#: It is NOT the default here, because on a camera with a card it returns
+#: nothing. Measured 2026-08-11: the same session, the same window, 0x12
+#: answered an EMPTY page while 0 answered with four real records, the first
+#: stamped 2026-08-11T20:41:42Z. The earlier note claiming the opposite was
+#: measured on three cameras with no card, where every selector answered empty
+#: and the comparison was between two empty answers.
+SD_EVENT_APP = 0x12
+
+#: The selector that returns records. The default, so a caller that does not
+#: know about the above cannot accidentally ask the question that gets silence.
+SD_EVENT_ANY = 0
+
+
+def stimeday(when: float) -> bytes:
+    """The vendor's 8-byte STimeDay, from ``AVIOCTRLDEFs$STimeDay``.
+
+    ``unsigned short year`` then six single bytes - month, day, wday, hour,
+    minute, second. UTC, because the field is named ``startutctime``.
+    """
+    t = time.gmtime(when)
+    return struct.pack(
+        "<HBBBBBB",
+        t.tm_year,
+        t.tm_mon,
+        t.tm_mday,
+        (t.tm_wday + 1) % 7,     # tm_wday is Mon=0; the vendor's wday is Sun=0
+        t.tm_hour,
+        t.tm_min,
+        t.tm_sec,
+    )
+
+
+def haslistevent_payload(start: float, end: float, channel: int = 0,
+                         event: int = SD_EVENT_ANY) -> bytes:
+    """22 bytes: channel, start, end, and a two-byte selector tail.
+
+    The length is not a guess - ``parseConent`` allocates ``const/16 v1, 0x16``,
+    which is 22, and copies the channel at offset 0 and the first STimeDay at
+    offset 4.
+    """
+    return (struct.pack("<I", channel)
+            + stimeday(start) + stimeday(end)
+            + struct.pack("<H", event & 0xFFFF))
+
+
+def listevent_payload(start: float, end: float, channel: int = 0,
+                      event: int = SD_EVENT_ANY, status: int = 0) -> bytes:
+    """24 bytes, not 22 - and the difference is the whole point.
+
+    ``SMsgAVIoctrlListEventReq`` has three ``parseConent`` overloads. The one
+    whose field list this was first written from is not the one the WebRTC path
+    uses: ``KVSWebRTCChannel.getSDRecordList`` calls the epoch-long overload,
+    which allocates ``const/16 v4, 0x18`` - 24 bytes - where the other
+    allocates 22. Four bytes of channel, two eight-byte STimeDays, the event and
+    status selectors, then two bytes of tail.
+    """
+    return (struct.pack("<I", channel)
+            + stimeday(start) + stimeday(end)
+            + bytes((event & 0xFF, status & 0xFF))
+            + b"\x00\x00")
+
+
+def _consistent(count: int, body_len: int, command: Optional[int]) -> bool:
+    """Does the declared entry count match the body, for THIS reply's entry size?
+
+    Records are 12 bytes each; occupancy-map hours are one byte each. When the
+    command is known the right rule is used. When it is not, either reading is
+    accepted - reporting False for a well-formed page just because the decoder
+    was not told what it was reading would be the check lying about the data.
+    """
+    if command == HASLISTEVENT_RESP_CMD:
+        return count == body_len
+    if command == LISTEVENT_RESP_CMD:
+        return count * EVENT_RECORD_LEN == body_len
+    return count == body_len or count * EVENT_RECORD_LEN == body_len
+
+
+def _stimeday(buf: bytes, off: int) -> tuple:
+    year, month, day, _wday, hour, minute, second = struct.unpack_from(
+        "<HBBBBBB", buf, off)
+    return year, month, day, hour, minute, second
+
+
+def decode_event_record(buf: bytes, off: int = 0) -> SdEvent:
+    """One 12-byte record: an STimeDay then channel, event, status, reserved."""
+    year, month, day, hour, minute, second = _stimeday(buf, off)
+    channel, event, status = struct.unpack_from("<BBB", buf, off + 8)
+    return SdEvent(year, month, day, hour, minute, second,
+                   channel, event, status)
+
+
+def decode_list_event_response(payload: bytes, *, command: Optional[int] = None) -> Optional[SdEventPage]:
+    """Decode a 0x319 payload, or None if it cannot be one.
+
+    None rather than an exception or a half-filled result: this runs against a
+    reply nobody has seen yet, and "this does not fit" is the answer that keeps
+    the next person honest.
+    """
+    # A HASLISTEVENT body is a per-hour occupancy map, not records. Reading it
+    # as records is not a near miss: the real 168-byte map is exactly fourteen
+    # 12-byte records, so the decode SUCCEEDS and invents fourteen recordings
+    # dated 0000-00-00. Measured 2026-08-11, when a formatted-but-empty card's
+    # 24-byte map read as "records: 2". A caller that knows which reply it has
+    # gets nothing rather than fiction; a caller that passes no command still
+    # gets the old best-effort behaviour, because that is what the existing
+    # tests and probe runs read.
+    if command == HASLISTEVENT_RESP_CMD:
+        return None
+    if payload is None or len(payload) < _HEADER_LEN:
+        return None
+    channel, total = struct.unpack_from("<II", payload, 0)
+    index, end_flag, count, _reserved = struct.unpack_from("<BBBB", payload, 8)
+    body = payload[_HEADER_LEN:]
+    usable = len(body) // EVENT_RECORD_LEN
+    # `count` is a BYTE count on HASLISTEVENT (one byte per hour) and a RECORD
+    # count on LISTEVENT. Only the record reading is meaningful here, so the
+    # number of records decoded is bounded by what the body can actually hold
+    # rather than by what the header claims.
+    take = usable
+    events = [decode_event_record(body, i * EVENT_RECORD_LEN)
+              for i in range(take)]
+    return SdEventPage(
+        events=events,
+        channel=channel,
+        total=total,
+        page_index=index,
+        end_flag=end_flag,
+        record_count=count,
+        # `count` counts ENTRIES in the body, and an entry is not always a
+        # byte. Measured 2026-08-11 against the first live replies carrying real
+        # data: a LISTEVENT_RESP with four records is 12 header + 48 body and
+        # declares count=4, while a HASLISTEVENT_RESP occupancy map declares
+        # count=168 for 168 bytes because there an entry IS one hour-byte.
+        #
+        # So the entry size depends on WHICH reply this is, and the payload
+        # alone cannot always say - a 24-byte body with count=24 is a valid
+        # 24-hour map, and a 24-byte body with count=2 is a valid two-record
+        # page. Pass `command` when it is known. Without it, accept either
+        # reading rather than calling a good page inconsistent, and say in
+        # `consistent` only what can honestly be said.
+        consistent=_consistent(count, len(body), command),
+        trailing=len(body) - usable * EVENT_RECORD_LEN,
+    )
+
+
+def decode_hour_map(payload: Optional[bytes], *,
+                    command: Optional[int] = None) -> Optional[bytes]:
+    """The per-hour occupancy bytes from a HASLISTEVENT reply, or None.
+
+    One byte per hour of the window that was requested, starting at the request
+    start: 168 bytes for seven days, 24 for one. A non-zero byte means the card
+    holds something recorded in that hour. It says nothing about how many
+    recordings, so nothing here counts them.
+
+    None means "this is not a map", which is a different answer from an empty
+    map and is why the return is not simply ``b""``.
+    """
+    if command == LISTEVENT_RESP_CMD:
+        return None
+    if payload is None or len(payload) <= _HEADER_LEN:
+        return None
+    return bytes(payload[_HEADER_LEN:])