vitafit-ble 0.1.0__tar.gz

vitafit_ble-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Myatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vitafit_ble-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: vitafit-ble
+Version: 0.1.0
+Summary: Bluetooth library for Vitafit devices
+Author: James Myatt
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Dist: bleak>=1.0
+Requires-Dist: bleak-retry-connector>=4.0
+Requires-Dist: bluetooth-data-tools>=1.28
+Requires-Dist: bluetooth-sensor-state-data>=1.9
+Requires-Dist: habluetooth>=3.42.0
+Requires-Dist: sensor-state-data>=2.20
+Requires-Python: >=3.11
+Project-URL: Documentation, https://vitafit-ble.readthedocs.io
+Project-URL: Repository, https://github.com/jamesmyatt/vitafit-ble
+Project-URL: Bug Tracker, https://github.com/jamesmyatt/vitafit-ble/issues
+Project-URL: Changelog, https://github.com/jamesmyatt/vitafit-ble/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# vitafit-ble
+
+Bluetooth library for Vitafit devices. See [supported devices](docs/supported_devices.md) for the models it works with.
+
+Unofficial; not affiliated with Vitafit.
+
+## Install
+
+```sh
+pip install vitafit-ble
+```
+
+## Use
+
+```python
+from bleak import BleakClient
+from vitafit_ble import async_measure
+
+async with BleakClient(address) as client:
+    measurement = await async_measure(client)
+```
+
+It returns a `Measurement` with `weight_kg`, `impedance_ohm` and `display_unit`, or `None` if no stable weight arrives within 30 s. Weight is always in kg. `impedance_ohm` is `None` if impedance isn't measured, for example through socks or if you step off early.
+
+Pass `weight_only=True` to skip impedance (the Vitafit app's "Weight Only Mode"). The scale keeps this mode for later offline weigh-ins.
+
+`VitafitBluetoothDeviceData` wraps the same session for Home Assistant; its `async_poll` passes `weight_only` through.
+
+See [usage](docs/usage.md) for details.
+
+## Licence
+
+MIT. The protocol is based on openScale's
+[VT701 handler](https://github.com/oliexdev/openScale/pull/1423).

vitafit_ble-0.1.0/README.md

@@ -0,0 +1,34 @@
+# vitafit-ble
+
+Bluetooth library for Vitafit devices. See [supported devices](docs/supported_devices.md) for the models it works with.
+
+Unofficial; not affiliated with Vitafit.
+
+## Install
+
+```sh
+pip install vitafit-ble
+```
+
+## Use
+
+```python
+from bleak import BleakClient
+from vitafit_ble import async_measure
+
+async with BleakClient(address) as client:
+    measurement = await async_measure(client)
+```
+
+It returns a `Measurement` with `weight_kg`, `impedance_ohm` and `display_unit`, or `None` if no stable weight arrives within 30 s. Weight is always in kg. `impedance_ohm` is `None` if impedance isn't measured, for example through socks or if you step off early.
+
+Pass `weight_only=True` to skip impedance (the Vitafit app's "Weight Only Mode"). The scale keeps this mode for later offline weigh-ins.
+
+`VitafitBluetoothDeviceData` wraps the same session for Home Assistant; its `async_poll` passes `weight_only` through.
+
+See [usage](docs/usage.md) for details.
+
+## Licence
+
+MIT. The protocol is based on openScale's
+[VT701 handler](https://github.com/oliexdev/openScale/pull/1423).

vitafit_ble-0.1.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["uv_build>=0.12.21,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "vitafit-ble"
+version = "0.1.0"
+description = "Bluetooth library for Vitafit devices"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "bleak>=1.0",
+    "bleak-retry-connector>=4.0",
+    "bluetooth-data-tools>=1.28",
+    "bluetooth-sensor-state-data>=1.9",
+    "habluetooth>=3.42.0",
+    "sensor-state-data>=2.20",
+]
+
+[[project.authors]]
+name = "James Myatt"
+
+[project.urls]
+Documentation = "https://vitafit-ble.readthedocs.io"
+Repository = "https://github.com/jamesmyatt/vitafit-ble"
+"Bug Tracker" = "https://github.com/jamesmyatt/vitafit-ble/issues"
+Changelog = "https://github.com/jamesmyatt/vitafit-ble/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy",
+    "pre-commit",
+    "pytest",
+    "pytest-asyncio",
+    "pytest-cov",
+    "ruff",
+]
+docs = [
+    "furo",
+    "myst-parser",
+    "sphinx",
+    "sphinx-autobuild",
+]
+
+[tool.pytest.ini_options]
+addopts = "-v -Wdefault --cov=vitafit_ble --cov-report=term-missing:skip-covered"
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "@overload",
+    "if TYPE_CHECKING",
+    "raise NotImplementedError",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "CPY001",
+    "D203",
+    "D213",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D",
+    "S101",
+    "PLR2004",
+    "SLF001",
+]
+"docs/conf.py" = [
+    "A001",
+    "D100",
+    "INP001",
+]
+"scripts/**" = ["INP001"]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+combine-as-imports = true
+
+[tool.mypy]
+strict = true

vitafit_ble-0.1.0/pyproject.toml.orig

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build>=0.12.21,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "vitafit-ble"
+version = "0.1.0"
+description = "Bluetooth library for Vitafit devices"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "James Myatt" }]
+requires-python = ">=3.11"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Programming Language :: Python :: 3",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+dependencies = [
+  "bleak>=1.0",
+  "bleak-retry-connector>=4.0",
+  "bluetooth-data-tools>=1.28",
+  "bluetooth-sensor-state-data>=1.9",
+  "habluetooth>=3.42.0",
+  "sensor-state-data>=2.20",
+]
+
+[project.urls]
+"Documentation" = "https://vitafit-ble.readthedocs.io"
+"Repository" = "https://github.com/jamesmyatt/vitafit-ble"
+"Bug Tracker" = "https://github.com/jamesmyatt/vitafit-ble/issues"
+"Changelog" = "https://github.com/jamesmyatt/vitafit-ble/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["mypy", "pre-commit", "pytest", "pytest-asyncio", "pytest-cov", "ruff"]
+docs = ["furo", "myst-parser", "sphinx", "sphinx-autobuild"]
+
+[tool.pytest.ini_options]
+addopts = "-v -Wdefault --cov=vitafit_ble --cov-report=term-missing:skip-covered"
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+  "pragma: no cover",
+  "@overload",
+  "if TYPE_CHECKING",
+  "raise NotImplementedError",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["COM812", "CPY001", "D203", "D213"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["D", "S101", "PLR2004", "SLF001"]
+"docs/conf.py" = ["A001", "D100", "INP001"]
+"scripts/**" = ["INP001"]
+
+[tool.ruff.lint.isort]
+force-sort-within-sections = true
+combine-as-imports = true
+
+[tool.mypy]
+strict = true

vitafit_ble-0.1.0/src/vitafit_ble/__init__.py

@@ -0,0 +1,29 @@
+"""Bluetooth library for Vitafit devices."""
+
+from sensor_state_data import (
+    DeviceClass,
+    DeviceKey,
+    SensorDescription,
+    SensorDeviceInfo,
+    SensorUpdate,
+    SensorValue,
+    Units,
+)
+
+from .parser import VitafitBluetoothDeviceData
+from .protocol import DisplayUnit
+from .session import Measurement, async_measure
+
+__all__ = [
+    "DeviceClass",
+    "DeviceKey",
+    "DisplayUnit",
+    "Measurement",
+    "SensorDescription",
+    "SensorDeviceInfo",
+    "SensorUpdate",
+    "SensorValue",
+    "Units",
+    "VitafitBluetoothDeviceData",
+    "async_measure",
+]

vitafit_ble-0.1.0/src/vitafit_ble/const.py

@@ -0,0 +1,17 @@
+"""Constants for the Vitafit VT701."""
+
+#: The scale is recognised by a local name starting with this, e.g. "Vitafit Body Fat".
+LOCAL_NAME_PREFIX = "Vitafit"
+MANUFACTURER = "Vitafit"
+MODEL = "VT701"
+
+NOTIFY_CHARACTERISTIC_UUID = "0000fff1-0000-1000-8000-00805f9b34fb"
+WRITE_CHARACTERISTIC_UUID = "0000fff2-0000-1000-8000-00805f9b34fb"
+
+#: Seconds to wait for a stable weight.
+WEIGHT_TIMEOUT = 30.0
+#: Seconds to wait for impedance after acknowledging the stable weight.
+IMPEDANCE_TIMEOUT = 10.0
+
+#: Minimum seconds between connections, so one weigh-in is read once.
+POLL_INTERVAL = 60.0

vitafit_ble-0.1.0/src/vitafit_ble/parser.py

@@ -0,0 +1,87 @@
+"""Home Assistant-style device data for the Vitafit VT701."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from bleak.exc import BleakError
+from bleak_retry_connector import BleakClientWithServiceCache, establish_connection
+from bluetooth_data_tools import short_address
+from bluetooth_sensor_state_data import BluetoothData
+from sensor_state_data import SensorLibrary, SensorUpdate
+
+from .const import LOCAL_NAME_PREFIX, MANUFACTURER, MODEL, POLL_INTERVAL
+from .session import async_measure
+
+if TYPE_CHECKING:
+    from bleak.backends.device import BLEDevice
+    from habluetooth import BluetoothServiceInfo
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class VitafitBluetoothDeviceData(BluetoothData):
+    """Data for a Vitafit VT701 scale."""
+
+    def _start_update(self, service_info: BluetoothServiceInfo) -> None:
+        """Update from a BLE advertisement."""
+        if not (service_info.name or "").startswith(LOCAL_NAME_PREFIX):
+            return
+        self.set_device_manufacturer(MANUFACTURER)
+        self.set_device_type(MODEL)
+        name = f"{MANUFACTURER} {MODEL} {short_address(service_info.address)}"
+        self.set_device_name(name)
+        self.set_title(name)
+
+    def poll_needed(
+        self,
+        service_info: BluetoothServiceInfo,  # noqa: ARG002
+        last_poll: float | None,
+    ) -> bool:
+        """Return True if the scale should be connected to.
+
+        True for the first advertisement, then at most once every
+        ``POLL_INTERVAL`` (60 s), so one weigh-in is read once. Safe to call on
+        every advertisement. The scale only advertises while awake, i.e. after
+        being stepped on.
+        """
+        return last_poll is None or last_poll > POLL_INTERVAL
+
+    async def async_poll(
+        self,
+        ble_device: BLEDevice,
+        **measure_kwargs: Any,  # noqa: ANN401
+    ) -> SensorUpdate:
+        """Connect, read one weigh-in and disconnect.
+
+        The update has ``mass`` and ``impedance`` (``None`` if the scale
+        couldn't measure it). If no stable weight arrives, or a Bluetooth error
+        occurs, the update has no readings; the error is logged as a warning.
+
+        ``measure_kwargs`` are passed to ``async_measure``, for example
+        ``weight_only=True``.
+        """
+        _LOGGER.debug("Polling Vitafit scale: %s", ble_device.address)
+        client = await establish_connection(
+            BleakClientWithServiceCache, ble_device, ble_device.address
+        )
+        try:
+            measurement = await async_measure(client, **measure_kwargs)
+        except BleakError as err:
+            _LOGGER.warning("%s: weigh-in failed: %s", ble_device.address, err)
+            return self._finish_update()
+        finally:
+            await client.disconnect()
+            _LOGGER.debug("%s: disconnected", ble_device.address)
+
+        if measurement is None:
+            _LOGGER.debug("%s: no stable weight received", ble_device.address)
+        else:
+            self.update_predefined_sensor(
+                SensorLibrary.MASS__MASS_KILOGRAMS, measurement.weight_kg
+            )
+            self.update_predefined_sensor(
+                SensorLibrary.IMPEDANCE__OHM, measurement.impedance_ohm
+            )
+        return self._finish_update()

vitafit_ble-0.1.0/src/vitafit_ble/protocol.py

@@ -0,0 +1,206 @@
+"""Frame codec for the Vitafit VT701 GATT protocol.
+
+Frames in both directions are ``[header][length][0x26][type][data…][checksum][0xAA]``:
+
+- ``header`` is 0x5A from the scale and 0xA5 from the client.
+- ``length`` counts every byte after itself.
+- ``checksum`` is the XOR of ``length`` through the last data byte.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+from functools import reduce
+import logging
+from operator import xor
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Iterator
+
+_LOGGER = logging.getLogger(__name__)
+
+HEADER_SCALE = 0x5A
+HEADER_CLIENT = 0xA5
+PRODUCT_ID = 0x26
+TRAILER = 0xAA
+
+MODE_NORMAL = 0x00
+# The Vitafit app's weight-only mode: the scale passes no current and sends
+# impedance 0x55AA.
+MODE_WEIGHT_ONLY = 0x01
+
+# Weight frame byte 7 is UNIT_BASE + the current display unit, but the weight
+# itself is always sent in 0.01 kg.
+UNIT_BASE = 0x20
+
+STABLE_FLAG = 0x02
+
+MIN_FRAME_LENGTH = 6
+
+# Impedance outside this range is treated as no reading, as openScale does.
+IMPEDANCE_MIN_OHM = 1
+IMPEDANCE_MAX_OHM = 1499
+
+
+class FrameType(IntEnum):
+    """Frame type byte, the same in both directions."""
+
+    WEIGHT = 0x10
+    IMPEDANCE = 0x11
+    UNIT = 0x17
+    """Sets the scale's display unit; the data byte is a DisplayUnit.
+
+    It isn't needed for a weigh-in, so the session only sends it when asked to
+    set the unit.
+    """
+    MODE = 0x33
+    """Sets the measurement mode; the data byte is MODE_NORMAL or MODE_WEIGHT_ONLY.
+
+    The scale keeps the mode until the next mode command, including for
+    weigh-ins without a connection. openScale calls this the first hello.
+    """
+    HELLO = 0x44
+    """Unknown request, referred to as the hello command.
+
+    The scale replies with one data byte of unknown meaning, 0x00 so far.
+    """
+
+
+# Total length of each scale-to-client frame type that decode() reads.
+FRAME_LENGTHS: dict[int, int] = {FrameType.WEIGHT: 12, FrameType.IMPEDANCE: 13}
+
+
+class ImpedanceCode(IntEnum):
+    """Impedance values that mean the scale didn't measure it."""
+
+    FAILED = 0xFFFF
+    """No contact, for example through socks."""
+    WEIGHT_ONLY = 0x55AA
+    """The scale is in weight-only mode, so it passed no current."""
+
+
+class DisplayUnit(IntEnum):
+    """Unit shown on the scale's display. Readings are always sent in kg."""
+
+    KG = 1
+    LB = 2
+    ST = 3
+
+
+@dataclass(frozen=True, slots=True)
+class WeightFrame:
+    """Live weight reading."""
+
+    weight_kg: float
+    """Weight in kg, to 0.01 kg, whatever the display unit."""
+    stable: bool
+    """True once the reading has settled."""
+    display_unit: DisplayUnit | None
+    """Unit the scale is displaying; None if the unit code is unknown."""
+
+
+@dataclass(frozen=True, slots=True)
+class ImpedanceFrame:
+    """Whole-body impedance reading."""
+
+    impedance_ohm: int | None
+    """Impedance in Ω; None if the scale couldn't measure it, e.g. through socks."""
+
+
+def _checksum(data: Iterable[int]) -> int:
+    return reduce(xor, data, 0)
+
+
+def encode_command(frame_type: FrameType, data: bytes = b"") -> bytes:
+    """Build a client-to-scale command frame."""
+    body = (len(data) + 4, PRODUCT_ID, frame_type, *data)
+    return bytes((HEADER_CLIENT, *body, _checksum(body), TRAILER))
+
+
+def unit_command(unit: DisplayUnit) -> bytes:
+    """Build the command that sets the scale's display unit."""
+    return encode_command(FrameType.UNIT, bytes((unit,)))
+
+
+def start_commands(
+    *, weight_only: bool = False, display_unit: DisplayUnit | None = None
+) -> Iterator[bytes]:
+    """Yield the commands sent at the start of a weigh-in.
+
+    The scale starts the weigh-in by itself when it wakes; these set it up.
+
+    The mode command, then the hello command, then the unit command if
+    ``display_unit`` is given.
+    """
+    mode = MODE_WEIGHT_ONLY if weight_only else MODE_NORMAL
+    yield encode_command(FrameType.MODE, bytes((mode,)))
+    yield encode_command(FrameType.HELLO)
+    if display_unit is not None:
+        yield unit_command(display_unit)
+
+
+ACK_STABLE_WEIGHT = encode_command(FrameType.WEIGHT, bytes((STABLE_FLAG,)))
+ACK_IMPEDANCE = encode_command(FrameType.IMPEDANCE, b"\x00")
+
+
+def _is_valid(frame: bytes) -> bool:
+    if not (
+        len(frame) >= MIN_FRAME_LENGTH
+        and frame[0] == HEADER_SCALE
+        and frame[1] == len(frame) - 2
+        and frame[2] == PRODUCT_ID
+        and frame[-1] == TRAILER
+        and _checksum(frame[1:-2]) == frame[-2]
+    ):
+        return False
+    expected = FRAME_LENGTHS.get(frame[3])
+    if expected is not None and len(frame) != expected:
+        _LOGGER.debug(
+            "%s frame has wrong length: %s",
+            FrameType(frame[3]).name.capitalize(),
+            frame.hex(" "),
+        )
+        return False
+    return True
+
+
+def _decode_weight(frame: bytes) -> WeightFrame:
+    raw = int.from_bytes(frame[8:10], "big")
+    try:
+        display_unit: DisplayUnit | None = DisplayUnit(frame[7] - UNIT_BASE)
+    except ValueError:
+        display_unit = None
+    return WeightFrame(
+        weight_kg=raw / 100,
+        stable=frame[4] == STABLE_FLAG,
+        display_unit=display_unit,
+    )
+
+
+def _decode_impedance(frame: bytes) -> ImpedanceFrame:
+    ohm = int.from_bytes(frame[9:11], "big")
+    match ohm:
+        case ImpedanceCode.FAILED:
+            _LOGGER.debug("Impedance not measured: no contact, e.g. socks")
+        case ImpedanceCode.WEIGHT_ONLY:
+            _LOGGER.debug("Impedance not measured: weight-only mode")
+        case _ if IMPEDANCE_MIN_OHM <= ohm <= IMPEDANCE_MAX_OHM:
+            return ImpedanceFrame(impedance_ohm=ohm)
+        case _:
+            _LOGGER.debug("Impedance out of range: %s Ω", ohm)
+    # Still a valid frame, unlike None, so the session acks it and stops waiting.
+    return ImpedanceFrame(impedance_ohm=None)
+
+
+def decode(frame: bytes) -> WeightFrame | ImpedanceFrame | None:
+    """Decode a scale-to-client frame; return None if invalid or unrecognised."""
+    if not _is_valid(frame):
+        return None
+    match frame[3]:
+        case FrameType.WEIGHT:
+            return _decode_weight(frame)
+        case FrameType.IMPEDANCE:
+            return _decode_impedance(frame)
+    return None

vitafit_ble-0.1.0/src/vitafit_ble/session.py

@@ -0,0 +1,139 @@
+"""Measurement session over an open GATT connection."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+import logging
+from typing import TYPE_CHECKING
+
+from .const import (
+    IMPEDANCE_TIMEOUT,
+    NOTIFY_CHARACTERISTIC_UUID,
+    WEIGHT_TIMEOUT,
+    WRITE_CHARACTERISTIC_UUID,
+)
+from .protocol import (
+    ACK_IMPEDANCE,
+    ACK_STABLE_WEIGHT,
+    ImpedanceFrame,
+    WeightFrame,
+    decode,
+    start_commands,
+)
+
+if TYPE_CHECKING:
+    from bleak import BleakClient
+    from bleak.backends.characteristic import BleakGATTCharacteristic
+
+    from .protocol import DisplayUnit
+
+_LOGGER = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True, slots=True)
+class Measurement:
+    """Result of one weigh-in."""
+
+    weight_kg: float
+    """Stable weight in kg, to 0.01 kg."""
+    impedance_ohm: int | None
+    """Whole-body impedance in Ω.
+
+    None if the scale couldn't measure it, for example through socks, or didn't
+    report it in time, for example when the user stepped off early.
+    """
+    display_unit: DisplayUnit | None
+    """Unit the scale was displaying, from the stable weight frame.
+
+    None if the unit code is unknown.
+
+    ``weight_kg`` is in kg whatever the display unit.
+    """
+
+
+async def _async_next_frame(
+    frames: asyncio.Queue[bytes],
+) -> WeightFrame | ImpedanceFrame | None:
+    data = await frames.get()
+    frame = decode(data)
+    _LOGGER.debug("Received %s: %s", data.hex(" "), frame)
+    return frame
+
+
+async def _async_stable_weight(frames: asyncio.Queue[bytes]) -> WeightFrame:
+    while True:
+        frame = await _async_next_frame(frames)
+        if isinstance(frame, WeightFrame) and frame.stable:
+            return frame
+
+
+async def _async_impedance(frames: asyncio.Queue[bytes]) -> ImpedanceFrame:
+    while True:
+        frame = await _async_next_frame(frames)
+        if isinstance(frame, ImpedanceFrame):
+            return frame
+
+
+async def async_measure(
+    client: BleakClient,
+    *,
+    weight_timeout: float = WEIGHT_TIMEOUT,
+    impedance_timeout: float = IMPEDANCE_TIMEOUT,
+    display_unit: DisplayUnit | None = None,
+    weight_only: bool = False,
+) -> Measurement | None:
+    """Run one weigh-in; return None if no stable weight arrives in time.
+
+    Impedance is None if the scale can't measure it, for example through socks,
+    or doesn't report it in time, for example when the user steps off early.
+
+    With ``display_unit``, set the scale's display unit after the mode and hello
+    commands. Without it, the scale keeps its display unit. The weight is always
+    in kg.
+
+    With ``weight_only``, select the scale's weight-only mode, which passes no
+    current, so impedance is None. Without it, select the normal mode. The
+    scale keeps the mode for later weigh-ins without a connection.
+    """
+    frames: asyncio.Queue[bytes] = asyncio.Queue()
+
+    def _on_notify(_: BleakGATTCharacteristic, data: bytearray) -> None:
+        frames.put_nowait(bytes(data))
+
+    async def _async_write(command: bytes) -> None:
+        _LOGGER.debug("Sending %s", command.hex(" "))
+        await client.write_gatt_char(WRITE_CHARACTERISTIC_UUID, command, response=True)
+
+    await client.start_notify(NOTIFY_CHARACTERISTIC_UUID, _on_notify)
+    for command in start_commands(weight_only=weight_only, display_unit=display_unit):
+        await _async_write(command)
+
+    try:
+        async with asyncio.timeout(weight_timeout):
+            weight = await _async_stable_weight(frames)
+    except TimeoutError:
+        _LOGGER.debug("No stable weight within %s s", weight_timeout)
+        return None
+    else:
+        # openScale says acknowledging the stable weight starts the impedance
+        # measurement. Untested: no normal-mode weigh-in has skipped it.
+        await _async_write(ACK_STABLE_WEIGHT)
+
+    try:
+        async with asyncio.timeout(impedance_timeout):
+            impedance = await _async_impedance(frames)
+    except TimeoutError:
+        _LOGGER.debug(
+            "No impedance within %s s; returning weight only", impedance_timeout
+        )
+        impedance_ohm = None
+    else:
+        await _async_write(ACK_IMPEDANCE)
+        impedance_ohm = impedance.impedance_ohm
+
+    return Measurement(
+        weight_kg=weight.weight_kg,
+        impedance_ohm=impedance_ohm,
+        display_unit=weight.display_unit,
+    )