hapbeat-python-sdk 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

hapbeat/netif.py

@@ -0,0 +1,270 @@
+"""Local IPv4 subnet discovery — the input to subnet-directed broadcast.
+
+Why this exists
+---------------
+``255.255.255.255`` (limited broadcast) leaves a multi-homed host through the
+*single* interface with the lowest routing metric. Installing Hyper-V, WSL2 or
+Docker adds a virtual switch that is permanently "connected" — no Ethernet
+cable required — and Windows may well rank it above Wi-Fi. When that happens
+the packet never reaches the network the Hapbeat is on and the SDK discovers
+nothing at all. A subnet-directed address (``192.168.0.255``) is instead
+resolved through the directly-connected route for that subnet, so the metric
+never enters into it.
+
+Computing that address needs each interface's real netmask, and the standard
+library has no portable way to ask for one. So this module calls the platform
+API directly through :mod:`ctypes`:
+
+- **Windows** — ``GetAdaptersAddresses`` (iphlpapi), whose per-address
+  ``OnLinkPrefixLength`` is the prefix we want.
+- **Linux / macOS / BSD** — ``getifaddrs`` (libc), which hands back ``ifa_netmask``
+  alongside each address.
+
+Everything here is best-effort by design: any platform this cannot query
+returns an empty list, and the caller falls back to the limited broadcast it
+has always used. Struct layouts follow the `ifaddr <https://pypi.org/project/ifaddr/>`_
+package (MIT), which is the reference implementation for this on both platforms.
+
+The SDK has no runtime dependencies, which is why the layouts are restated here
+instead of taking that package as a dependency.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import logging
+import platform
+import socket
+from typing import List, Tuple
+
+logger = logging.getLogger("hapbeat")
+
+# (address, prefix length), e.g. ("192.168.0.205", 24)
+Subnet = Tuple[str, int]
+
+_IS_WINDOWS = platform.system() == "Windows"
+_IS_BSD = platform.system() == "Darwin" or "BSD" in platform.system()
+
+
+# ── sockaddr (BSD keeps a length byte where the others start the family) ──
+if _IS_BSD:
+
+    class _sockaddr(ctypes.Structure):
+        _fields_ = [
+            ("sa_len", ctypes.c_uint8),
+            ("sa_family", ctypes.c_uint8),
+            ("sa_data", ctypes.c_uint8 * 14),
+        ]
+
+    class _sockaddr_in(ctypes.Structure):
+        _fields_ = [
+            ("sin_len", ctypes.c_uint8),
+            ("sin_family", ctypes.c_uint8),
+            ("sin_port", ctypes.c_uint16),
+            ("sin_addr", ctypes.c_uint8 * 4),
+            ("sin_zero", ctypes.c_uint8 * 8),
+        ]
+
+else:
+
+    class _sockaddr(ctypes.Structure):  # type: ignore[no-redef]
+        _fields_ = [
+            ("sa_family", ctypes.c_uint16),
+            ("sa_data", ctypes.c_uint8 * 14),
+        ]
+
+    class _sockaddr_in(ctypes.Structure):  # type: ignore[no-redef]
+        _fields_ = [
+            ("sin_family", ctypes.c_uint16),
+            ("sin_port", ctypes.c_uint16),
+            ("sin_addr", ctypes.c_uint8 * 4),
+            ("sin_zero", ctypes.c_uint8 * 8),
+        ]
+
+
+def _ipv4_of(sockaddr_ptr) -> str:
+    """Dotted-quad for an ``AF_INET`` sockaddr, or "" for anything else."""
+    if not sockaddr_ptr or sockaddr_ptr[0].sa_family != socket.AF_INET:
+        return ""
+    sin = ctypes.cast(sockaddr_ptr, ctypes.POINTER(_sockaddr_in))
+    return ".".join(str(b) for b in sin[0].sin_addr)
+
+
+def _prefix_of_mask(mask: str) -> int:
+    """Prefix length for a dotted-quad mask. -1 if it is not contiguous.
+
+    A non-contiguous mask is not something a modern stack hands out, but
+    accepting one would produce a broadcast address that reaches the wrong
+    hosts, so it is rejected rather than guessed at.
+    """
+    try:
+        parts = [int(p) for p in mask.split(".")]
+    except ValueError:
+        return -1
+    if len(parts) != 4 or any(p < 0 or p > 255 for p in parts):
+        return -1
+    value = (parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]
+    if value == 0:
+        return -1
+    # Contiguous means the complement is all-ones in the low bits.
+    inverted = ~value & 0xFFFFFFFF
+    if inverted & (inverted + 1):
+        return -1
+    return 32 - inverted.bit_length()
+
+
+# ── Windows: GetAdaptersAddresses ────────────────────────────────────
+class _SOCKET_ADDRESS(ctypes.Structure):
+    _fields_ = [
+        ("lpSockaddr", ctypes.POINTER(_sockaddr)),
+        ("iSockaddrLength", ctypes.c_int),
+    ]
+
+
+class _IP_ADAPTER_UNICAST_ADDRESS(ctypes.Structure):
+    pass
+
+
+_IP_ADAPTER_UNICAST_ADDRESS._fields_ = [
+    ("Length", ctypes.c_ulong),
+    ("Flags", ctypes.c_uint32),
+    ("Next", ctypes.POINTER(_IP_ADAPTER_UNICAST_ADDRESS)),
+    ("Address", _SOCKET_ADDRESS),
+    ("PrefixOrigin", ctypes.c_uint),
+    ("SuffixOrigin", ctypes.c_uint),
+    ("DadState", ctypes.c_uint),
+    ("ValidLifetime", ctypes.c_ulong),
+    ("PreferredLifetime", ctypes.c_ulong),
+    ("LeaseLifetime", ctypes.c_ulong),
+    ("OnLinkPrefixLength", ctypes.c_uint8),
+]
+
+
+class _IP_ADAPTER_ADDRESSES(ctypes.Structure):
+    pass
+
+
+_IP_ADAPTER_ADDRESSES._fields_ = [
+    ("Length", ctypes.c_ulong),
+    ("IfIndex", ctypes.c_uint32),
+    ("Next", ctypes.POINTER(_IP_ADAPTER_ADDRESSES)),
+    ("AdapterName", ctypes.c_char_p),
+    ("FirstUnicastAddress", ctypes.POINTER(_IP_ADAPTER_UNICAST_ADDRESS)),
+    ("FirstAnycastAddress", ctypes.c_void_p),
+    ("FirstMulticastAddress", ctypes.c_void_p),
+    ("FirstDnsServerAddress", ctypes.c_void_p),
+    ("DnsSuffix", ctypes.c_wchar_p),
+    ("Description", ctypes.c_wchar_p),
+    ("FriendlyName", ctypes.c_wchar_p),
+]
+
+_ERROR_BUFFER_OVERFLOW = 111
+
+
+def _windows_subnets() -> List[Subnet]:
+    iphlpapi = ctypes.windll.Iphlpapi  # type: ignore[attr-defined]
+
+    size = ctypes.c_ulong(15 * 1024)
+    buffer = ctypes.create_string_buffer(size.value)
+    retval = _ERROR_BUFFER_OVERFLOW
+    # The documented protocol: on overflow the call writes the size it needs.
+    # Bounded so a pathological answer cannot spin here.
+    for _ in range(5):
+        buffer = ctypes.create_string_buffer(size.value)
+        retval = iphlpapi.GetAdaptersAddresses(
+            ctypes.c_ulong(socket.AF_INET),
+            ctypes.c_ulong(0),
+            None,
+            ctypes.byref(buffer),
+            ctypes.byref(size),
+        )
+        if retval != _ERROR_BUFFER_OVERFLOW:
+            break
+    if retval != 0:
+        raise OSError(f"GetAdaptersAddresses failed ({retval})")
+
+    out: List[Subnet] = []
+    adapter = _IP_ADAPTER_ADDRESSES.from_buffer(buffer)
+    while True:
+        # Adapters with no configured IPv4 address are simply absent from an
+        # AF_INET enumeration, so no operational-status filtering is needed
+        # here; 127/8 is dropped by the caller and duplicates are merged there.
+        address_ptr = adapter.FirstUnicastAddress
+        while address_ptr:
+            address = address_ptr[0]
+            ip = _ipv4_of(address.Address.lpSockaddr)
+            prefix = address.OnLinkPrefixLength
+            if ip and 0 < prefix <= 32:
+                out.append((ip, prefix))
+            address_ptr = address.Next
+        if not adapter.Next:
+            break
+        adapter = adapter.Next[0]
+    return out
+
+
+# ── POSIX: getifaddrs ────────────────────────────────────────────────
+class _ifaddrs(ctypes.Structure):
+    pass
+
+
+_ifaddrs._fields_ = [
+    ("ifa_next", ctypes.POINTER(_ifaddrs)),
+    ("ifa_name", ctypes.c_char_p),
+    ("ifa_flags", ctypes.c_uint),
+    ("ifa_addr", ctypes.POINTER(_sockaddr)),
+    ("ifa_netmask", ctypes.POINTER(_sockaddr)),
+]
+
+
+def _posix_subnets() -> List[Subnet]:
+    import ctypes.util
+
+    libc_name = ctypes.util.find_library("c")
+    if libc_name is None:
+        raise OSError("libc not found")
+    libc = ctypes.CDLL(libc_name, use_errno=True)
+
+    head = ctypes.POINTER(_ifaddrs)()
+    if libc.getifaddrs(ctypes.byref(head)) != 0:
+        errno = ctypes.get_errno()
+        raise OSError(errno, "getifaddrs failed")
+
+    out: List[Subnet] = []
+    try:
+        node = head
+        while node:
+            entry = node[0]
+            # getifaddrs also reports link-layer entries (AF_PACKET / AF_LINK)
+            # and IPv6; _ipv4_of returns "" for those.
+            ip = _ipv4_of(entry.ifa_addr)
+            if ip and entry.ifa_netmask:
+                # On some systems the netmask sockaddr carries family 0.
+                # It sits on an IPv4 address, so read it as one.
+                if entry.ifa_netmask[0].sa_family == 0:
+                    entry.ifa_netmask[0].sa_family = socket.AF_INET
+                mask = _ipv4_of(entry.ifa_netmask)
+                prefix = _prefix_of_mask(mask) if mask else -1
+                if prefix > 0:
+                    out.append((ip, prefix))
+            node = entry.ifa_next
+    finally:
+        libc.freeifaddrs(head)
+    return out
+
+
+def local_ipv4_subnets() -> List[Subnet]:
+    """Every local IPv4 address with its prefix length, loopback excluded.
+
+    Returns an empty list on any platform or failure this cannot handle —
+    callers treat that as "use the limited broadcast", which is the behaviour
+    that predates this module.
+    """
+    try:
+        found = _windows_subnets() if _IS_WINDOWS else _posix_subnets()
+    except Exception as exc:  # noqa: BLE001 — never let discovery setup fail a session
+        logger.debug("could not enumerate local subnets (%s); "
+                     "limited broadcast only", exc)
+        return []
+
+    return [(ip, prefix) for ip, prefix in found if not ip.startswith("127.")]

hapbeat/osc.py

@@ -4,7 +4,7 @@ Lets any OSC-capable tool (TouchOSC, Max/MSP, TouchDesigner, a DAW, vvvv, ...)
 drive Hapbeat without writing code, using the addresses defined in
 ``hapbeat-contracts/specs/message-format.md`` §6::
 
-    /hapbeat/play      event_id [target] [target_time_us] [gain]
+    /hapbeat/play      event_id [target] [target_time_us] [gain] [pan]
     /hapbeat/stop      event_id [target]
     /hapbeat/stop-all  [target]
     /hapbeat/ping
@@ -66,7 +66,9 @@ class OscBridge:
         target = str(args[1]) if len(args) >= 2 and args[1] != "" else None
         target_time = int(args[2]) if len(args) >= 3 else 0
         gain = float(args[3]) if len(args) >= 4 else None
-        self.hb.play(event_id, gain, target=target, target_time_us=target_time)
+        pan = float(args[4]) if len(args) >= 5 else 0.0
+        self.hb.play(event_id, gain, target=target, target_time_us=target_time,
+                     pan=pan)
 
     def _handle_stop(self, _address: str, *args) -> None:
         if not args:

hapbeat/protocol.py

@@ -21,6 +21,9 @@ from typing import Optional
 # ── Header constants ────────────────────────────────────────────────
 MAGIC = 0x4842  # ASCII "HB"
 VERSION = 0x01
+# STREAM_BEGIN/DATA/END to stream-session-v2 receivers carry header version 2
+# (contracts stream-session-v2.md); every other command stays version 1.
+STREAM_VERSION = 0x02
 HEADER_SIZE = 8
 MAX_PACKET_SIZE = 512          # command packets
 MAX_STREAM_PACKET_SIZE = 1472  # 1500 MTU - 20 IP - 8 UDP
@@ -43,19 +46,34 @@ CMD_STREAM_END = 0x32
 CMD_PONG = 0x11
 CMD_ERROR = 0xFF
 
+# ── Stream session v2 (contracts stream-session-v2.md) ──────────────
+STREAM_ENVELOPE_SIZE = 16  # device_boot_id(u64) lease_ticket(u32) generation(u32)
+STREAM_LEASE_TAIL_MARKER = b"HBS2"
+STREAM_LEASE_TAIL_SIZE = 32
+STREAM_LEASE_TAIL_VERSION = 1
+STREAM_LEASE_FLAG_VALID = 0x01
+STREAM_LEASE_FLAG_SUPERSEDED = 0x02
+
+# PONG ``lease_tail``: how the bytes after volume_wiper classify
+LEASE_TAIL_ABSENT = "absent"        # no HBS2 marker (pre-v2 firmware when matched)
+LEASE_TAIL_VALID = "valid"          # well-formed 32-byte HBS2 tail
+LEASE_TAIL_MALFORMED = "malformed"  # HBS2 marker, wrong length/version/reserved/flags
+
 # ── Audio formats (streaming) ───────────────────────────────────────
 AUDIO_FORMAT_PCM16 = 0
 AUDIO_FORMAT_IMA_ADPCM = 1
 
 
 # ── Header ──────────────────────────────────────────────────────────
-def build_header(command_type: int, seq: int, payload_length: int) -> bytes:
+def build_header(
+    command_type: int, seq: int, payload_length: int, version: int = VERSION
+) -> bytes:
     """Build the 8-byte common header (little-endian).
 
     Layout: magic(u16) version(u8) command_type(u8) seq(u16) payload_length(u16)
     """
     return struct.pack(
-        "<HBBHH", MAGIC, VERSION, command_type, seq & 0xFFFF, payload_length
+        "<HBBHH", MAGIC, version, command_type, seq & 0xFFFF, payload_length
     )
 
 
@@ -100,18 +118,27 @@ def build_play(
     target: str = "",
     target_time_us: int = 0,
     gain: float = 1.0,
+    pan: float = 0.0,
 ) -> bytes:
     """PLAY (0x01).
 
     Wire payload (see contracts/specs/device-addressing.md §5.1):
         event_id(null-term) + target(null-term) + target_time(i64) + gain(f32)
