openble-muse 0.1.0__py3-none-any.whl

openble/muse/__init__.py

@@ -0,0 +1,10 @@
+"""Interaxon Muse headband BLE protocol, read from the Muse app and public work.
+
+``uuids`` names the GATT characteristics, ``models`` maps a serial number to
+a model and its characteristics, ``identify`` matches advertisements,
+``commands`` frames the ASCII commands and ``replies`` reassembles and reads
+the JSON answers. The data layouts are ``packets`` (per-sensor, ``pv`` 1-2),
+``universal`` (``pv`` 3) and ``ble4`` (``pv`` >= 4). ``link`` runs the
+start-up sequence over any transport. Nothing here imports a Bluetooth stack.
+See docs/muse-ble-protocol.md.
+"""

openble/muse/ble4.py

@@ -0,0 +1,159 @@
+"""The BLE4 stream (protocol version 4 and up): current Muse S Athena firmware.
+
+Read from Ble4DataHandler::handle, parse_subpackets and ParsedPacket::convert;
+the tags and payload sizes match amused, OpenMuse and muse-rs.
+
+    frame:      len | counter u16 LE | device clock u48 LE | sub-packets…
+    sub-packet: tag | seq u8 | time offset s24 LE | payload
+
+Frames arrive on ``UNIVERSAL`` and ``MUSE_DEBUG``. The app requires one frame
+per notification; OpenMuse walks several by their length bytes, so
+``parse_notification`` does both. Values are packed least-significant bit
+first, and rows are time steps (sample-major), as amused, OpenMuse and
+muse-rs decode them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from openble.muse.readings import DPS_PER_BIT, G_PER_BIT, Reading, eeg14_uv
+
+HEADER = 9
+EEG4, EEG8, DRL_REF, OPTICS4, OPTICS8, OPTICS16, IMU, BATTERY = range(1, 9)
+RATES_HZ = {1: 256, 2: 128, 3: 64, 4: 52, 5: 32, 6: 16, 7: 10, 8: 1, 9: 0.1}
+PAYLOAD = {1: 28, 2: 28, 3: 24, 4: 30, 5: 40, 6: 40, 7: 36, 8: 20}
+BATTERY_TO_END = 0x88  # newer firmware: 188-230 bytes to the end of the frame
+
+# Channel names are public (muse-rs); the app does not name them.
+EEG_CHANNELS = ("TP9", "AF7", "AF8", "TP10", "FPZ", "AUX_RIGHT", "AUX_LEFT", "AUX")
+IMU_CHANNELS = ("accel_x", "accel_y", "accel_z", "gyro_x", "gyro_y", "gyro_z")
+OPTICS_CHANNELS = {OPTICS4: 4, OPTICS8: 8, OPTICS16: 16}
+
+
+@dataclass(frozen=True)
+class SubPacket:
+    tag: int
+    kind: int  # low nibble
+    rate_code: int  # high nibble
+    sequence: int  # per type; the app skips duplicates and logs gaps
+    offset: int  # s24 LE; the app multiplies it by 100
+    payload: bytes
+
+
+@dataclass(frozen=True)
+class Frame:
+    counter: int  # u16 LE; the app reorders notifications by it
+    clock: int  # u48 LE; muse-rs reads 256 kHz ticks
+    subpackets: tuple[SubPacket, ...]
+    unparsed: bytes  # from the first unknown or truncated sub-packet on
+
+
+def parse_frame(data: bytes) -> Frame:
+    """Split one frame. Byte 0 must equal its length."""
+    data = bytes(data)
+    if len(data) < HEADER or data[0] != len(data):
+        raise ValueError(f"BLE4 frame length mismatch: {data.hex(' ')}")
+    subpackets: list[SubPacket] = []
+    i = HEADER
+    while i + 5 <= len(data):
+        tag = data[i]
+        kind = tag & 0x0F
+        size = len(data) - i - 5 if tag == BATTERY_TO_END else PAYLOAD.get(kind)
+        if size is None or i + 5 + size > len(data):
+            break
+        subpackets.append(
+            SubPacket(
+                tag=tag,
+                kind=kind,
+                rate_code=tag >> 4,
+                sequence=data[i + 1],
+                offset=int.from_bytes(data[i + 2 : i + 5], "little", signed=True),
+                payload=data[i + 5 : i + 5 + size],
+            )
+        )
+        i += 5 + size
+    return Frame(
+        counter=int.from_bytes(data[1:3], "little"),
+        clock=int.from_bytes(data[3:9], "little"),
+        subpackets=tuple(subpackets),
+        unparsed=data[i:],
+    )
+
+
+def parse_notification(data: bytes) -> list[Frame]:
+    """Every frame in a notification, walked by their length bytes."""
+    data = bytes(data)
+    frames = []
+    i = 0
+    while i < len(data):
+        length = data[i]
+        if length < HEADER or i + length > len(data):
+            raise ValueError(
+                f"BLE4 frame at {i} claims {length} bytes: {data.hex(' ')}"
+            )
+        frames.append(parse_frame(data[i : i + length]))
+        i += length
+    return frames
+
+
+def unpack_lsb_first(payload: bytes, bits: int) -> list[int]:
+    """Unsigned ``bits``-wide fields, least-significant bit first."""
+    word = int.from_bytes(payload, "little")
+    mask = (1 << bits) - 1
+    return [(word >> (bits * i)) & mask for i in range(len(payload) * 8 // bits)]
+
+
+def reading(sub: SubPacket, eeg_offset: int = 0) -> Reading:
+    """Convert a sub-packet. EEG is in microvolts, optics stay raw.
+
+    ``eeg_offset=EEG14_OFFSET_MUSE_RS`` centres EEG the way muse-rs does.
+    """
+    rate = RATES_HZ.get(sub.rate_code)
+    if sub.kind in (EEG4, EEG8):
+        width = 4 if sub.kind == EEG4 else 8
+        values = [eeg14_uv(v, eeg_offset) for v in unpack_lsb_first(sub.payload, 14)]
+        return Reading(
+            "eeg", EEG_CHANNELS[:width], _rows(values, width), sub.sequence, rate
+        )
+    if sub.kind in OPTICS_CHANNELS:
+        width = OPTICS_CHANNELS[sub.kind]
+        values = [float(v) for v in unpack_lsb_first(sub.payload, 20)]
+        channels = tuple(f"optics_{n}" for n in range(width))
+        return Reading("optics", channels, _rows(values, width), sub.sequence, rate)
+    if sub.kind == IMU:
+        v = _s16(sub.payload)
+        rows = tuple(
+            tuple(x * G_PER_BIT for x in v[i : i + 3])
+            + tuple(x * DPS_PER_BIT for x in v[i + 3 : i + 6])
+            for i in range(0, 18, 6)
+        )
+        return Reading("imu", IMU_CHANNELS, rows, sub.sequence, rate)
+    if sub.kind == DRL_REF:
+        values = [float(x) for x in _s16(sub.payload)]
+        return Reading("drl_ref", ("drl", "ref"), _rows(values, 2), sub.sequence, rate)
+    if sub.kind == BATTERY:
+        # Only the first field is known: charge percent as u16 LE / 256.
+        percent = int.from_bytes(sub.payload[:2], "little") / 256
+        return Reading("battery", ("percent",), ((percent,),), sub.sequence, rate)
+    raise ValueError(f"no reading for sub-packet type {sub.kind}")
+
+
+def readings(data: bytes, eeg_offset: int = 0) -> list[Reading]:
+    """Every reading in a notification, in order."""
+    return [
+        reading(sub, eeg_offset)
+        for frame in parse_notification(data)
+        for sub in frame.subpackets
+    ]
+
+
+def _rows(values: list[float], width: int) -> tuple[tuple[float, ...], ...]:
+    return tuple(tuple(values[i : i + width]) for i in range(0, len(values), width))
+
+
+def _s16(payload: bytes) -> list[int]:
+    return [
+        int.from_bytes(payload[i : i + 2], "little", signed=True)
+        for i in range(0, len(payload) - 1, 2)
+    ]

openble/muse/commands.py

@@ -0,0 +1,74 @@
+"""ASCII commands on ``SERIAL`` and their length-prefixed framing.
+
+Builders follow ``interaxon::cmd::nevis``; framing is ``ConnectorImpl::send``:
+one byte ``n`` (the command bytes that follow, ``\\n`` included, at most 19),
+then the ASCII command ending in ``\\n``. ``s`` goes out as ``02 73 0a``.
+Builders return the command text; ``encode`` frames it for the write.
+"""
+
+from __future__ import annotations
+
+from openble.muse.models import PRESETS
+
+MAX_PAYLOAD = 19  # command bytes after the length byte, "\n" included
+
+STATUS = "s"
+HALT = "h"
+KEEP_ALIVE = "k"  # every 2.5 s while paused
+BOOT_TO_HEADSET = "*1"  # leave the bootloader
+BOOT_TO_BOOTLOADER = "*0"  # for firmware update; no reply
+LED_ON = "L1"  # MU_04, MU_05 and MS_03 only; no reply
+LED_OFF = "L0"
+START_FLAGS = 0xC001  # meaning not known; public clients send it too
+START_LEGACY = "d"  # what muse-js and the per-sensor path in muse-rs send
+
+
+def encode(command: str) -> bytes:
+    """``[n][command]\\n`` as one write. Raises if it exceeds 19 bytes."""
+    body = (command + "\n").encode("ascii")
+    if len(body) > MAX_PAYLOAD:
+        raise ValueError(f"{command!r} is {len(body)} bytes with '\\n'; max 19")
+    return bytes((len(body),)) + body
+
+
+def expects_reply(command: str) -> bool:
+    """False for the fire-and-forget commands, which start with ``L`` or ``Q``."""
+    return not command.startswith(("L", "Q"))
+
+
+def version(offered: int = 7) -> str:
+    """``v<n>``: the version query, offering protocol version ``n`` in hex.
+
+    The app sends ``v7``. Public clients send ``v1``, ``v4`` or ``v6``.
+    """
+    if not 0 <= offered <= 0xF:
+        raise ValueError("offered protocol version is one hex digit")
+    return f"v{offered:x}"
+
+
+def preset(code: str) -> str:
+    """``p<code>``, e.g. ``p21`` or ``p1035``. Halt streaming first."""
+    code = code.upper()
+    if code not in PRESETS:
+        raise ValueError(f"unknown preset {code!r}")
+    return "p" + code
+
+
+def start_streaming(flags: int = START_FLAGS) -> str:
+    """``d`` + flags in hex, ``dc001``. Older clients send ``START_LEGACY``."""
+    return f"d{flags:x}"
+
+
+def led(on: bool) -> str:
+    return LED_ON if on else LED_OFF
+
+
+def clock_sync(index: int, host_ms: int) -> str:
+    """``Q<k> C,<12 hex digits>``: the universal v3 clock-sync answer.
+
+    ``host_ms`` is wall-clock milliseconds, most significant digit first.
+    What ``k`` counts is not recorded; this formats it in decimal.
+    """
+    if not 0 <= host_ms < 1 << 48:
+        raise ValueError("host time is 48 bits")
+    return f"Q{index} C,{host_ms:012x}"

openble/muse/identify.py

@@ -0,0 +1,43 @@
+"""Match an advertisement to a Muse headband (MuseManagerAndroid, LeDevice)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from openble.muse.models import GENERATIONS
+from openble.muse.uuids import SERVICE
+
+
+def classify(name: str, service_uuids: list[str]) -> tuple[list[str], list[str]]:
+    """Return ``(["headband"], reasons)`` for a Muse headband, else empty lists.
+
+    The app scans for service ``0xFE8D``; a name starting ``Muse`` also counts.
+    """
+    reasons: list[str] = []
+    if SERVICE in {uuid.lower() for uuid in service_uuids}:
+        reasons.append("service fe8d")
+    if name.startswith("Muse"):
+        reasons.append(f"name {name}")
+    return (["headband"] if reasons else []), reasons
+
+
+def generation(manufacturer_data: Mapping[int, bytes]) -> str | None:
+    """Hardware generation from byte 1 of the first manufacturer data entry.
+
+    Any company ID is accepted. Android and bleak both hand over the value
+    without the two company ID bytes. Returns ``aster``, ``letto``,
+    ``athena``, or None when absent or unknown.
+    """
+    for value in manufacturer_data.values():
+        return GENERATIONS.get(value[1]) if len(value) > 1 else None
+    return None
+
+
+def fallback_name(address: str, hardware: str | None = None) -> str:
+    """The name the app shows when the OS reports none.
+
+    ``Muse-`` (``MuseS-`` for generations 5-7) plus the last four hex digits
+    of the address. The status reply's ``hn`` replaces it after connecting.
+    """
+    digits = address.replace(":", "").replace("-", "").upper()[-4:]
+    return ("MuseS-" if hardware in GENERATIONS.values() else "Muse-") + digits

