Documentation

Introduction

puffco-py is a standalone, lightweight, asynchronous Python library for communicating with Puffco Peak Pro (V1, V2, Limited Editions) and Puffco Proxy vaporizers using Bluetooth Low Energy (BLE).

Modern Puffco devices use a proprietary firmware protocol called the Lorax Virtual File System (VFS). Rather than using fixed GATT characteristics for every sensor, Puffco multiplexes virtual file paths over a single write/notify characteristic pair. puffco-py implements this protocol natively, providing:

• Low latency streaming — Adaptive polling at up to ~16 FPS (60ms) during active heating sessions.
• Cryptographic authentication — Automatically solves the SHA-256 access seed challenge required by modern firmware.
• Desktop GUI friendly — Dedicated background-worker thread client (ThreadedPuffcoClient) for Tkinter, PyQt, and macOS status bar widgets.
• Hardware telemetry — Live bowl temperature, battery %, charging status, chamber detection (3D, 3DXL, Proxy), and lifetime dab counter.

Installation

Requires Python 3.9 or higher. Install from PyPI or build from source.

Standard Install (PyPI)

pip install puffco-py

Optional Extras

Include CLI formatting and macOS menu bar widget dependencies:

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

From Source

git clone https://github.com/SoyMilkIsOk/puffco-py.git
cd puffco-py
pip install -e .

Hardware & Platform Support

Async Python Quickstart

PuffcoClient is an async context manager powered by asyncio and bleak. It auto-discovers the nearest device, authenticates, and starts telemetry.

import asyncio
from puffco_py import PuffcoClient

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

        def on_telemetry(t):
            print(f"\rTemp: {t.live_temp_f:.1f}°F | State: {t.state_name}", end="")

        client.add_telemetry_listener(on_telemetry)
        await client.start_telemetry_stream()
        await asyncio.sleep(15)

asyncio.run(main())

Threaded / GUI Quickstart

For desktop GUIs (Tkinter, PyQt, PySide) or synchronous scripts, use ThreadedPuffcoClient. It runs the async BLE event loop on a background thread and exposes simple synchronous methods:

import time
from puffco_py import ThreadedPuffcoClient

client = ThreadedPuffcoClient()
client.add_telemetry_listener(lambda t: print(f"Live Temp: {t.live_temp_f:.1f}°F"))

client.start()

if client.wait_connected(timeout=10.0):
    print(client.telemetry.summary())

    client.set_profile(slot=1)
    client.start_session()
    time.sleep(10)
    client.boost()
    time.sleep(10)
    client.stop_session()

client.stop()

CLI Commands

The package includes an out-of-the-box CLI utility named puffco-py:

macOS Menu Bar Widget

A native macOS status bar app is provided in examples/04_mac_menu_widget.py (powered by rumps):

pip install "puffco-py[gui]"
python3 examples/04_mac_menu_widget.py

The widget displays live bowl temperature in your menu bar and provides one-click dropdown actions to start, boost, or abort sessions.

Features

• Lorax VFS Protocol — Native support for Puffco firmware using Lorax Virtual File System sequence multiplexing and SHA-256 challenge-response authentication.
• Sub-100ms Streaming — Adaptive polling engine streams ~16 FPS (60ms) during active heating and throttles to 250ms when idle.
• Thread-Safe & GUI Ready — ThreadedPuffcoClient for synchronous UI toolkits (Tkinter, PyQt, PySide) without blocking dispatch threads.
• macOS Status Bar Widget — Ready-to-run native menu bar app powered by rumps, showing live temps and one-click session triggers.
• Auto-Discovery — Scans BLE advertisements and filters nearest devices by manufacturer OUI and Lorax GATT UUIDs.
• Full Session Control — Start sessions, abort, trigger heat boosts, change profiles, set temperatures, and toggle stealth mode.

Python API Reference

PuffcoClient Methods

Telemetry Model

Accessible via client.telemetry:

Lorax VFS Protocol

Puffco firmware implements a sequence-multiplexed file system over BLE:

VFS Paths

• /p/app/stat/id — Operating state byte (0=Idle, 1=Preheat, 2=Sesh, 3=Fade)
• /p/app/htr/temp — Chamber temperature sensor reading
• /p/app/mc — Mode control (0x07=Start, 0x08=Stop, 0x09=Boost)
• /p/bat/soc — Battery state of charge percentage
• /p/app/odom/0/nc — Lifetime completed dabs counter

Authentication Flow

1. GATT Connection — Bleak discovers device via Lorax service UUID and establishes an MTU-negotiated link.
2. Seed Challenge — Client sends opcode 0x00 (GET_ACCESS_SEED) to request a 16-byte random seed.
3. SHA-256 Auth — Client computes SHA256(MasterKey + Seed)[:16] and sends opcode 0x01 (UNLOCK_ACCESS).
4. Stream Telemetry — Client polls VFS paths for live temperature, state, and battery level.

Platform Troubleshooting & Gotchas

1. The Single-Central Rule (Exclusive Connection)

Puffco hardware only supports one active BLE connection at a time. If the official Puffco iOS/Android app or Puffco Web App (Chrome) is running in the background on your phone, the device will reject connection attempts from puffco-py.

Solution: Completely force-close the mobile app and close any active Web Bluetooth browser tabs before running your Python scripts or CLI commands.

2. Linux & Raspberry Pi (BlueZ Permissions)

The Linux kernel restricts raw BLE socket creation to root by default. If device scanning returns zero results or throws PermissionDenied:

sudo setcap 'cap_net_raw,cap_net_admin+eip' $(readlink -f $(which python3))
sudo systemctl status bluetooth

3. macOS Bluetooth Permissions

On macOS Ventura, Sonoma, and Sequoia, terminal applications require explicit authorization under TCC privacy controls. Go to System Settings > Privacy & Security > Bluetooth and ensure your terminal app (Terminal, iTerm2, or VS Code) is toggled ON.

4. Windows 10 / 11 Bluetooth Pairing

The Windows WinRT BLE stack requires the Puffco Peak Pro to be paired in Windows Settings before third-party applications can enumerate GATT services. Open Settings > Bluetooth & devices > Add device, put your Peak Pro into pairing mode, and pair it once in Windows.

5. Running Offline Tests

pytest tests/ -v   # or: python3 -m unittest discover tests/