pytboss

Python 3 library for interacting with Pitboss grills and smokers.

Note that this project has no official relationship with Pitboss or Danson's. Use at your own risk.

Usage

pytboss supports three ways of talking to a grill: a direct Bluetooth LE connection, a WebSocket connection to the PitBoss cloud service, or an HTTP connection to the grill on your own network. All three use the same PitBoss API once connected — only the Transport passed to it differs.

Bluetooth LE

If you don't already know your grill's Bluetooth address, you can discover nearby devices with bleak:

import asyncio
from bleak import BleakScanner


async def discover():
    devices = await BleakScanner.discover()
    for device in devices:
        print(device.address, device.name)


asyncio.run(discover())

Once you have the address, connect and subscribe to state updates:

import asyncio
from bleak import BleakScanner
from pytboss import BleConnection, PitBoss


async def state_callback(data):
    print(data)


async def main():
    device_address = "AA:BB:CC:DD:EE:FF"  # Your grill's Bluetooth address.
    ble_device = await BleakScanner.find_device_by_address(device_address)
    model = "PBV4PS2"  # Or your model. See below.
    boss = PitBoss(BleConnection(ble_device), model)
    # Subscribe to updates from the smoker.
    await boss.subscribe_state(state_callback)
    await boss.start()
    while True:
        await asyncio.sleep(0.1)


asyncio.run(main())

WebSocket

The WebSocket transport talks to the PitBoss cloud service instead of connecting directly over Bluetooth, which is useful when the grill isn't in Bluetooth range. It requires the grill's unique identifier (grill_id), which you can find in the PitBoss mobile app or account settings; this library does not currently provide a way to look it up.

import asyncio
from pytboss import PitBoss, WebSocketConnection


async def state_callback(data):
    print(data)


async def main():
    grill_id = "your-grill-id"
    model = "PBV4PS2"  # Or your model. See below.
    boss = PitBoss(WebSocketConnection(grill_id), model)
    await boss.subscribe_state(state_callback)
    await boss.start()
    while True:
        await asyncio.sleep(0.1)


asyncio.run(main())

HTTP (local network)

Mongoose OS serves the same RPC interface at http://<grill-ip>/rpc that the Dansons relay forwards, so this transport talks to the grill directly, with the vendor's cloud out of the path.

Not every grill answers. The ESP-IDF firmware line (versioned 16.x, on the PBC2, PBD, PBE, PBL2 and PBT boards) links no HTTP server at all, and Mongoose grills serve the endpoint only when http.enable is set — per-unit configuration that no model or firmware version predicts. Nothing in this library turns it on; connect() simply fails. Check first over a transport that already works:

from pytboss.exceptions import RPCError

try:
    http = await boss.config.get_config("http")
except RPCError:
    http = {}  # No such section: not a Mongoose grill.
if http.get("enable"):
    ...  # An HttpConnection will work against this grill.

There is no push channel. HTTP is strictly request/response, so unlike the other two transports this one never invokes the state or VData callbacks — subscribe_state() registers a callback that will not fire. Poll get_state() instead; it issues a live RPC and updates the same cache the rest of the API reads.

import asyncio
from pytboss import HttpConnection, PitBoss


async def main():
    host = "192.168.1.50"  # Your grill's address on the network.
    model = "PBV4PS2"  # Or your model. See below.
    boss = PitBoss(HttpConnection(host), model)
    await boss.start()
    while True:
        print(await boss.get_state())
        await asyncio.sleep(10)


asyncio.run(main())

Error handling

Calls to the grill can fail for a number of reasons — the grill may be unreachable, the connection may drop, or an RPC may be rejected. These are all raised as subclasses of pytboss.exceptions.Error:

from pytboss.exceptions import Error, GrillUnavailable, InvalidGrill, NotConnectedError

try:
    boss = PitBoss(WebSocketConnection(grill_id), model)
    await boss.start()
except InvalidGrill:
    print(f"Unknown grill model: {model}")
except GrillUnavailable:
    print("Could not reach the grill.")
except NotConnectedError:
    print("Not connected to the grill.")
except Error as ex:
    print(f"Unexpected error: {ex}")

Installation

pytboss requires Python 3.12 or later.

Pip

To install pytboss, run this command in your terminal:

$ pip install pytboss

Source code

Pytboss is actively developed on Github, where the code is always available.

You can either clone the public repository:

$ git clone https://github.com/dknowles2/pytboss

Or download the latest tarball:

$ curl -OL https://github.com/dknowles2/pytboss/tarball/main

Once you have a copy of the source, you can embed it in your own Python package, or install it into your site-packages easily:

$ cd pytboss
$ python -m pip install .

Supported Models

The following models should be supported. Note however that only the PBV4PS2 model has been tested.

Development

To work on pytboss itself, install uv and sync the test dependencies (uv manages the Python 3.12+ interpreter and virtual environment for you):

$ uv sync --group test

Run the test suite, linter, and type checker:

$ uv run pytest
$ uv run ruff check .
$ uv run mypy .

pre-commit hooks are also available; sync the dev group and install them with:

$ uv sync --group dev
$ uv run pre-commit install

Metadata

Release files for pytboss 2026.8.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytboss 2026.8.6
File	Size	Uploaded	Provenance
pytboss-2026.8.6.tar.gz	159.9 kB	Aug 7, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pytboss 2026.8.6
File	Interpreter	ABI	Platform	Reset
pytboss-2026.8.6-py3-none-any.whl 69.6 kB Aug 7, 2026 Without provenance	Python 3	none	any	Details

Total release size: 229.5 kB

Release files / pytboss-2026.8.6.tar.gz

Download URL	pytboss-2026.8.6.tar.gz
Size	159.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`ed7f6948a955b52d8a096b15e68b8b5444d0af786044c463d2cb49ca821a15ce`
BLAKE2b-256 checksum How to use checksums	`45f338c45ae35dd1c1acab33181bf101480041525a05be0db3e996e1672033c8`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Release files / pytboss-2026.8.6-py3-none-any.whl

Download URL	pytboss-2026.8.6-py3-none-any.whl
Size	69.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b99aae26ba1408e89f3e086473752bdf2ac53d88fdb2e9f59143cb0c32b6b05d`
BLAKE2b-256 checksum How to use checksums	`bc523a80b9366fce9aab839c8cb7aea30037096a10979af4148f6138495b4fda`
Upload date	Aug 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.6`

Security for pytboss 2026.8.6

Report project as malware

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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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.