An open-source Python library for automating XBloom coffee machines via Bluetooth Low Energy.
Disclaimer: This project is not affiliated with, endorsed by, or connected to XBloom in any way. It was created through clean-room reverse engineering for personal automation and interoperability purposes.
- Full Brew Automation - Grind beans, pour water, complete recipes
- Real-Time Monitoring - Weight, temperature, water level, grinder status
- Recipe Support - Multi-pour recipes with temperature, flow rate, and pattern control
- Async API - Modern Python async/await patterns
- Cross-Platform - Works on Linux, macOS, Windows
# Clone the repository
git clone https://github.com/fhenwood/PyBloom.git
cd pybloom
# Install in development mode
pip install -e .- Python 3.9+
- Bluetooth adapter with BLE support
- XBloom Studio coffee machine
import asyncio
from xbloom import XBloomClient
from xbloom.models.types import XBloomRecipe, PourStep, PourPattern, CupType
async def brew_coffee():
recipe = XBloomRecipe(
name="Morning Pour Over",
grind_size=50, # 1-100
rpm=80, # Grinder speed
bean_weight=15.0, # Grams to grind
total_water=24, # 24 * 10 = 240ml
cup_type=CupType.X_DRIPPER,
pours=[
# Bloom
PourStep(
volume=50,
temperature=93,
pausing=30, # 30 second bloom
flow_rate=3.0,
pattern=PourPattern.SPIRAL
),
# Main pour
PourStep(
volume=190,
temperature=93,
pausing=0,
flow_rate=3.5,
pattern=PourPattern.SPIRAL
),
]
)
# Find your device MAC with: xbloom scan
async with XBloomClient(mac_address="XX:XX:XX:XX:XX:XX") as client:
if client.is_connected:
# This handles everything: bypass, cup, recipe, execute
await client.brew(recipe, wait_for_completion=True)
print("โ Enjoy your coffee!")
asyncio.run(brew_coffee())The main client for controlling the machine.
async with XBloomClient(mac_address="XX:XX:XX:XX:XX:XX") as client:
# High-level brewing
await client.brew(recipe) # Full automated brew
await client.brew_without_grinding(recipe) # Skip grinding (pre-ground)
# Low-level control
await client.set_bypass(volume, temp, dose) # Set bypass parameters
await client.set_cup(max_weight, min_weight) # Set cup bounds
await client.send_coffee_recipe(recipe) # Send recipe data
await client.execute_coffee_recipe() # Start execution
# Monitoring
status = client.status # Current device status
status.scale.weight # Current weight (grams)
status.brewer.temperature # Current temperature (ยฐC)
status.grinder.is_running # Grinder active?
status.brewer.is_running # Brewer active?| Parameter | Range | Description |
|---|---|---|
grind_size |
1-100 | Grind fineness (1=finest) |
rpm |
60-100 | Grinder motor speed |
bean_weight |
5-30g | Grams of beans to grind |
total_water |
1-50 | Total water รท 10 (e.g., 24 = 240ml) |
temperature |
80-100ยฐC | Pour temperature |
flow_rate |
1.0-5.0 | Water flow speed |
pausing |
0-255s | Pause after pour (bloom time) |
PourPattern.CENTER # 0 - Center only
PourPattern.CIRCULAR # 1 - Circular motion
PourPattern.SPIRAL # 2 - Spiral outward# Scan for devices
xbloom scan
# Monitor device status
xbloom monitor XX:XX:XX:XX:XX:XXpybloom/
โโโ src/xbloom/
โ โโโ core/client.py # Main XBloomClient
โ โโโ models/
โ โ โโโ types.py # Recipe, PourStep, etc.
โ โ โโโ recipes.py # Recipe payload builder
โ โโโ protocol/
โ โ โโโ constants.py # Command codes
โ โ โโโ packet.py # Packet building
โ โ โโโ parser.py # Response parsing
โ โโโ connection/ # BLE connection handling
โ โโโ components/ # Grinder, Brewer, Scale controllers
โ โโโ bridge.py # MQTT bridge for Home Assistant
โ โโโ cli.py # Command-line interface
โโโ examples/
โ โโโ simple_brew.py # Basic brewing example
โ โโโ simple_grind.py # Grinder control
โ โโโ simple_pour.py # Pour control
โ โโโ simple_weight.py # Scale monitoring
โโโ docs/
โ โโโ PROTOCOL_DOCUMENTATION.md # BLE protocol reference
โ โโโ MQTT_BRIDGE_GUIDE.md # MQTT/Home Assistant setup
โ โโโ YAML_RECIPE_CONFIGURATION.md
โโโ custom_components/ # Home Assistant integration
โโโ .env.example # Environment template
โโโ README.md
A sleek custom Lovelace card for Home Assistant that replicates the XBloom Studio mobile app aesthetic.
- Dark Studio Theme - Matches XBloom's premium design language
- Connection-Aware UI - Controls disable when machine is disconnected
- Auto-Discovery - Automatically finds your XBloom entities
- All Controls - Grind, Brew, Recipe selection, Sliders for all parameters
-
Copy the card to your Home Assistant
wwwfolder:cp custom_components/xbloom_mqtt/www/xbloom-studio-card.js /config/www/
-
Add the resource in Home Assistant:
- Go to Settings โ Dashboards โ โฎ (top right) โ Resources
- Click Add Resource
- URL:
/local/xbloom-studio-card.js - Type: JavaScript Module
-
Add the card to any dashboard:
- Edit dashboard โ Add Card โ Search "XBloom Studio"
- Or add manually with:
type: custom:xbloom-studio-card
-
Apply the theme (optional):
- Copy
examples/themes/xbloom_studio.yamlto/config/themes/ - Go to Settings โ General โ Theme โ XBloom Studio
- Copy
The card provides:
- Connect/Disconnect button
- Grind & Brew action buttons
- Sliders for Grind Size, RPM, Temperature, Volume
- Recipe selector with Pour button
- Sensor readouts (Weight, Status, Error)
- Cancel button for emergency stop
- Protocol Documentation - Complete BLE protocol reference
- MQTT Bridge Guide - Home Assistant integration
- YAML Recipe Configuration - Recipe setup
-
Disconnect Cleanup: By default, disconnecting sends abort commands. Set
client._cleanup_on_disconnect = Falseto let brews continue after script exit. -
Timing: Commands need ~1 second delay between them for reliable operation.
-
Bean Detection: The machine will prompt for more beans if the hopper is empty.
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Submit a pull request
MIT License - see LICENSE file.
- Protocol documentation created through BLE traffic analysis and clean-room reverse engineering
- Inspired by the need for home automation integration
- Thanks to the open-source community for BLE tools like Bleak
Made with โ by coffee enthusiasts, for coffee enthusiasts.