+        + pan(f32)
 
     ``target=""`` broadcasts to every device.
+
+    ``pan`` is the left/right balance (-1 left, 0 centre, +1 right) applied by
+    the device mixer as linear balance (contracts message-format.md §0x01,
+    DEC-055). It is the *trailing optional* field of the payload — receivers
+    that predate it treat its absence as 0.0 — but we always write it, and
+    clamp to [-1, 1] here so an out-of-range value can never reach the wire.
     """
+    pan = max(-1.0, min(1.0, float(pan)))
     payload = (
         event_id.encode("utf-8") + b"\x00"
         + target.encode("utf-8") + b"\x00"
-        + struct.pack("<qf", int(target_time_us), float(gain))
+        + struct.pack("<qff", int(target_time_us), float(gain), pan)
     )
     return build_packet(CMD_PLAY, seq, payload)
 
@@ -128,9 +155,21 @@ def build_stop_all(seq: int, *, target: str = "") -> bytes:
     return build_packet(CMD_STOP_ALL, seq, payload)
 
 
-def build_ping(seq: int, timestamp_us: int) -> bytes:
-    """PING (0x10). Payload: timestamp(i64, microseconds)."""
-    return build_packet(CMD_PING, seq, struct.pack("<q", int(timestamp_us)))
+def build_ping(
+    seq: int, timestamp_us: int, client_incarnation: Optional[int] = None
+) -> bytes:
+    """PING (0x10). Payload: timestamp(i64, microseconds).
+
+    With ``client_incarnation`` (nonzero u64) this is the 16-byte extended PING
+    of stream-session-v2.md: v2 receivers answer with an HBS2 lease tail,
+    pre-v2 firmware ignores the extra bytes and answers an ordinary PONG.
+    """
+    payload = struct.pack("<q", int(timestamp_us))
+    if client_incarnation is not None:
+        if not 0 < client_incarnation <= 0xFFFFFFFFFFFFFFFF:
+            raise ValueError("client_incarnation must be a nonzero uint64")
+        payload += struct.pack("<Q", client_incarnation)
+    return build_packet(CMD_PING, seq, payload)
 
 
 def build_connect_status(
@@ -157,6 +196,35 @@ def build_connect_status(
 
 
 # ── Streaming builders (clip-mode playback) ─────────────────────────
+#
+# v1 (``build_stream_*``) is for pre-v2 firmware only: header version 1, no
+# envelope, END without payload (contracts message-format.md "v1 stream").
+# v2 (``build_stream_*_v2``) starts every payload with the 16-byte
+# device_boot_id / lease_ticket / generation envelope, header version 2.
+def _stream_begin_body(
+    sample_rate: int, channels: int, fmt: int, total_samples: int,
+    gain: float, target: str,
+) -> bytes:
+    body = struct.pack(
+        "<HBBIf", sample_rate, channels, fmt, total_samples, float(gain)
+    )
+    if target:
+        body += target.encode("utf-8") + b"\x00"
+    return body
+
+
+def _build_stream_packet(
+    command_type: int, seq: int, payload: bytes, version: int
+) -> bytes:
+    """Stream packets use the larger MTU-safe size cap."""
+    total = HEADER_SIZE + len(payload)
+    if total > MAX_STREAM_PACKET_SIZE:
+        raise ValueError(
+            f"stream packet {total} exceeds MTU cap {MAX_STREAM_PACKET_SIZE}"
+        )
+    return build_header(command_type, seq, len(payload), version) + payload
+
+
 def build_stream_begin(
     seq: int,
     *,
@@ -167,35 +235,78 @@ def build_stream_begin(
     gain: float = 1.0,
     target: str = "",
 ) -> bytes:
-    """STREAM_BEGIN (0x30).
+    """STREAM_BEGIN (0x30), v1 (pre-v2 firmware).
 
     Default format is PCM16 — clip streaming sends uncompressed 16-bit PCM
     (ADPCM is reserved but not produced by the SDK).
     """