openble/muse/link.py

@@ -0,0 +1,196 @@
+"""The command link and the app's start-up sequence, over any transport.
+
+``nevis::ConnectorImpl`` keeps one command in flight and waits for its JSON
+reply before the next, except for ``L…`` and ``Q…``, which get none.
+``MuseLink`` copies that: it takes a ``write`` coroutine and is fed the
+``SERIAL`` notifications, so it runs over bleak, a test double, or anything
+else. ``prepare`` runs states 3-8 of the app's path to streaming.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+from openble.muse import commands, models, uuids
+from openble.muse.replies import (
+    MuseError,
+    Replies,
+    Status,
+    Version,
+    check_protocol,
+    parse_status,
+    parse_version,
+    return_code,
+)
+
+# interaxon::cmd::*_TIMEOUT, in seconds.
+VERSION_TIMEOUT = 10.0
+STATUS_TIMEOUT = 8.0
+SERIAL_TIMEOUT = 6.0
+KEEP_ALIVE_INTERVAL = 2.5  # while paused
+DATA_TIMEOUT = 6.0  # no data while streaming for this long is an error
+
+LICENCE_INVALID = 2  # dc001 rc
+
+
+class BootloaderError(MuseError):
+    """The headband runs its bootloader. Send ``*1`` (``boot_to_headset``) and reconnect."""
+
+
+@dataclass(frozen=True)
+class Session:
+    """What ``prepare`` learned, and what to subscribe to before ``start_streaming``."""
+
+    version: Version
+    status: Status
+    model: str
+    preset: str
+    layout: str  # "per-sensor", "universal" or "ble4"
+    # Data characteristics to subscribe to. TIME_SYNC is left out: its message
+    # format is still open.
+    subscribe: tuple[str, ...]
+
+
+class MuseLink:
+    """Send commands to one headband and match its JSON replies.
+
+    ``write`` sends one framed command to ``SERIAL``. The app writes without
+    response where the characteristic allows it. Call ``feed`` from the
+    ``SERIAL`` notification callback.
+    """
+
+    def __init__(
+        self,
+        write: Callable[[bytes], Awaitable[None]],
+        *,
+        log: Callable[..., None] | None = None,
+    ) -> None:
+        self._write = write
+        self._log = log or (lambda kind, **payload: None)
+        self._replies = Replies()
+        self._lock = asyncio.Lock()
+        self._pending: asyncio.Future[dict[str, Any]] | None = None
+
+    def feed(self, data: bytes) -> None:
+        """Take one ``SERIAL`` notification. Safe to call from a bleak callback."""
+        reply = self._replies.feed(bytes(data))
+        if reply is None:
+            return
+        self._log("reply", message=str(reply), data=reply)
+        if self._pending is not None and not self._pending.done():
+            self._pending.set_result(reply)
+        else:
+            self._log("unsolicited", message=str(reply), data=reply)
+
+    async def command(
+        self, command: str, timeout: float = SERIAL_TIMEOUT
+    ) -> dict[str, Any] | None:
+        """Write one command and return its reply, or None for ``L…``/``Q…``."""
+        payload = commands.encode(command)
+        async with self._lock:
+            if not commands.expects_reply(command):
+                self._log("write", message=command, data=payload)
+                await self._write(payload)
+                return None
+            self._pending = asyncio.get_running_loop().create_future()
+            try:
+                self._log("write", message=command, data=payload)
+                await self._write(payload)
+                async with asyncio.timeout(timeout):
+                    return await self._pending
+            except TimeoutError:
+                self._replies.reset()
+                raise TimeoutError(f"no reply to {command!r} in {timeout}s") from None
+            finally:
+                self._pending = None
+
+    async def version(
+        self, offered: int = 7, timeout: float = VERSION_TIMEOUT
+    ) -> Version:
+        return parse_version(await self._reply(commands.version(offered), timeout))
+
+    async def status(self, timeout: float = STATUS_TIMEOUT) -> Status:
+        return parse_status(await self._reply(commands.STATUS, timeout))
+
+    async def halt(self, timeout: float = SERIAL_TIMEOUT) -> None:
+        """``h``. The app drops the connection on anything but ``{"rc":0}``."""
+        reply = await self._reply(commands.HALT, timeout)
+        if return_code(reply) != 0:
+            raise MuseError(f"halt failed: {reply}")
+
+    async def set_preset(self, code: str, timeout: float = SERIAL_TIMEOUT) -> None:
+        """``p<code>``. The headband refuses while streaming, so halt first."""
+        reply = await self._reply(commands.preset(code), timeout)
+        if return_code(reply) != 0:
+            raise MuseError(
+                f"preset {code} refused (wrong model, or streaming): {reply}"
+            )
+
+    async def start_streaming(
+        self, command: str | None = None, timeout: float = SERIAL_TIMEOUT
+    ) -> int:
+        """``dc001`` (or ``command``, e.g. ``commands.START_LEGACY``); returns ``rc``.
+
+        ``rc`` 2 is an invalid headband licence and raises. Any other
+        non-zero ``rc`` means it was already streaming, which the app accepts.
+        """
+        reply = await self._reply(command or commands.start_streaming(), timeout)
+        rc = return_code(reply)
+        if rc == LICENCE_INVALID:
+            raise MuseError(f"the headband licence is not valid: {reply}")
+        if rc != 0:
+            self._log("already-streaming", message=str(reply), data=reply)
+        return rc
+
+    async def keep_alive(self, timeout: float = SERIAL_TIMEOUT) -> None:
+        """``k``: send every ``KEEP_ALIVE_INTERVAL`` while paused."""
+        await self._reply(commands.KEEP_ALIVE, timeout)
+
+    async def led(self, on: bool) -> None:
+        """``L1``/``L0``; Muse S and Athena only. No reply comes back."""
+        await self.command(commands.led(on))
+
+    async def boot_to_headset(self, timeout: float = SERIAL_TIMEOUT) -> None:
+        """``*1``: leave the bootloader. Reconnect once the headband reboots."""
+        reply = await self._reply(commands.BOOT_TO_HEADSET, timeout)
+        if return_code(reply) == 1:
+            raise MuseError(f"firmware CRC failure: {reply}")
+
+    async def prepare(
+        self, preset: str | None = None, offered_version: int = 7
+    ) -> Session:
+        """Version, status, halt, preset, status: the app's path up to subscribing.
+
+        ``preset`` defaults to the app's default for the model. Next, subscribe
+        to ``Session.subscribe`` and call ``start_streaming``.
+        """
+        version = await self.version(offered_version)
+        check_protocol(version.protocol)
+        if version.in_bootloader:
+            raise BootloaderError(f"headband is in its bootloader: {version.raw}")
+        model = (await self.status()).model
+        code = (preset or models.default_preset(model)).upper()
+        await self.halt()
+        await self.set_preset(code)
+        status = await self.status()
+        subscribe = tuple(
+            uuid
+            for uuid in models.characteristics(model, version.protocol)
+            if uuid != uuids.TIME_SYNC
+        )
+        return Session(
+            version=version,
+            status=status,
+            model=model,
+            preset=code,
+            layout=models.layout(version.protocol),
+            subscribe=subscribe,
+        )
+
+    async def _reply(self, command: str, timeout: float) -> dict[str, Any]:
+        reply = await self.command(command, timeout)
+        assert reply is not None
+        return reply

openble/muse/models.py

@@ -0,0 +1,120 @@
+"""Models, capability sets and presets from the app's libmuse.
+
+The model comes from the first character of the serial number in the status
+reply (``bridge::get_model_from_serial_number``). The capability set decides
+which characteristics carry data (``DeviceCapability::get_characteristics``).
+"""
+
+from __future__ import annotations
+
+from openble.muse import uuids
+
+# MuseModel -> (product, capability set). Product names are the common public
+# ones; "inferred" rows come from the capability set alone.
+MODELS = {
+    "MU_01": ("Muse 2014", "classic"),  # classic Bluetooth, not covered
+    "MU_02": ("Muse 2016", "nevis"),
+    "MU_03": ("Muse 2", "blackcomb"),
+    "MU_06": ("Muse 2, later hardware (inferred)", "blackcomb"),
+    "MU_04": ("Muse S", "aster"),
+    "MU_05": ("Muse S, later hardware (inferred)", "aster"),
+    "MS_03": ("Muse S Athena", "athena"),
+    "GL_01": ("internal glasses device", "glasses"),
+    "AMHL_01": ("internal, product unknown", "blackcomb"),
+}
+
+# cmd::get_default_preset. Public Athena clients use 1041, 1034 or 1045 instead.
+DEFAULT_PRESETS = {
+    "MU_01": "14",
+    "MU_02": "21",
+    "MU_03": "21",
+    "MU_06": "21",
+    "MU_04": "21",
+    "MU_05": "21",
+    "MS_03": "1021",
+}
+
+# Models that take the L1 / L0 indicator LED commands.
+LED_MODELS = frozenset({"MU_04", "MU_05", "MS_03"})
+
+_NEVIS = (0x0002, 0x0003, 0x0004, 0x0005, 0x0006, 0x0007, 0x0008, 0x000B)
+_NEVIS += (0x000A, 0x0009)
+_BLACKCOMB = _NEVIS + (0x000F, 0x0010, 0x0011)
+CAPABILITIES = {
+    "nevis": _NEVIS,
+    "blackcomb": _BLACKCOMB,
+    "aster": _BLACKCOMB + (0x0012,),
+    "athena": (0x0013, 0x0014, 0x0015),
+    "glasses": _NEVIS + (0x000C, 0x000D, 0x000E),
+}
+
+# PRESET_MAP in muse_command.cpp, without the Muse 2014 codes.
+PRESETS = frozenset(
+    {"20", "21", "22", "23", "31", "32", "50", "51", "52", "53", "54", "55"}
+    | {"60", "61", "63"}
+    | {f"102{c}" for c in "123456789A"}
+    | {f"103{c}" for c in "123456"}
+    | {f"104{c}" for c in "123456"}
+)
+
+# Hardware generation, byte 1 of the manufacturer data (LeDevice.getInfo).
+GENERATIONS = {5: "aster", 6: "letto", 7: "athena"}
+
+
+def model_from_serial(serial: str) -> str:
+    """``MuseModel`` name for a serial number, e.g. ``"5031-…"`` -> ``"MU_04"``."""
+    first = serial[:1]
+    if first == "4":
+        return "MU_03" if serial[1:2] <= "2" else "MU_06"
+    model = {
+        "1": "MU_01",
+        "2": "MU_02",
+        "3": "GL_01",
+        "5": "MU_04",
+        "6": "MU_05",
+        "7": "MS_03",
+        "9": "AMHL_01",
+    }.get(first)
+    if model is None:
+        raise ValueError(f"unknown muse model from serial number {serial!r}")
+    return model
+
+
+def capability(model: str) -> str:
+    """The capability set of a model, e.g. ``"MS_03"`` -> ``"athena"``."""
+    try:
+        return MODELS[model][1]
+    except KeyError:
+        raise ValueError(f"unknown model {model!r}") from None
+
+
+def characteristics(model: str, protocol_version: int) -> tuple[str, ...]:
+    """Data characteristic uuids the app maps for a model, ``SERIAL`` not included.
+
+    Athena drops ``TIME_SYNC`` below protocol version 5.
+    """
+    suffixes = CAPABILITIES.get(capability(model))
+    if suffixes is None:
+        raise ValueError(f"{model} is not a BLE headband")
+    if protocol_version < 5:
+        suffixes = tuple(s for s in suffixes if s != 0x0015)
+    return tuple(uuids.muse_uuid(s) for s in suffixes)
+
+
+def default_preset(model: str) -> str:
+    """The preset the app selects for a model."""
+    try:
+        return DEFAULT_PRESETS[model]
+    except KeyError:
+        raise ValueError(f"no default preset for {model}") from None
+
+
+def layout(protocol_version: int) -> str:
+    """``"per-sensor"`` (pv 1-2), ``"universal"`` (pv 3) or ``"ble4"`` (pv >= 4)."""
+    if protocol_version < 1:
+        raise ValueError(f"protocol version {protocol_version} is below 1")
+    if protocol_version <= 2:
+        return "per-sensor"
+    if protocol_version == 3:
+        return "universal"
+    return "ble4"