Skip to content
fhenwoodPublic

About

No description, website, or topics provided.

Resources

Stars

30 stars

Watchers

3 watching

Forks

Latest commit

ย 

History

5 Commits

Folders and files

Repository files navigation

PyBloom ๐ŸŒธโ˜•

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.

โœจ Features

  • 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

๐Ÿ“ฆ Installation

# Clone the repository
git clone https://github.com/fhenwood/PyBloom.git
cd pybloom

# Install in development mode
pip install -e .

Requirements

  • Python 3.9+
  • Bluetooth adapter with BLE support
  • XBloom Studio coffee machine

๐Ÿš€ Quick Start

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())

๐Ÿ“– API Reference

XBloomClient

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?

Recipe Parameters

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)

Pour Patterns

PourPattern.CENTER   # 0 - Center only
PourPattern.CIRCULAR # 1 - Circular motion
PourPattern.SPIRAL   # 2 - Spiral outward

๐Ÿ”ง CLI Usage

# Scan for devices
xbloom scan

# Monitor device status
xbloom monitor XX:XX:XX:XX:XX:XX

๐Ÿ“ Project Structure

pybloom/
โ”œโ”€โ”€ 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

๐ŸŽจ XBloom Studio Dashboard Card

A sleek custom Lovelace card for Home Assistant that replicates the XBloom Studio mobile app aesthetic.

Features

  • 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

Installation

  1. Copy the card to your Home Assistant www folder:

    cp custom_components/xbloom_mqtt/www/xbloom-studio-card.js /config/www/
  2. 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
  3. Add the card to any dashboard:

    • Edit dashboard โ†’ Add Card โ†’ Search "XBloom Studio"
    • Or add manually with:
      type: custom:xbloom-studio-card
  4. Apply the theme (optional):

    • Copy examples/themes/xbloom_studio.yaml to /config/themes/
    • Go to Settings โ†’ General โ†’ Theme โ†’ XBloom Studio

Screenshot

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

๐Ÿ“š Documentation

โš ๏ธ Important Notes

  1. Disconnect Cleanup: By default, disconnecting sends abort commands. Set client._cleanup_on_disconnect = False to let brews continue after script exit.

  2. Timing: Commands need ~1 second delay between them for reliable operation.

  3. Bean Detection: The machine will prompt for more beans if the hopper is empty.

๐Ÿค Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Submit a pull request

๐Ÿ“„ License

MIT License - see LICENSE file.

๐Ÿ™ Acknowledgments

  • 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.

About

No description, website, or topics provided.

Resources

Stars

30 stars

Watchers

3 watching

Forks

Releases

Packages

Used by

Contributors

Languages