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.6.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.6.0
File Size Uploaded Provenance Actions
xbloom_py-0.6.0.tar.gz 73.0 kB With provenance Details for xbloom_py-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 149.0 kB

Release files / xbloom_py-0.6.0.tar.gz

Download URL xbloom_py-0.6.0.tar.gz
Size 73.0 kB
Tags Source
SHA-256 checksum
How to use checksums
cbd53c78cf765cc7b1d2ae5b08488d5deb13f6c9e9fe1e51998b3a3a87b8c7f8
BLAKE2b-256 checksum
How to use checksums
2fe4ca59f1266fe7641acea6b3a13aed810d2abf5568d0ec851ed6f547c5ae00
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 19, 2026.

Transparency log

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

Download URL xbloom_py-0.6.0-py3-none-any.whl
Size 76.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2ca3ba739fea2320df495fc047297560cd65e3c0b0ae3f3612d3c071dd80c8ca
BLAKE2b-256 checksum
How to use checksums
a192a8b4c827b2b44c832b4937db496e76437de95643ed2e70ea10190df8ef50
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 19, 2026.

Transparency log

Security for xbloom-py 0.6.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.6.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 19, 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