puffco-py 💨

A Python library and CLI for Puffco Peak Pro and Puffco Proxy smart vaporizers over Bluetooth Low Energy (BLE).

Stream live bowl temperatures and battery levels, control heating sessions and profiles, and build custom desktop widgets, home automations, or web apps.

🌐 Website & Live Docs: puffco-py.soymilkisok.com

Features

• Real-Time Telemetry: Stream bowl temperature (~16 FPS active / 250ms idle), battery %, chamber status, and session countdowns.
• Session Control: Start/stop heat cycles, trigger boosts, switch profiles, and tweak target temperatures.
• Async & Thread-Safe: Built on asyncio (bleak), with a ThreadedPuffcoClient bridge for desktop GUIs (Tkinter, PyQt, rumps) and sync scripts.
• Auto-Discovery: Automatically find and connect to nearby Puffco hardware.
• Built-in CLI: Terminal commands for monitoring, scanning, and heat control right out of the box.

Installation

pip install puffco-py

For the terminal dashboard and desktop GUI extras:

pip install "puffco-py[cli,gui]"

Quickstart

import asyncio
from puffco_py import PuffcoClient


async def main():
    async with PuffcoClient() as client:
        print(f"Connected to {client.telemetry.device_name} ({client.telemetry.chamber_name})")

        # Stream real-time telemetry updates
        def on_update(telemetry):
            print(f"\rTemp: {telemetry.live_temp_f:.1f}°F | State: {telemetry.state_name}", end="")

        client.add_telemetry_listener(on_update)
        await client.start_telemetry_stream()

        # Stream for 15 seconds
        await asyncio.sleep(15)


asyncio.run(main())

Building a desktop GUI or synchronous script? Use ThreadedPuffcoClient so you don't have to juggle asyncio event loops. See examples/03_threaded_gui.py.

Command-Line Interface (CLI)

puffco-py installs a standalone terminal tool:

# Scan for nearby devices and signal strength
puffco-py scan

# Stream a live terminal telemetry dashboard
puffco-py monitor

# View hardware serial, firmware version, and heat profiles
puffco-py info

# Trigger or abort heat sessions
puffco-py sesh start
puffco-py sesh boost
puffco-py sesh stop

Examples & Integrations

The examples/ directory contains standalone, runnable scripts:

• Live Telemetry: Minimal quickstart streaming temperature and battery.
• Session Control: Switching profile slots and heat settings.
• Threaded GUI Worker: Background BLE worker pattern for PyQt, Tkinter, or PySide.
• macOS Menu Bar Widget: Native status bar monitor and remote control (rumps).
• Home Assistant MQTT Bridge: Auto-discovery for smart home sensors and switches.
• FastAPI & WebSocket Server: REST API and live WebSocket server for web apps.

See examples/README.md for full descriptions and setup steps.

Documentation

Detailed documentation is available in docs/ and on the web:

• Website & Live Docs — Interactive web documentation and guides.
• Python API Reference — Full reference for PuffcoClient, ThreadedPuffcoClient, and PuffcoTelemetry.
• Hardware & Platform Troubleshooting — Bluetooth permissions (macOS, Linux BlueZ, Windows) and connection tips.
• Lorax BLE Protocol Specification — Handshake flow, authentication challenge-response, UUIDs, and VFS endpoints.

Running Tests

Run the offline unit test suite:

python3 -m unittest discover tests/

Contributing

Contributions, bug reports, and hardware dumps are warmly welcomed! Please read our Contributing Guide and Code of Conduct before submitting pull requests.

Check out the Changelog for release notes and version history.

Credits & Acknowledgments

puffco-py builds upon foundational protocol research and reverse-engineering from the community:

• Fr0st3h / PuffcoBLE: Early BLE exploration and Lorax path research.
• PuffcoPC by meekzyr: Original Puffco Bluetooth communication and pairing work.
• home-assistant-puffco: Home Assistant integration documenting Lorax paths.
• Bleak: Asynchronous BLE library for Python.

License

This project is licensed under the MIT License.

Legal Disclaimer

puffco-py is an independent, community-developed open-source reverse-engineering project. It is NOT affiliated with, authorized, maintained, sponsored, or endorsed by Puff Corp. or any of its affiliates. Puffco, Peak, Peak Pro, Proxy, 3D Chamber, and 3DXL are registered trademarks of Puff Corp. Nominative use of these names is strictly for identification and interoperability purposes under Fair Use.