Metadata-Version: 2.4
Name: wellue-ble
Version: 1.0.0
Summary: Talk to Wellue Checkme O2 pulse oximeters over Bluetooth Low Energy
Author: Dylan Sallee
License-Expression: Apache-2.0
Project-URL: Source, https://github.com/DylanSallee/wellue-ble
Keywords: ble,bluetooth,wellue,checkme,pulse-oximeter,home-assistant
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bleak>=0.22
Requires-Dist: bleak-retry-connector>=3.5
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# wellue-ble

[![PyPI](https://img.shields.io/pypi/v/wellue-ble)](https://pypi.org/project/wellue-ble/)
[![Python versions](https://img.shields.io/pypi/pyversions/wellue-ble)](https://pypi.org/project/wellue-ble/)

A Python library for reading live data from **Wellue Checkme O2** wrist pulse
oximeters (the Checkme O2 Max and Checkme O2 Ultra) over Bluetooth Low Energy.

It was written to power a Home Assistant integration, but it doesn't depend on
Home Assistant. You can use it from any Python program, or try it directly from
the command line.

> **Not a medical device.** This is an unofficial hobby project that isn't
> affiliated with Wellue or Viatom. Don't rely on it for medical decisions or
> alarms.

## What it can do

| Data | Field | Notes |
| --- | --- | --- |
| Blood oxygen (SpO2) | `oxygen_saturation_percent` | `None` when there's no valid reading |
| Heart rate | `heart_rate_bpm` | `None` when there's no valid reading |
| Perfusion index | `perfusion_index_percent` | Same scale as the official app, e.g. `2.3` |
| Motion | `motion` | Unitless; a higher number means more movement |
| Battery level | `battery_level_percent` | |
| Charging state | `charging_state`, `is_charging` | Not charging / charging / fully charged |
| Finger present | `finger_detected` | Ignored while the device is charging (see below) |
| Device information | `DeviceInfo` | Serial number, model, firmware, hardware, bootloader, protocol and file format versions, branch code, region |
| Current settings | `DeviceInfo` | SpO2 and heart rate alert settings, buzzer volume, vibration intensity, screen mode. **Read only** for now |

Planned: changing settings (alert thresholds, vibration, volume, screen mode,
storage interval).

## Installation

The library is published on [PyPI](https://pypi.org/project/wellue-ble/):

```console
pip install wellue-ble
```

Python 3.13 or newer is required. To work on the library itself, install it
from a copy of this repository instead (see [Development](#development)).

## Trying it from the command line

Close the ViHealth app first, or turn off Bluetooth on your phone. The device
only accepts **one connection at a time**.

```console
python -m wellue_ble scan                 # find nearby devices and their addresses
python -m wellue_ble info ADDRESS         # print device info and current settings
python -m wellue_ble monitor ADDRESS      # print a live reading every second
python -m wellue_ble --debug monitor ADDRESS   # same, plus every raw packet
```

On Linux and Windows, `ADDRESS` is the Bluetooth MAC address
(`AA:BB:CC:DD:EE:FF`). macOS hides MAC addresses, so `scan` shows a UUID
there. Use that UUID instead.

Example `monitor` output:

```text
SpO2 97%  HR 72 bpm  PI 2.3%  motion 0  battery 85%  charging NOT_CHARGING  finger yes
SpO2 --  HR --  PI --  motion --  battery 85%  charging NOT_CHARGING  finger no
```

## Using it from Python

```python
import asyncio
from bleak import BleakScanner
from wellue_ble import WellueCheckmeO2

async def main():
    ble_device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
    device = WellueCheckmeO2(ble_device)

    info = await device.get_device_info()
    print(info.serial_number, info.firmware_version)

    reading = await device.read_sensors()   # connects automatically if needed
    print(reading.oxygen_saturation_percent, reading.heart_rate_bpm)

    await device.disconnect()               # frees the device for the official app

asyncio.run(main())
```

The connection stays open between calls, so calling `read_sensors()` once a
second keeps one connection open rather than reconnecting every time. If the
connection drops, the next call reconnects. Every error the library raises on
purpose is a subclass of `WellueError`.

## How it works

The Checkme O2 uses a proprietary protocol on top of BLE. The device never
sends data by itself. Every value has to be requested:

1. **Connect** and subscribe to the device's *notify* characteristic, which is
   where its answers arrive.
2. **Write a request packet** to the device's *write* characteristic.
3. **Collect the answer.** A long answer is split across several BLE
   notifications. The library joins them back together, checks the checksum
   and decodes the contents.

Every packet, in both directions, has the same layout:

```text
 marker  command  ~command  block (2)  length (2)  payload (length bytes)  CRC-8
  0xAA                                                                      request
  0x55                                                                      response
```

The library uses two commands so far:

| Command | Code | Answer |
| --- | --- | --- |
| Get device info | `0x14` | JSON text (~264 bytes) with identity and settings |
| Read sensors | `0x17` | 13 bytes: SpO2, heart rate, battery, charging, motion, perfusion index, finger flag |

Other details:

- **Invalid readings.** With no finger on the sensor, the device sends
  placeholder values such as 127 or 255. A reading counts as valid only when a
  finger is detected, SpO2 is between 50 and 100 %, and heart rate is between
  30 and 250 bpm. If any check fails, all four health values are `None`.
- **Charging.** While the device sits in its charger, it sometimes reports a
  finger even when there isn't one. The library ignores the finger flag while
  the device is charging.

### Code layout

The code is split so that only one file touches Bluetooth. Everything else is
plain byte handling that you can explore in a Python shell without a device.

| File | What it does |
| --- | --- |
| [`const.py`](src/wellue_ble/const.py) | Names for the fixed values: UUIDs, command codes, timeouts |
| [`protocol.py`](src/wellue_ble/protocol.py) | Building request packets, checksums, joining response chunks |
| [`models.py`](src/wellue_ble/models.py) | Turning response payloads into `SensorReading` and `DeviceInfo` |
| [`device.py`](src/wellue_ble/device.py) | The `WellueCheckmeO2` class: connecting, sending commands, waiting for answers |
| [`exceptions.py`](src/wellue_ble/exceptions.py) | The errors the library can raise |
| [`__main__.py`](src/wellue_ble/__main__.py) | The command line tool |

## Development

```console
python -m venv .venv                 # create an isolated Python environment
source .venv/bin/activate            # use it in this terminal
python -m pip install -e ".[dev]"    # install this library (editable) plus dev tools
python -m ruff check .               # check the code for mistakes
python -m ruff format .              # tidy the code's formatting
```

"Editable" means changes to the files in `src/` take effect immediately, with
no reinstall needed.

### Releasing a new version

Releases are published to PyPI automatically by
[`publish.yml`](.github/workflows/publish.yml):

1. Raise `version` in `pyproject.toml` and commit. PyPI never accepts the same
   version number twice.
2. On GitHub, open **Releases → Draft a new release**, create a tag matching
   the version (for example `v0.1.1`) and click **Publish release**.
3. The workflow builds the package and uploads it to
   [TestPyPI](https://test.pypi.org/project/wellue-ble/) first, then to PyPI.
   If the TestPyPI upload fails, it stops before uploading to PyPI.

## Acknowledgements

The protocol was worked out with the help of these open source projects:
[o2r](https://github.com/shadowmoon-waltz/o2r) and
[viatom-ble](https://github.com/ecostech/viatom-ble). They were used as
reference only, and no code was copied from them.

## License

Apache License 2.0. See [LICENSE](LICENSE).