-    payload = struct.pack(
-        "<HBBIf", sample_rate, channels, fmt, total_samples, float(gain)
+    payload = _stream_begin_body(
+        sample_rate, channels, fmt, total_samples, gain, target
     )
-    if target:
-        payload += target.encode("utf-8") + b"\x00"
     return build_packet(CMD_STREAM_BEGIN, seq, payload)
 
 
 def build_stream_data(seq: int, offset: int, data: bytes) -> bytes:
-    """STREAM_DATA (0x31). Uses the larger MTU-safe size cap."""
+    """STREAM_DATA (0x31), v1. Uses the larger MTU-safe size cap."""
     payload = struct.pack("<I", offset) + data
-    total = HEADER_SIZE + len(payload)
-    if total > MAX_STREAM_PACKET_SIZE:
-        raise ValueError(
-            f"stream packet {total} exceeds MTU cap {MAX_STREAM_PACKET_SIZE}"
-        )
-    return build_header(CMD_STREAM_DATA, seq, len(payload)) + payload
+    return _build_stream_packet(CMD_STREAM_DATA, seq, payload, VERSION)
 
 
 def build_stream_end(seq: int) -> bytes:
-    """STREAM_END (0x32). No payload."""
+    """STREAM_END (0x32), v1. No payload."""
     return build_packet(CMD_STREAM_END, seq, b"")
 
 
+def build_stream_envelope(boot_id: int, lease_ticket: int, generation: int) -> bytes:
+    """The 16-byte v2 stream envelope. Every field must be nonzero."""
+    if not 0 < boot_id <= 0xFFFFFFFFFFFFFFFF:
+        raise ValueError("device_boot_id must be a nonzero uint64")
+    if not 0 < lease_ticket <= 0xFFFFFFFF:
+        raise ValueError("lease_ticket must be a nonzero uint32")
+    if not 0 < generation <= 0xFFFFFFFF:
+        raise ValueError("generation must be a nonzero uint32")
+    return struct.pack("<QII", boot_id, lease_ticket, generation)
+
+
+def build_stream_begin_v2(
+    seq: int,
+    boot_id: int,
+    lease_ticket: int,
+    generation: int,
+    *,
+    sample_rate: int = 16000,
+    channels: int = 1,
+    fmt: int = AUDIO_FORMAT_PCM16,
+    total_samples: int = 0,
+    gain: float = 1.0,
+    target: str = "",
+) -> bytes:
+    """STREAM_BEGIN (0x30), v2: envelope + the v1 BEGIN body."""
+    payload = build_stream_envelope(boot_id, lease_ticket, generation)
+    payload += _stream_begin_body(
+        sample_rate, channels, fmt, total_samples, gain, target
+    )
+    return _build_stream_packet(CMD_STREAM_BEGIN, seq, payload, STREAM_VERSION)
+
+
+def build_stream_data_v2(
+    seq: int, boot_id: int, lease_ticket: int, generation: int,
+    offset: int, data: bytes,
+) -> bytes:
+    """STREAM_DATA (0x31), v2: envelope + byte offset(u32) + audio."""
+    payload = build_stream_envelope(boot_id, lease_ticket, generation)
+    payload += struct.pack("<I", offset & 0xFFFFFFFF) + data
+    return _build_stream_packet(CMD_STREAM_DATA, seq, payload, STREAM_VERSION)
+
+
+def build_stream_end_v2(
+    seq: int, boot_id: int, lease_ticket: int, generation: int
+) -> bytes:
+    """STREAM_END (0x32), v2: exactly the envelope, no body."""
+    payload = build_stream_envelope(boot_id, lease_ticket, generation)
+    return _build_stream_packet(CMD_STREAM_END, seq, payload, STREAM_VERSION)
+
+
 # ── Device addressing ───────────────────────────────────────────────
 def address_matches(target: Optional[str], device_address: Optional[str]) -> bool:
     """Does ``device_address`` accept a packet aimed at ``target``?
@@ -249,12 +360,44 @@ def _read_cstr(buf: bytes) -> tuple[str, bytes]:
     return buf[:idx].decode("utf-8", errors="replace"), buf[idx + 1:]
 
 
+def _classify_lease_tail(tail: bytes, out: dict) -> None:
+    """Classify the bytes after volume_wiper (stream-session-v2.md "Legacy
+    receiver fallback"): anything that is not the full 4-byte HBS2 marker
+    (including a truncated prefix such as "HB") -> absent; the full marker
+    with a wrong length / version / reserved / flags -> malformed; otherwise
+    the valid 32-byte lease tail."""
+    if tail[:4] != STREAM_LEASE_TAIL_MARKER:
+        out["lease_tail"] = LEASE_TAIL_ABSENT
+        return
+    known_flags = STREAM_LEASE_FLAG_VALID | STREAM_LEASE_FLAG_SUPERSEDED
+    if (
+        len(tail) != STREAM_LEASE_TAIL_SIZE
+        or tail[4] != STREAM_LEASE_TAIL_VERSION
+        or tail[5] & ~known_flags
+        or struct.unpack_from("<H", tail, 6)[0] != 0
+    ):
+        out["lease_tail"] = LEASE_TAIL_MALFORMED
+        return
+    flags = tail[5]
+    incarnation, boot_id, ticket, high_water = struct.unpack_from("<QQII", tail, 8)
+    out["lease_tail"] = LEASE_TAIL_VALID
+    out["echoed_client_incarnation"] = incarnation
+    out["device_boot_id"] = boot_id
+    out["lease_ticket"] = ticket
+    out["high_water_ticket"] = high_water
+    out["lease_valid"] = bool(flags & STREAM_LEASE_FLAG_VALID) and boot_id != 0 and ticket != 0
+    out["lease_superseded"] = bool(flags & STREAM_LEASE_FLAG_SUPERSEDED)
+
+
 def parse_pong(data: bytes) -> Optional[dict]:
     """Parse a PONG (0x11).
 
     Bridge form is 16 bytes (timestamp, server_time). Devices append an
-    extended form (name / address / firmware_version, plus optional
-    trailing volume bytes). Returns ``None`` if not a valid PONG.
+    extended form (name / address / firmware_version, then volume_level and
+    volume_wiper). A v2 receiver's direct reply to an extended PING ends with
+    the 32-byte HBS2 stream lease tail; ``lease_tail`` says how the bytes
+    after volume_wiper classify (``LEASE_TAIL_*``). Returns ``None`` if not a
+    valid PONG.
     """
     hdr = parse_header(data)
     if hdr is None or hdr["command_type"] != CMD_PONG:
@@ -280,8 +423,7 @@ def parse_pong(data: bytes) -> Optional[dict]:
         out["volume_level"] = rest[0]
     if len(rest) >= 2:
         out["volume_wiper"] = rest[1]
-    if len(rest) >= 3:
-        out["volume_steps"] = rest[2]
+    _classify_lease_tail(rest[2:], out)
     return out