ha-pitboss

PitBoss

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

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 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; 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).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called pitboss.
4. Download all the files from the custom_components/pitboss/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. 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 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

---