KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

ha-pitboss

★ 62 Open GitHub ↗

Home Assistant Custom Integration for PitBoss smokers and grills

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# PitBoss

[![GitHub Release][releases-shield]][releases]
[![GitHub Activity][commits-shield]][commits]
[![License][license-shield]](https://raw.githubusercontent.com/dknowles2/ha-pitboss/main/LICENSE)

[![hacs][hacsbadge]][hacs]
![Project Maintenance][maintenance-shield]

A Home Assistant custom integration to interact with [PitBoss grills and smokers][pitboss].

> **WARNING: THIS INTEGRATION IS STILL UNDER ACTIVE DEVELOPMENT AND MAY NOT YET WORK PROPERLY.**
>
> **USE AT YOUR OWN RISK**

Supported models can be found at https://github.com/dknowles2/pytboss#supported-models.
See [`docs/SUPPORTED_GRILLS.md`](docs/SUPPORTED_GRILLS.md) for a per-model breakdown of
which features (lights, meat probes, primer motor, recipe mode) each grill supports in
this integration. That file is auto-generated and kept in sync whenever the `pytboss`
dependency is updated.

## Features

- **No account, no app.** The integration talks to the grill itself. It never signs in to a PitBoss account and never uses the vendor's mobile app.
- **Automatic discovery.** Power on your grill and it's discovered automatically over Bluetooth; manual setup by device ID is also supported.
- **Three connection protocols.** Bluetooth (`ble`), the vendor's relay (`wss`, the default), or a direct local connection (`local`) for grills that support it — chosen at setup and changeable later via reconfigure. See [Connection protocols](#connection-protocols); they are not equivalent.
- **Reconfigurable, and it asks rather than gives up.** Change the model, password, or protocol without deleting the integration. If the grill starts rejecting the password, the integration asks you to re-enter it instead of retrying forever.
- **Adapts to your grill.** The light, primer motor, recipe sensors, probe count, probe naming, and per-probe targets are all created from what your model and control board declare — not assumed.
- **Polls faster when it matters.** Updates arrive quickly while the grill is running and back off in standby.
- **Safety first, remote start off by default.** Out of the box the integration cannot light the grill: the power switch and climate card only ever turn it off. A deliberate opt-in in the integration options enables the `pitboss.start_grill` action -- and only that action; the switch and climate card refuse either way.

### Connection protocols

| | Reaches the grill via | Needs internet |
| --- | --- | --- |
| `ble` | Bluetooth, directly | No |
| `wss` (default) | `socket.dansonscorp.com`, the vendor's relay | **Yes** |
| `local` | HTTP on your own network, directly | No |

**`wss` is not a local connection.** Despite being described as "WiFi", it connects outbound to Dansons' servers, which relay to your grill. It is the default because it is the more reliable of the two — Bluetooth range and adapter quirks cause most connection problems — but if you want no cloud in the path, choose `ble`.

**`local` is the genuinely local option, but not every grill has it.** It talks to the RPC interface the grill's own firmware serves on your network — no cloud in the path and no Bluetooth range to fight. The ESP-IDF firmware line (versioned `16.x`) serves no HTTP endpoint at all, and the others serve it only when `http.enable` is set on the unit; nothing here can turn it on. The setup form checks by connecting: if no grill answers at the address you give, it says so rather than creating a broken entry.

**This integration will set up the following platforms:**

| Platform | Description |
| --- | --- |
| `binary_sensor` | Error flags, live fan/igniter/auger state, connectivity, per-probe "target reached", and whether the grill has a meat probe control port |
| `button` | Restart the controller; request fast updates |
| `climate` | Grill temperature and HVAC action; turn off only (safety) |
| `light` | The grill's built-in light, if the model has one |
| `number` | A target temperature for every probe the grill supports, and an optional grill setpoint |
| `select` | The temperature unit the grill itself displays |
| `sensor` | Probe temperatures, recipe progress, firmware version, controller uptime and free memory, and an optional grill temperature |
| `switch` | Grill module power (turn off only) and the primer motor |

### Entity details

- **Climate (`Grill temperature`):** Current and target temperature, plus HVAC action. Target temperatures snap to the values the control board actually accepts — the board silently ignores anything else. Setting HVAC mode to `off` turns the grill off and leaves the setpoint alone.
- **Sensor (`MPC`/`P2`–`P4`, or `Probe 1`–`Probe 4`):** Probe temperatures in the grill's current unit. On grills with a meat probe control port, probe 1 is labelled `MPC` to match what is printed by the socket; other grills keep numbered names. Only as many probes as the grill has are enabled.
- **Number (`… target`):** A target for every probe the board supports, not just the first two. Targets can be set while the probe is unplugged and while the grill is off — they are held and sent when the grill comes on.
- **Sensor (`Smoker temperature`), disabled by default:** A smoke-box reading, on the 111 of 137 models whose control board reports one — it is a field of its own on the wire, not a second name for the grill temperature. Off by default because what it reads on any particular grill has not been checked against hardware: a combo model with a separate smoke box is not the same appliance as a pellet grill that merely decodes the field. Grills whose board never reports it get no entity at all.
- **Sensor (`Chamber temperature`) and number (`Chamber setpoint`), both disabled by default:** The same reading and the same control the climate entity offers, in a shape you can override the unit on. Home Assistant resolves a per-entity unit for `sensor` and `number` entities but not for `climate` ones, so if you want the grill in °F while the rest of your Home Assistant is in °C — or the other way round — enable these two and set the unit under each entity's own settings. The climate entity stays whatever you do: it is what voice assistants control and what reports HVAC action. Both controls write through the same place, so moving one moves the other straight away.
- **Binary sensor (`… target reached`):** One per probe, comparing the probe against its target.
- **Binary sensor (`Connectivity`):** Stays available so it can report *disconnected*, rather than vanishing along with everything else.
- **Binary sensor (`Meat probe control`):** Whether the grill has a control port at all.
- **Binary sensor (errors and state):** Probe, startup, high-temperature, fan, igniter, auger and no-pellets errors, plus live fan, igniter and auger state.
- **Select (`Grill temperature unit`):** Switches the unit the *grill's own panel* uses. This does not change how Home Assistant displays temperatures — that follows your Home Assistant unit system.
- **Button (`Restart controller`):** Restarts the WiFi controller, the usual fix when it stops responding.
- **Button (`Request fast updates`):** Asks the grill to push status every 5 seconds for the next 5 minutes. Does nothing unless the grill is on, and nothing on any path but the relay (`wss`) one, since that is where those pushes go.
- **Sensor (`Firmware version`, `Controller uptime`, `Controller free memory`):** Diagnostics, read on a slower cadence than grill state.
- **Switch (`Module power`):** Turns the grill off. Stays available and reports `off` when the grill is off, rather than disappearing.
- **Switch (`Prime`):** Runs the auger primer motor, on models that support it.

### Actions

- **`pitboss.set_grill_password`:** Sets the grill's connection password and stores it in the config entry, so the two cannot drift apart.
- **`pitboss.start_grill`:** Lights the grill remotely. Refused unless "Allow starting the grill remotely" is enabled in the integration options, and refused while the grill is on, disconnected, or reporting an error such as an empty hopper. Only light a grill you have prepared: lid open, burn pot clear of unburned pellets.

## Installation

### HACS

If you have HACS, go to the three-dot menu and click `Custom
repositories`. Paste the link to the Github repository and select "Integration"
as the category.

### Manual

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`).
1. If you do not have a `custom_components` directory (folder) there, you need to create it.
1. In the `custom_components` directory (folder) create a new folder called `pitboss`.
1. Download _all_ the files from the `custom_components/pitboss/` directory (folder) in this repository.
1. Place the files you downloaded in the new directory (folder) you created.
1. Restart Home Assistant
1. In the HA UI go to "Configuration" -> "Integrations" click "+" and search for "PitBoss"

## Configuration is done in the UI

Power on your grill and it should be discovered automatically over Bluetooth. Once you
initiate the setup process, it will ask for your exact grill model so we can properly
communicate with it. No PitBoss account is needed either way.

If your grill isn't discovered automatically, you can add it manually by entering its
device ID. You'll then choose your exact model and, optionally, a connection password
and how to connect — Bluetooth (`ble`), the vendor relay (`wss`), or the direct local
connection (`local`), which also asks for the grill's address on your network — see
[Connection protocols](#connection-protocols) for what that choice means.

Already set up? You can change the model, password, or connection protocol at any time
via the integration's "Reconfigure" option, without needing to remove and re-add it.

If the grill starts rejecting your password, the integration starts a reauthentication
flow asking you to enter it again, rather than retrying indefinitely.

## Contributions are welcome!

If you want to contribute to this please read the [Contribution guidelines](CONTRIBUTING.md)

***

[pitboss]: https://github.com/dknowles2/ha-pitboss
[commits-shield]: https://img.shields.io/github/commit-activity/y/dknowles2/ha-pitboss.svg?style=for-the-badge
[commits]: https://github.com/dknowles2/ha-pitboss/commits/main
[hacs]: https://github.com/hacs/integration
[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge
[discord]: https://discord.gg/Qa5fW2R
[discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge
[exampleimg]: example.png
[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge
[forum]: https://community.home-assistant.io/
[license-shield]: https://img.shields.io/github/license/dknowles2/ha-pitboss.svg?style=for-the-badge
[maintenance-shield]: https://img.shields.io/badge/maintainer-David%20Knowles%20%40dknowles2-blue.svg?style=for-the-badge
[releases-shield]: https://img.shields.io/github/release/dknowles2/ha-pitboss.svg?style=for-the-badge
[releases]: https://github.com/dknowles2/ha-pitboss/releases

ha-pitboss

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README