fellow-stagg-ble

Async Python library for the Fellow Stagg EKG+ electric kettle over Bluetooth LE, built on bleak and bleak-retry-connector.

It keeps one connection to the kettle open, decodes the state the kettle streams (power, target and current temperature, unit, hold, auto-off countdown, on/off base) into immutable KettleState snapshots, and sends power and temperature commands. Reconnecting, scanning and scheduling are left to the caller, so the library fits a Home Assistant coordinator as well as a script.

Installation

pip install fellow-stagg-ble

Requires Python 3.12 or newer.

Usage

import asyncio

from bleak import BleakScanner

from fellow_stagg_ble import FellowStaggKettle, KettleState, TemperatureUnit


def on_state(state: KettleState) -> None:
    print(f"{state.current_temperature} -> {state.target_temperature} °{state.unit}")


def on_disconnect() -> None:
    print("connection lost")


async def main() -> None:
    device = await BleakScanner.find_device_by_address("AA:BB:CC:DD:EE:FF")
    if device is None:
        raise SystemExit("kettle not found; lift it or press a button so it advertises")

    kettle = FellowStaggKettle(device, state_callback=on_state, disconnected_callback=on_disconnect)
    await kettle.connect()  # returns once power, target and current temperature have arrived
    print(kettle.state)

    await kettle.set_target_temperature(195, TemperatureUnit.FAHRENHEIT)
    await kettle.set_power(True)

    unsubscribe = kettle.register_callback(lambda s: print("hold:", s.hold))
    await asyncio.sleep(30)
    unsubscribe()

    await kettle.disconnect()


asyncio.run(main())

API

Callbacks fire only when the state changed. Exceptions raised by callbacks are logged and swallowed. Loss of an established connection is reported exactly once through disconnected_callback, whether bleak noticed it or a failed write did; a failed write also raises FellowStaggCommandError and drops the connection. Commands never connect on their own.

KettleState.complete is true once power, target temperature and unit are known; current_temperature is None both before the first reading and while the kettle reports none (off or lifted), so it is not part of the check. connect() itself waits for an actual current-temperature frame.

Exceptions: FellowStaggError is the base of FellowStaggConnectionError, FellowStaggNotSupportedError (characteristic missing), FellowStaggCommandError and FellowStaggTimeoutError.

Protocol

The pure protocol helpers live in fellow_stagg_ble.protocol (split_frames, parse_frame, build_command) and have no Bluetooth dependency.

Limitations

• The kettle accepts a single central at a time. While the Fellow app is connected, other clients cannot connect.
• The kettle stops advertising roughly three minutes after it was last used. It still accepts a connection if the caller has a cached BLEDevice, but a fresh scan will not find it until it is lifted or a button is pressed.
• A power cycle resets the setpoint to 212 °F.
• A second disconnect about 27 s after the kettle is powered up has been observed; callers should expect to reconnect.
• Writes are spaced at least 0.2 s apart.

Development

uv sync --all-groups
uv run pytest --cov=fellow_stagg_ble --cov-report=term-missing
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv build

Tests run against a fake BleakClient; no hardware is needed.

Releasing

1. Bump version in pyproject.toml and __version__ in src/fellow_stagg_ble/__init__.py, move the CHANGELOG.md entry out of unreleased, commit.
2. Tag vX.Y.Z and push the tag. The publish workflow builds the sdist and wheel, uploads them to PyPI through Trusted Publishing and creates a GitHub Release with the files attached.

Trusted Publishing for the pypi environment of this repository is pending setup on PyPI.

Attribution and license

MIT, see LICENSE. The command frame format and init sequence descend from Levi McCallum's MIT-licensed stagg-ekg-plus-ha integration. The Home Assistant integration that consumes this library lives at ADobin/stagg-ekg-plus-ha.