Skip to main content

xbloom-py

Async Python library for xBloom Studio coffee brewers: the BLE protocol, recipe validation, over-the-air firmware updates, the optional cloud account API, and the community recipe hub.

Unofficial, and not affiliated with or endorsed by xBloom. See Disclaimer.

Install

pip install xbloom-py            # pure-python core: spec, recipes, validation
pip install "xbloom-py[ble]"     # + local Bluetooth control
pip install "xbloom-py[cloud]"   # + cloud account, recipe sync, firmware check, community hub
pip install "xbloom-py[all]"     # everything

Import as xbloom:

from xbloom import spec, recipe_validate

Dependencies are declared with lower bounds only and no upper pins, so the package drops into an environment that already pins these without fighting it.

What is in it

Module Needs What it does
spec — Machine constants: ranges, enums, pattern and unit maps. The single source of truth.
recipe_validate — Validate and normalise recipe dictionaries.
brew_scale — Scale a recipe's dose and water.
models — Recipe and reading dataclasses.
exceptions — XBloomError, XBloomAPIError.
ble [ble] at runtime Frame encoding/decoding, ACK-gated send/confirm, packet builders.
ota [ble] at runtime Validated, arm-gated firmware flashing. Read Firmware updates first.
mode_listener [ble] at runtime Live knob and scale event stream.
client [cloud] Share-link recipe fetching.
cloud [cloud] Account login, recipe CRUD, the app's Trending, For You and Tea recipes, firmware version check.
community [cloud] at runtime Search and read the community recipe hub, without signing in.

ble, ota and mode_listener import their Bluetooth dependencies lazily, so they can be imported for packet construction with no extras installed.

Development

uv sync --all-extras
uv run pytest

The suite runs without extras too; test_cloud.py is skipped when aiohttp and cryptography are absent.

Firmware updates

Read this before you use ota. Firmware flashing is the one thing in this library that can permanently damage your machine. Use it only if you accept that.

ota verifies the update's MD5 before anything is sent, and every block is acknowledged by the machine as it is written. That makes a bad flash unlikely — it does not make it impossible. Bluetooth is a wireless link, and a wireless link can drop. If it drops in the middle of a firmware write, the machine can be left unbootable, with no way to recover it over BLE.

If you choose to use it:

  • Keep the machine powered and close to the Bluetooth adapter for the whole flash.
  • Never start a flash during a brew.
  • Don't kill the process, or let the host sleep, while one is running.

You do this entirely at your own risk. This is unofficial software talking to an undocumented protocol that was worked out by inspection, and it is not endorsed by or connected to xBloom in any way. The authors and contributors accept no responsibility and no liability for any damage to your machine, loss of warranty, or any other loss arising from using this library — the firmware updater above all. If that isn't a risk you want to take, don't import ota; everything else works without it.

Disclaimer

This is an independent, community project. It is not affiliated with, authorized, or endorsed by xBloom. "xBloom" is used only to say which machine this talks to. It communicates with the machine over its local BLE protocol, worked out for interoperability, which may change at any time with a firmware update and break this library without warning.

The software is provided as is, without warranty of any kind, express or implied. You use it at your own risk, and the authors and contributors are not liable for any damage, loss, or injury resulting from its use. See the Firmware updates section for the risk that matters most.

License

MIT

Metadata

Release files for xbloom-py 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xbloom-py 0.5.0
File Size Uploaded Provenance Actions
xbloom_py-0.5.0.tar.gz 72.1 kB With provenance Details for xbloom_py-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xbloom-py 0.5.0
File Interpreter ABI Platform Actions
xbloom_py-0.5.0-py3-none-any.whl Python 3 none any Details for xbloom_py-0.5.0-py3-none-any.whl

Total release size: 147.8 kB

Release files / xbloom_py-0.5.0.tar.gz

Download URL xbloom_py-0.5.0.tar.gz
Size 72.1 kB
Tags Source
SHA-256 checksum
How to use checksums
643d8f4a0ee8d3bb59fbf923276d039bd691371005c3f149cd4df7a8a46f2cd2
BLAKE2b-256 checksum
How to use checksums
e525320b57ebae29b11578cfbb891ad78def137a608eea499c0873c9c505e834
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / xbloom_py-0.5.0-py3-none-any.whl

Download URL xbloom_py-0.5.0-py3-none-any.whl
Size 75.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
79bd38d9bc279434565d572a08617947d06e2dc7225988e68312d70ac3e1c8a1
BLAKE2b-256 checksum
How to use checksums
69155599608fc2c62c879fd0f085f5f9197bd14a13124137c6269315d96aeacb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for xbloom-py 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xbloom_py-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page