emay-sleepo2 1.0.1__tar.gz

emay_sleepo2-1.0.1/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: emay-sleepo2
+Version: 1.0.1
+Summary: BLE client and CSV parser for the EMAY SleepO2 pulse oximeter
+Author: Ground Effect Software, LLC
+License: MIT
+Project-URL: Homepage, https://github.com/chenders/emay-sleepo2
+Project-URL: Repository, https://github.com/chenders/emay-sleepo2
+Project-URL: Issues, https://github.com/chenders/emay-sleepo2/issues
+Project-URL: Specification, https://github.com/chenders/emay-sleepo2/blob/main/spec.md
+Keywords: emay,sleepo2,pulse-oximeter,spo2,ble,bluetooth,health,medical,oximetry,wearable
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == "ble"
+Provides-Extra: csv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: all
+Requires-Dist: bleak>=0.22; extra == "all"
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: ruff; extra == "all"

emay_sleepo2-1.0.1/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "emay-sleepo2"
+version = "1.0.1"
+description = "BLE client and CSV parser for the EMAY SleepO2 pulse oximeter"
+readme = { file = "../../README.md", content-type = "text/markdown" }
+license = { text = "MIT" }
+authors = [{ name = "Ground Effect Software, LLC" }]
+keywords = [
+    "emay", "sleepo2", "pulse-oximeter", "spo2", "ble", "bluetooth",
+    "health", "medical", "oximetry", "wearable"
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Healthcare Industry",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+ble = ["bleak>=0.22"]
+csv = []
+dev = ["pytest", "ruff"]
+all = ["bleak>=0.22", "pytest", "ruff"]
+
+[project.urls]
+Homepage = "https://github.com/chenders/emay-sleepo2"
+Repository = "https://github.com/chenders/emay-sleepo2"
+Issues = "https://github.com/chenders/emay-sleepo2/issues"
+Specification = "https://github.com/chenders/emay-sleepo2/blob/main/spec.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

emay_sleepo2-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

emay_sleepo2-1.0.1/src/emay_sleepo2/__init__.py

@@ -0,0 +1,34 @@
+"""EMAY SleepO2 BLE SDK — Python."""
+
+from .types import Reading, MinuteSample, Status
+from .protocol import (
+    parse_reading, checksum, command,
+    HELLO, DEVICE_STATE, START_REALTIME, STOP_REALTIME, GET_BATTERY, HEARTBEAT,
+    SERVICE_UUID, WRITE_UUID, NOTIFY_UUID,
+)
+from .downsampler import LiveDownsampler
+from .csv_parser import parse_csv, parse_csv_file
+
+# EMAYClient requires bleak (pip install bleak). Import it explicitly
+# to avoid load failures when only CSV parsing is needed.
+try:
+    from .client import EMAYClient
+except ImportError:
+    EMAYClient = None  # type: ignore
+
+__all__ = [
+    "Reading",
+    "MinuteSample",
+    "Status",
+    "LiveDownsampler",
+    "parse_csv",
+    "parse_csv_file",
+    "parse_reading",
+    "checksum",
+    "command",
+    "HELLO", "DEVICE_STATE", "START_REALTIME", "STOP_REALTIME",
+    "GET_BATTERY", "HEARTBEAT",
+    "SERVICE_UUID", "WRITE_UUID", "NOTIFY_UUID",
+]
+if EMAYClient is not None:
+    __all__.append("EMAYClient")

emay_sleepo2-1.0.1/src/emay_sleepo2/client.py

@@ -0,0 +1,244 @@
+"""Bleak-based client for the EMAY SleepO2 pulse oximeter."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from datetime import datetime, timezone
+from typing import Callable, List, Optional
+
+from bleak import BleakClient, BleakScanner
+from bleak.backends.device import BLEDevice
+from bleak.backends.characteristic import BleakGATTCharacteristic
+
+from .protocol import (
+    SERVICE_UUID, WRITE_UUID, NOTIFY_UUID, NAME_PREFIX,
+    HEARTBEAT, START_REALTIME, START_SEQUENCE, STOP_REALTIME,
+    parse_reading,
+)
+from .types import Reading, Status, MinuteSample
+from .downsampler import LiveDownsampler
+
+logger = logging.getLogger(__name__)
+
+
+class EMAYClient:
+    """Async BLE client for the EMAY SleepO2.
+
+    Example::
+
+        emay = EMAYClient()
+        emay.on_reading = lambda r: print(f"SpO2: {r.spo2}%  HR: {r.pulse}")
+        await emay.start()
+        await asyncio.sleep(30)
+        await emay.stop()
+    """
+
+    def __init__(
+        self,
+        heartbeat_interval: float = 1.5,
+        stale_timeout: float = 4.0,
+        auto_reconnect: bool = True,
+    ):
+        self.heartbeat_interval = heartbeat_interval
+        self.stale_timeout = stale_timeout
+        self.auto_reconnect = auto_reconnect
+
+        # Callbacks
+        self.on_reading: Optional[Callable[[Reading], None]] = None
+        self.on_status_change: Optional[Callable[[Status], None]] = None
+        self.on_minute_samples: Optional[Callable[[List[MinuteSample]], None]] = None
+
+        # State
+        self._status: Status = Status.IDLE
+        self._latest_reading: Optional[Reading] = None
+        self._last_reading_at: Optional[datetime] = None
+        self._client: Optional[BleakClient] = None
+        self._device: Optional[BLEDevice] = None
+        self._notify_char: Optional[BleakGATTCharacteristic] = None
+        self._write_char: Optional[BleakGATTCharacteristic] = None
+        self._heartbeat_task: Optional[asyncio.Task] = None
+        self._want_scan = False
+        self._downsampler = LiveDownsampler()
+        self._known_address: Optional[str] = None
+
+    @property
+    def status(self) -> Status:
+        return self._status
+
+    @status.setter
+    def status(self, value: Status) -> None:
+        if self._status != value:
+            self._status = value
+            if self.on_status_change:
+                self.on_status_change(value)
+
+    @property
+    def latest_reading(self) -> Optional[Reading]:
+        return self._latest_reading
+
+    @property
+    def is_streaming(self) -> bool:
+        return self._status == Status.STREAMING
+
+    async def start(self, address: Optional[str] = None) -> None:
+        """Start monitoring for the oximeter."""
+        if self._status.is_active:
+            return
+        self._want_scan = True
+        self._known_address = address or self._known_address
+        self.status = Status.SCANNING
+        await self._begin_monitoring()
+
+    async def stop(self) -> None:
+        """Stop streaming and disconnect."""
+        self._want_scan = False
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            self._heartbeat_task = None
+        if self._client and self._client.is_connected and self._write_char:
+            try:
+                await self._client.write_gatt_char(self._write_char, STOP_REALTIME, response=True)
+            except Exception:
+                pass
+        if self._client:
+            try:
+                await self._client.disconnect()
+            except Exception:
+                pass
+        self._reset_connection_state()
+        self.status = Status.IDLE
+
+    async def _begin_monitoring(self) -> None:
+        if self._device:
+            await self._connect_to(self._device)
+            return
+        if self._known_address:
+            # Try to find the known device
+            device = await BleakScanner.find_device_by_address(self._known_address)
+            if device:
+                await self._connect_to(device)
+                return
+        await self._scan()
+
+    async def _scan(self) -> None:
+        self.status = Status.SCANNING
+
+        def _filter(device: BLEDevice, adv_data) -> bool:
+            if SERVICE_UUID.lower() not in [s.lower() for s in adv_data.service_uuids or []]:
+                return False
+            name = adv_data.local_name or device.name or ""
+            return not name or name.startswith(NAME_PREFIX)
+
+        device = await BleakScanner.find_device_by_filter(_filter, timeout=10)
+        if device is None:
+            self.status = Status.FAILED
+            if self.on_status_change:
+                self.on_status_change(Status.FAILED)
+            return
+        self._known_address = device.address
+        await self._connect_to(device)
+
+    async def _connect_to(self, device: BLEDevice) -> None:
+        self._device = device
+        self.status = Status.CONNECTING
+        client = BleakClient(
+            device,
+            disconnected_callback=self._on_disconnect,
+        )
+        try:
+            await client.connect()
+        except Exception as e:
+            self.status = Status.FAILED
+            if self.on_status_change:
+                self.on_status_change(Status.FAILED)
+            logger.error(f"EMAY: connect failed: {e}")
+            return
+        self._client = client
+        await self._start_streaming()
+
+    async def _start_streaming(self) -> None:
+        client = self._client
+        assert client is not None
+        # Discover and enable
+        svc = client.services.get_service(SERVICE_UUID)
+        if svc is None:
+            self.status = Status.FAILED
+            logger.error("EMAY: service not found")
+            return
+        self._write_char = svc.get_characteristic(WRITE_UUID)
+        self._notify_char = svc.get_characteristic(NOTIFY_UUID)
+        if self._write_char is None or self._notify_char is None:
+            self.status = Status.FAILED
+            logger.error("EMAY: characteristics not found")
+            return
+
+        await client.start_notify(self._notify_char, self._on_data)
+
+        # Serialized start sequence
+        for cmd in START_SEQUENCE:
+            await client.write_gatt_char(self._write_char, cmd, response=True)
+        self.status = Status.STREAMING
+        self._start_heartbeat()
+
+    def _on_data(self, char: BleakGATTCharacteristic, data: bytearray) -> None:
+        result = parse_reading(bytes(data))
+        if result is None:
+            return
+        spo2, pulse = result
+        reading = Reading(spo2=spo2, pulse=pulse)
+        self._latest_reading = reading
+        self._last_reading_at = datetime.now(timezone.utc)
+        if self.on_reading:
+            self.on_reading(reading)
+
+        minutes = self._downsampler.add(reading)
+        if minutes and self.on_minute_samples:
+            self.on_minute_samples(minutes)
+
+    def _on_disconnect(self, client: BleakClient) -> None:
+        was_failure = self._status == Status.FAILED
+        is_transient = self._want_scan and not was_failure and self.auto_reconnect
+        if not is_transient:
+            _ = self._downsampler.flush()
+        self._reset_connection_state()
+        if is_transient:
+            asyncio.ensure_future(self._begin_monitoring())
+        elif not was_failure:
+            self.status = Status.IDLE
+
+    def _start_heartbeat(self) -> None:
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+        self._heartbeat_task = asyncio.ensure_future(self._heartbeat_loop())
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self.heartbeat_interval)
+            if self._status != Status.STREAMING or self._client is None:
+                return
+            if self._write_char:
+                try:
+                    await self._client.write_gatt_char(self._write_char, HEARTBEAT, response=True)
+                except Exception:
+                    pass
+            # Staleness watchdog
+            if self._last_reading_at is not None:
+                if (datetime.now(timezone.utc) - self._last_reading_at).total_seconds() > self.stale_timeout:
+                    if self._latest_reading is not None:
+                        self._latest_reading = None
+                        self._downsampler.flush()
+
+    def _reset_connection_state(self) -> None:
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            self._heartbeat_task = None
+        self._client = None
+        self._device = None
+        self._write_char = None
+        self._notify_char = None
+        self._latest_reading = None
+        self._last_reading_at = None
+
+
+__all__ = ["EMAYClient"]

emay_sleepo2-1.0.1/src/emay_sleepo2/csv_parser.py

@@ -0,0 +1,130 @@
+"""CSV parser for EMAY SleepO2 export files.
+
+The device's companion app exports sleep sessions as CSV with columns:
+Date,Time,SpO2(%),PR(bpm). No BLE hardware is required.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone, timedelta
+from pathlib import Path
+from typing import List, Tuple, Optional
+
+from .types import Reading
+
+
+class DSTFoldCorrector:
+    """Restores physical (monotonic) time across DST fall-back transitions.
+
+    Without correction, the repeated 1–2 AM hour on clocks-back night
+    produces duplicate wall-clock timestamps, silently erasing an hour
+    of real data.
+    """
+
+    MIN_BACKWARD_JUMP: float = 5.0
+    MAX_BACKWARD_JUMP: float = 7200.0  # 2 hours
+    FOLD_DURATION: float = 3600.0  # 1 hour
+
+    def __init__(self, tz: timezone | None = None):
+        import time as _time
+        # Store seconds offset from UTC for DST transition detection.
+        # We use isdst to detect whether the timezone is currently in DST.
+        self._tz = tz
+        self._offset: float = 0.0
+        self._previous: Optional[datetime] = None
+
+    def corrected(self, parsed: datetime) -> datetime:
+        """Feed naively parsed timestamps in file order; returns
+        the fold-corrected physical timestamp."""
+        if self._previous is None:
+            self._previous = parsed
+            return parsed
+
+        # Once naive parse catches up to corrected timeline, wall clock
+        # has passed the ambiguous hour — stop compensating.
+        if self._offset > 0 and parsed >= self._previous:
+            self._offset = 0.0
+
+        candidate = parsed + timedelta(seconds=self._offset)
+        delta = (candidate - self._previous).total_seconds()
+
+        if (
+            delta < -self.MIN_BACKWARD_JUMP
+            and delta >= -self.MAX_BACKWARD_JUMP
+            and self._tz is not None
+            and _clocks_fell_back(self._previous, self._tz)
+        ):
+            self._offset += self.FOLD_DURATION
+            candidate = parsed + timedelta(seconds=self._offset)
+
+        self._previous = candidate
+        return candidate
+
+
+def _clocks_fell_back(instant: datetime, tz: timezone) -> bool:
+    """True only when the timezone transitioned clocks back near instant."""
+    try:
+        import time as _time
+    except ImportError:
+        return False
+    # Check if instant is in DST and 1 hour earlier is not —
+    # this is a heuristic for fall-back transition proximity.
+    before = instant - timedelta(hours=1)
+    before_dst = before.astimezone(tz).dst() != timedelta(0)
+    instant_dst = instant.astimezone(tz).dst() != timedelta(0)
+    return before_dst and not instant_dst
+
+
+def parse_csv(content: str, timezone: timezone | None = None,
+              correct_dst_fold: bool = True) -> Tuple[List[Reading], List[str]]:
+    """Parse EMAY CSV content.
+
+    Returns (readings, warnings). Raises ValueError if the file has no
+    data rows.
+    """
+    lines = [line.strip() for line in content.splitlines() if line.strip()]
+    if len(lines) <= 1:
+        raise ValueError("CSV file contains no data rows")
+
+    warnings: List[str] = []
+    readings: List[Reading] = []
+    corrector = DSTFoldCorrector(tz=timezone if correct_dst_fold else None)
+
+    for i, line in enumerate(lines[1:], start=2):
+        fields = [f.strip() for f in line.split(",")]
+        if len(fields) < 2:
+            warnings.append(f"Row {i}: skipping — expected at least date,time columns")
+            continue
+
+        date_str = f"{fields[0]} {fields[1]}"
+        try:
+            parsed = datetime.strptime(date_str, "%m/%d/%Y %I:%M:%S %p")
+        except ValueError:
+            warnings.append(f"Row {i}: skipping — invalid date/time '{date_str}'")
+            continue
+
+        # Attach local timezone info if provided
+        if timezone is not None:
+            parsed = parsed.replace(tzinfo=timezone)
+
+        timestamp = corrector.corrected(parsed) if correct_dst_fold else parsed
+
+        spo2_str = fields[2] if len(fields) > 2 else ""
+        pr_str = fields[3] if len(fields) > 3 else ""
+
+        spo2 = int(spo2_str) if spo2_str else None
+        pulse = int(pr_str) if pr_str else None
+
+        readings.append(Reading(spo2=spo2, pulse=pulse, timestamp=timestamp))
+
+    return readings, warnings
+
+
+def parse_csv_file(path: str | Path, timezone: timezone | None = None,
+                   correct_dst_fold: bool = True) -> Tuple[List[Reading], List[str]]:
+    """Parse an EMAY CSV file from disk."""
+    content = Path(path).read_text(encoding="utf-8")
+    return parse_csv(content, timezone=timezone, correct_dst_fold=correct_dst_fold)
+
+
+__all__ = ["parse_csv", "parse_csv_file", "DSTFoldCorrector"]

emay_sleepo2-1.0.1/src/emay_sleepo2/downsampler.py

@@ -0,0 +1,81 @@
+"""Per-minute downsampler for the ~1 Hz EMAY stream."""
+
+from __future__ import annotations
+
+import threading
+from datetime import datetime, timedelta
+from typing import Callable, List, Optional
+
+from .types import MinuteSample, Reading
+
+
+def _start_of_minute(dt: datetime) -> datetime:
+    return dt.replace(second=0, microsecond=0)
+
+
+class LiveDownsampler:
+    """Buffers ~1 Hz EMAY readings into per-minute mean samples.
+
+    Thread-safe. Use in a BLE callback to accumulate readings; finalized
+    minutes are returned from add().
+    """
+
+    def __init__(self, minimum_samples_per_minute: int = 2):
+        self.minimum_samples_per_minute = minimum_samples_per_minute
+        self._lock = threading.Lock()
+        self._spo2_values: List[float] = []
+        self._pulse_values: List[float] = []
+        self._current_minute: Optional[datetime] = None
+
+    def add(self, reading: Reading) -> List[MinuteSample]:
+        """Feed a new reading into the current minute bucket.
+
+        Returns any finalized MinuteSamples (typically 0 or 2 per call).
+        """
+        with self._lock:
+            minute = _start_of_minute(reading.timestamp)
+            flushed: List[MinuteSample] = []
+
+            if self._current_minute is not None and minute != self._current_minute:
+                flushed = self._finalize_locked()
+
+            self._current_minute = minute
+            if reading.spo2 is not None:
+                self._spo2_values.append(float(reading.spo2))
+            if reading.pulse is not None:
+                self._pulse_values.append(float(reading.pulse))
+            return flushed
+
+    def flush(self) -> List[MinuteSample]:
+        """Finalize and return the current partial bucket."""
+        with self._lock:
+            return self._finalize_locked()
+
+    def _finalize_locked(self) -> List[MinuteSample]:
+        if self._current_minute is None:
+            return []
+        minute = self._current_minute
+        spo2_vals = self._spo2_values
+        pulse_vals = self._pulse_values
+        self._spo2_values = []
+        self._pulse_values = []
+        self._current_minute = None
+
+        samples: List[MinuteSample] = []
+        if len(spo2_vals) >= self.minimum_samples_per_minute:
+            mean = sum(spo2_vals) / len(spo2_vals)
+            samples.append(MinuteSample(
+                minute_start=minute,
+                metric_type="SpO2",
+                value=mean / 100.0,
+                unit_string="%"
+            ))
+        if len(pulse_vals) >= self.minimum_samples_per_minute:
+            mean = sum(pulse_vals) / len(pulse_vals)
+            samples.append(MinuteSample(
+                minute_start=minute,
+                metric_type="PulseRate",
+                value=mean,
+                unit_string="count/min"
+            ))
+        return samples

emay_sleepo2-1.0.1/src/emay_sleepo2/protocol.py

@@ -0,0 +1,87 @@
+"""Pure-protocol layer for the EMAY SleepO2 BLE protocol.
+
+Contains no Bluetooth calls, no async, no platform dependencies. Each
+language binding reimplements these functions with that language's
+byte-manipulation idioms.
+"""
+
+from __future__ import annotations
+
+from typing import List, Optional, Tuple
+
+# ---- BLE identifiers ----
+SERVICE_UUID = "0000ff12-0000-1000-8000-00805f9b34fb"
+WRITE_UUID = "0000ff01-0000-1000-8000-00805f9b34fb"
+NOTIFY_UUID = "0000ff02-0000-1000-8000-00805f9b34fb"
+NAME_PREFIX = "SleepO2"
+
+# ---- Commands ----
+HELLO: bytes = bytes([0x89, 0x09])
+DEVICE_STATE: bytes = bytes([0x8E, 0x05, 0x13])
+START_REALTIME: bytes = bytes([0x9B, 0x01, 0x1C])
+STOP_REALTIME: bytes = bytes([0x9B, 0x7F, 0x1A])
+GET_BATTERY: bytes = bytes([0x86, 0x06])
+HEARTBEAT: bytes = bytes([0x9A, 0x1A])
+
+START_SEQUENCE: List[bytes] = [HELLO, DEVICE_STATE, START_REALTIME, GET_BATTERY]
+
+# ---- Data frame constants ----
+FRAME_LENGTH: int = 8
+FRAME_HEADER: bytes = bytes([0xEB, 0x01, 0x05])
+FRAME_TRAILER: bytes = bytes([0x7F, 0x00])
+
+# ---- Plausibility bounds ----
+PULSE_MIN_BPM: int = 30
+PULSE_MAX_BPM: int = 220
+SPO2_MAX_PERCENT: int = 100
+SPO2_MIN_PERCENT: int = 0
+
+# ---- Sentinel values ----
+_SENTINEL_VALUES = {0x00, 0xFF}
+
+
+def checksum(payload: bytes) -> int:
+    """Compute the EMAY checksum: sum(payload) & 0x7F.
+
+    The 0x7F mask (NOT 0xFF) is crucial — 0xFF produces invalid
+    checksums that the device silently ignores.
+    """
+    return sum(payload) & 0x7F
+
+
+def command(payload: bytes) -> bytes:
+    """Build a full command frame: payload + checksum."""
+    return payload + bytes([checksum(payload)])
+
+
+def parse_reading(raw: bytes) -> Optional[Tuple[Optional[int], Optional[int]]]:
+    """Attempt to parse an 8-byte raw frame from the BLE notify characteristic.
+
+    Returns (spo2, pulse) as a tuple on success, or None if the frame
+    fails any validation check. Both spo2 and pulse can individually be
+    None when the sensor reports "no finger detected" for that metric.
+    """
+    if len(raw) != FRAME_LENGTH:
+        return None
+    if raw[0] != FRAME_HEADER[0] or raw[1] != FRAME_HEADER[1] or raw[2] != FRAME_HEADER[2]:
+        return None
+    if raw[5] != FRAME_TRAILER[0] or raw[6] != FRAME_TRAILER[1]:
+        return None
+
+    cks = sum(raw[:7]) & 0x7F
+    if raw[7] != cks:
+        return None
+
+    raw_pr = raw[3]
+    raw_spo2 = raw[4]
+
+    pr: Optional[int] = None if raw_pr in _SENTINEL_VALUES else raw_pr
+    spo2: Optional[int] = None if raw_spo2 in _SENTINEL_VALUES else raw_spo2
+
+    # Application-level plausibility bounds
+    if pr is not None and (pr < PULSE_MIN_BPM or pr > PULSE_MAX_BPM):
+        return None
+    if spo2 is not None and (spo2 < SPO2_MIN_PERCENT or spo2 > SPO2_MAX_PERCENT):
+        return None
+
+    return (spo2, pr)

emay_sleepo2-1.0.1/src/emay_sleepo2/types.py

@@ -0,0 +1,64 @@
+"""Data types for the EMAY SleepO2 SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum, auto
+from typing import Optional
+
+
+@dataclass(frozen=True, slots=True)
+class Reading:
+    """A single physiological reading from the EMAY SleepO2.
+
+    Both spo2 and pulse are optional — the device can report a valid
+    pulse rate without SpO₂ (finger partially on) or vice versa. None
+    means the sensor couldn't acquire that measurement, NOT zero
+    saturation or asystole.
+    """
+
+    spo2: Optional[int]  # Oxygen saturation percent (0–100)
+    pulse: Optional[int]  # Pulse rate in bpm
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def __repr__(self) -> str:
+        s = f"{self.spo2}%" if self.spo2 is not None else "—"
+        p = f"{self.pulse}" if self.pulse is not None else "—"
+        return f"Reading(spo2={s}, pulse={p})"
+
+
+@dataclass(frozen=True, slots=True)
+class MinuteSample:
+    """A finalized per-minute mean sample."""
+
+    minute_start: datetime
+    metric_type: str  # "SpO2" or "PulseRate"
+    value: float
+    unit_string: str  # "%" or "count/min"
+
+
+class Status(Enum):
+    """Observable connection/streaming state."""
+
+    IDLE = auto()
+    SCANNING = auto()
+    CONNECTING = auto()
+    STREAMING = auto()
+    BLUETOOTH_OFF = auto()
+    BLUETOOTH_UNAUTHORIZED = auto()
+    BLUETOOTH_UNSUPPORTED = auto()
+    FAILED = auto()
+
+    @property
+    def is_active(self) -> bool:
+        """Whether a session is actively in progress."""
+        return self in (Status.SCANNING, Status.CONNECTING, Status.STREAMING)
+
+
+@dataclass(frozen=True, slots=True)
+class StatusEvent:
+    """A status change event from the client."""
+
+    status: Status
+    message: str = ""

emay_sleepo2-1.0.1/src/emay_sleepo2.egg-info/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.4
+Name: emay-sleepo2
+Version: 1.0.1
+Summary: BLE client and CSV parser for the EMAY SleepO2 pulse oximeter
+Author: Ground Effect Software, LLC
+License: MIT
+Project-URL: Homepage, https://github.com/chenders/emay-sleepo2
+Project-URL: Repository, https://github.com/chenders/emay-sleepo2
+Project-URL: Issues, https://github.com/chenders/emay-sleepo2/issues
+Project-URL: Specification, https://github.com/chenders/emay-sleepo2/blob/main/spec.md
+Keywords: emay,sleepo2,pulse-oximeter,spo2,ble,bluetooth,health,medical,oximetry,wearable
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == "ble"
+Provides-Extra: csv
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: all
+Requires-Dist: bleak>=0.22; extra == "all"
+Requires-Dist: pytest; extra == "all"
+Requires-Dist: ruff; extra == "all"

emay_sleepo2-1.0.1/src/emay_sleepo2.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+pyproject.toml
+src/emay_sleepo2/__init__.py
+src/emay_sleepo2/client.py
+src/emay_sleepo2/csv_parser.py
+src/emay_sleepo2/downsampler.py
+src/emay_sleepo2/protocol.py
+src/emay_sleepo2/types.py
+src/emay_sleepo2.egg-info/PKG-INFO
+src/emay_sleepo2.egg-info/SOURCES.txt
+src/emay_sleepo2.egg-info/dependency_links.txt
+src/emay_sleepo2.egg-info/requires.txt
+src/emay_sleepo2.egg-info/top_level.txt
+tests/test_csv.py
+tests/test_downsampler.py
+tests/test_protocol.py

emay_sleepo2-1.0.1/src/emay_sleepo2.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

emay_sleepo2-1.0.1/src/emay_sleepo2.egg-info/requires.txt

@@ -0,0 +1,14 @@
+
+[all]
+bleak>=0.22
+pytest
+ruff
+
+[ble]
+bleak>=0.22
+
+[csv]
+
+[dev]
+pytest
+ruff

emay_sleepo2-1.0.1/src/emay_sleepo2.egg-info/top_level.txt

@@ -0,0 +1 @@
+emay_sleepo2

emay_sleepo2-1.0.1/tests/test_csv.py

@@ -0,0 +1,40 @@
+"""Tests for EMAY CSV parser."""
+import pytest
+from emay_sleepo2.csv_parser import parse_csv, DSTFoldCorrector
+from datetime import datetime, timezone, timedelta
+
+
+def test_parse_valid():
+    csv = "Date,Time,SpO2(%),PR(bpm)\n5/8/2026,4:46:58 PM,98,52\n5/8/2026,4:47:00 PM,,58"
+    readings, warnings = parse_csv(csv, correct_dst_fold=False)
+    assert len(readings) == 2
+    assert readings[0].spo2 == 98
+    assert readings[0].pulse == 52
+    assert readings[1].spo2 is None
+    assert readings[1].pulse == 58
+
+
+def test_empty_throws():
+    with pytest.raises(ValueError):
+        parse_csv("Date,Time,SpO2(%),PR(bpm)")
+
+
+def test_invalid_date_warns():
+    csv = "Date,Time,SpO2(%),PR(bpm)\nbad,data,99,50\n5/8/2026,4:47:00 PM,98,52"
+    readings, warnings = parse_csv(csv, correct_dst_fold=False)
+    assert len(warnings) >= 1
+    assert len(readings) == 1
+    assert readings[0].spo2 == 98
+
+
+def test_dst_fold_no_correction_without_transition():
+    """Without a real DST transition, backward jumps are left alone."""
+    # Fixed-offset timezone has no DST transitions
+    utc = timezone.utc
+    corrector = DSTFoldCorrector(tz=utc)
+    t1 = datetime(2026, 11, 1, 1, 55, tzinfo=utc)
+    t2 = datetime(2026, 11, 1, 1, 5, tzinfo=utc)
+    c1 = corrector.corrected(t1)
+    c2 = corrector.corrected(t2)
+    # UTC has no DST → backward jump stays
+    assert c2 < c1, "Without DST transition, backward jump should NOT be corrected"

emay_sleepo2-1.0.1/tests/test_downsampler.py

@@ -0,0 +1,76 @@
+"""Tests for EMAY downsampler."""
+from datetime import datetime, timedelta
+from emay_sleepo2.downsampler import LiveDownsampler
+from emay_sleepo2.types import Reading
+
+
+def _reading(spo2, pulse, minute=10, second=30):
+    ts = datetime(2026, 5, 8, 16, minute, second)
+    return Reading(spo2=spo2, pulse=pulse, timestamp=ts)
+
+
+def test_below_minimum():
+    ds = LiveDownsampler(minimum_samples_per_minute=2)
+    result = ds.add(_reading(98, 60))
+    assert len(result) == 0
+
+
+def test_two_samples():
+    ds = LiveDownsampler(minimum_samples_per_minute=2)
+    ds.add(_reading(98, 60, second=30))
+    ds.add(_reading(96, 62, second=31))
+    result = ds.flush()
+    spo2 = [s for s in result if s.metric_type == "SpO2"][0]
+    pulse = [s for s in result if s.metric_type == "PulseRate"][0]
+    assert spo2.value == 0.97
+    assert pulse.value == 61.0
+
+
+def test_minute_boundary():
+    ds = LiveDownsampler(minimum_samples_per_minute=1)
+    ds.add(_reading(98, None, minute=10, second=30))
+    flushed = ds.add(_reading(95, 60, minute=11, second=1))
+    assert len(flushed) == 1
+    assert flushed[0].metric_type == "SpO2"
+    assert flushed[0].value == 0.98
+
+
+def test_boundary_below_minimum():
+    ds = LiveDownsampler(minimum_samples_per_minute=5)
+    ds.add(_reading(98, 60, minute=10, second=30))
+    flushed = ds.add(_reading(95, 62, minute=11, second=1))
+    assert len(flushed) == 0
+
+
+def test_nil_metrics_excluded():
+    ds = LiveDownsampler(minimum_samples_per_minute=2)
+    ds.add(_reading(98, None, second=30))
+    ds.add(_reading(96, 60, second=31))
+    result = ds.flush()
+    pulse_samples = [s for s in result if s.metric_type == "PulseRate"]
+    assert len(pulse_samples) == 0
+
+
+def test_flush_empties():
+    ds = LiveDownsampler(minimum_samples_per_minute=1)
+    ds.add(_reading(98, 60))
+    assert len(ds.flush()) > 0
+    assert len(ds.flush()) == 0
+
+
+def test_spo2_fraction():
+    ds = LiveDownsampler(minimum_samples_per_minute=1)
+    ds.add(_reading(50, 60))
+    result = ds.flush()
+    spo2 = [s for s in result if s.metric_type == "SpO2"][0]
+    assert spo2.value == 0.50
+    assert spo2.unit_string == "%"
+
+
+def test_pulse_unit():
+    ds = LiveDownsampler(minimum_samples_per_minute=1)
+    ds.add(_reading(98, 75))
+    result = ds.flush()
+    pulse = [s for s in result if s.metric_type == "PulseRate"][0]
+    assert pulse.value == 75.0
+    assert pulse.unit_string == "count/min"

emay_sleepo2-1.0.1/tests/test_protocol.py

@@ -0,0 +1,99 @@
+"""Tests for EMAY SleepO2 protocol."""
+import pytest
+from emay_sleepo2.protocol import parse_reading, checksum, command
+from emay_sleepo2.types import Reading
+
+
+def _frame(pr: int, spo2: int) -> bytes:
+    """Build a valid frame with given PR and SpO2."""
+    raw = bytearray([0xEB, 0x01, 0x05, pr, spo2, 0x7F, 0x00, 0x00])
+    raw[7] = sum(raw[:7]) & 0x7F
+    return bytes(raw)
+
+
+class TestChecksum:
+    def test_hello(self):
+        assert checksum(bytes([0x89])) == 0x09
+
+    def test_heartbeat(self):
+        assert checksum(bytes([0x9A])) == 0x1A
+
+    def test_start_realtime(self):
+        assert checksum(bytes([0x9B, 0x01])) == 0x1C
+
+    def test_device_state(self):
+        assert checksum(bytes([0x8E, 0x05])) == 0x13
+
+    def test_stop_realtime(self):
+        assert checksum(bytes([0x9B, 0x7F])) == 0x1A
+
+
+class TestParseReading:
+    def test_valid(self):
+        spo2, pr = parse_reading(_frame(62, 98))
+        assert pr == 62
+        assert spo2 == 98
+
+    def test_wrong_length(self):
+        assert parse_reading(b'\xEB\x01\x05\x3E\x62\x7F') is None
+
+    def test_bad_header(self):
+        raw = bytearray([0x00, 0x01, 0x05, 62, 98, 0x7F, 0x00, 0x00])
+        raw[7] = sum(raw[:7]) & 0x7F
+        assert parse_reading(bytes(raw)) is None
+
+    def test_bad_trailer(self):
+        raw = bytearray([0xEB, 0x01, 0x05, 62, 98, 0x00, 0x00, 0x00])
+        raw[7] = sum(raw[:7]) & 0x7F
+        assert parse_reading(bytes(raw)) is None
+
+    def test_bad_checksum(self):
+        assert parse_reading(bytes([0xEB, 0x01, 0x05, 62, 98, 0x7F, 0x00, 0xFF])) is None
+
+    def test_sentinel_pr_0(self):
+        spo2, pr = parse_reading(_frame(0x00, 98))
+        assert pr is None
+        assert spo2 == 98
+
+    def test_sentinel_pr_ff(self):
+        spo2, pr = parse_reading(_frame(0xFF, 98))
+        assert pr is None
+
+    def test_sentinel_spo2_0(self):
+        spo2, pr = parse_reading(_frame(62, 0x00))
+        assert spo2 is None
+        assert pr == 62
+
+    def test_sentinel_spo2_ff(self):
+        spo2, pr = parse_reading(_frame(62, 0xFF))
+        assert spo2 is None
+
+    def test_both_sentinels(self):
+        spo2, pr = parse_reading(_frame(0xFF, 0xFF))
+        assert spo2 is None
+        assert pr is None
+
+    def test_pulse_too_low(self):
+        assert parse_reading(_frame(29, 98)) is None
+
+    def test_pulse_too_high(self):
+        assert parse_reading(_frame(221, 98)) is None
+
+    def test_pulse_boundary_min(self):
+        _, pr = parse_reading(_frame(30, 98))
+        assert pr == 30
+
+    def test_pulse_boundary_max(self):
+        _, pr = parse_reading(_frame(220, 98))
+        assert pr == 220
+
+    def test_spo2_too_high(self):
+        assert parse_reading(_frame(62, 101)) is None
+
+    def test_spo2_boundary_min(self):
+        spo2, _ = parse_reading(_frame(62, 1))
+        assert spo2 == 1
+
+    def test_spo2_boundary_max(self):
+        spo2, _ = parse_reading(_frame(62, 100))
+        assert spo2 == 100