philips_sonicare_ble

KO | EN

gitlite — search

#python #hacktoberfest #llm #machine-learning #linux #docker #macos #java #windows #awesome #kubernetes #awesome-list #openai #open-source

philips_sonicare_ble

(★ 44)

Philips Sonicare BLE integration for Home Assistant — real-time brushing data via Bluetooth or ESP32 bridge

philips_sonicare_ble 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Philips Sonicare BLE Integration for Home Assistant

[![HACS Default](https://img.shields.io/badge/HACS-Default-41BDF5.svg)](https://github.com/hacs/default)
[![GitHub Release](https://img.shields.io/github/v/release/mtheli/philips_sonicare_ble)](https://github.com/mtheli/philips_sonicare_ble/releases)
[![License: MIT](https://img.shields.io/github/license/mtheli/philips_sonicare_ble)](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/LICENSE)

This is a custom component for Home Assistant to integrate **Philips Sonicare BLE toothbrushes**.

The integration connects to your toothbrush via **Bluetooth Low Energy (BLE)** to provide battery status, brushing session data, brush head wear tracking, and more. All communication is fully local -- no cloud, no app required.

![Device overview in Home Assistant](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/ToothBrush1.png)

Three connection methods are supported:

1.  **Direct Bluetooth** -- connects from the HA host's Bluetooth adapter (built-in or USB). Uses a persistent live connection with a poll fallback.
2.  **ESP32 BLE Bridge** ★ -- an ESP32 running a custom ESPHome component acts as a wireless BLE relay. Recommended for out-of-range setups; supports multiple devices and notification throttling.
3.  **Bluetooth Proxy** -- uses an existing ESPHome `bluetooth_proxy`. Works for a single Sonicare per proxy; not recommended due to stability issues.

★ = recommended method -- the most reliable option and the one most new features target.

See [Configuration](#configuration) for setup instructions.

---

## Table of Contents

- [Tested Models](#tested-models)
- [Dashboard Card](#dashboard-card)
- [Supported Languages](#supported-languages)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Option A: Direct Bluetooth](#option-a-direct-bluetooth)
  - [Option B: ESP32 BLE Bridge](#option-b-esp32-ble-bridge)
  - [Option C: Bluetooth Proxy](#option-c-bluetooth-proxy)
- [How It Works](#how-it-works)
- [Troubleshooting & Caveats](#troubleshooting--caveats)
- [BLE Protocol](#ble-protocol)
- [Screenshots](#screenshots)

---

## Tested Models

Any BLE-enabled Philips Sonicare toothbrush using either the standard protocol or the newer Condor protocol (HX742X / Series 7100) should work (Sonicare For Kids, ExpertClean, DiamondClean Smart, DiamondClean 9000, DiamondClean Prestige, Series 7100, and more). The integration auto-discovers compatible devices via BLE and selects the right protocol automatically. If you have a different model — happy to hear your test results!

> [!NOTE]
> Some models (ExpertClean, HX991M, DiamondClean Prestige, Series 7100) require **BLE bonding**. The integration detects this automatically and pairs the device during setup. Models like DiamondClean Smart and Sonicare For Kids use open GATT and connect without pairing. Series 7100 brushes additionally use a **rolling private address (RPA)** that can change as often as every ~15–20 seconds — bonding is what allows the host to follow the brush across address rotations. Bonding also needs a host adapter with a working SMP implementation; some cheap USB dongles can't complete it (see [Known Issues](docs/KNOWN_ISSUES.md#some-usb-dongles-cannot-complete-smp-bonding)).

---

## Dashboard Card

For a visual brushing dashboard, use the [**Toothbrush Card**](https://github.com/mtheli/toothbrush-card) -- a custom Lovelace card with live sector tracking, pressure display, and brush head wear indicator. Works with Philips Sonicare, Oral-B and Laifen toothbrushes.

The card is a **separate project and not bundled with this integration** -- install it in addition, via the default HACS store (search for "Toothbrush Card"). The button below opens the **Toothbrush Card** repository in HACS -- it does not install this integration:

[![Install Toothbrush Card via HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=mtheli&repository=toothbrush-card&category=plugin)

![Toothbrush Card with Sonicare](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/Card.png)

For small displays and wall panels there is also a compact view (`tooth_style: none`) with a large standalone timer -- shown here with the header and chips still enabled. With the header hidden as well (`show_header: false`), two of these fit side by side on a 480x480 wall panel:

![Toothbrush Card compact view](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/CardCompact.png)

---

## Supported Languages

| Language | Code | Comment |
|----------|------|---------|
| English  | en | |
| Deutsch  | de | |

Setup dialogs, entity names and entity states all follow the language configured in your Home Assistant instance (per-user profile setting). This includes binary sensor states, which otherwise fall back to English. If your language is not yet supported, it falls back to English. Contributions for additional languages are welcome — copy `custom_components/philips_sonicare_ble/translations/en.json`, translate the values and open a pull request.

---

## Features

This integration creates a new device for your toothbrush and provides the following entities based on your device's hardware:

### Sensor Data (live during brushing)

These sensors are only available while actively brushing and stream live data from the toothbrush's built-in sensors.

---

## Prerequisites

* A compatible Philips Sonicare toothbrush (see [Tested Models](#tested-models) above).
* **Either** a Home Assistant instance with the **Bluetooth integration** enabled and a working Bluetooth adapter, **or** an ESP32 running the [BLE Bridge component](esphome/SETUP.md).
* **Pairing depends on the model** -- some models require BLE bonding, the integration detects and handles this automatically (see the note under [Tested Models](#tested-models)). Simply close any Sonicare phone app to free the BLE connection.

> [!NOTE]
> The toothbrush only advertises via BLE for a short time after being picked up from the charger or turned on/off. It enters deep sleep after approximately 20 seconds of inactivity. While on the charging stand, it is **not reachable** via BLE.

---

## Installation

### HACS (Recommended)

This integration is available in the **default HACS store** — just click the button below, or search HACS for "Philips Sonicare".

[![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=mtheli&repository=philips_sonicare_ble&category=integration)

Then restart Home Assistant.

> Don't have HACS yet? Follow the [HACS installation guide](https://hacs.xyz/docs/use/) first.

<details>
<summary>Manual installation</summary>

1.  Copy the `custom_components/philips_sonicare_ble` directory from this repository into your Home Assistant `config/custom_components/` folder.
2.  Restart Home Assistant.

</details>

---

## Configuration

The integration supports three connection methods:

⭐ = recommended path

> [!TIP]
> Want to see the setup dialogs before you start? The **[interactive config-flow walkthrough](https://mtheli.github.io/philips_sonicare_ble/config_flow_walkthrough.html)** lets you click through every screen of the setup — normal path, conditional branches, errors and aborts — with example data ([HTML source](docs/config_flow_walkthrough.html)).

> [!NOTE]
> The [ESP-IDF bug](https://github.com/esphome/esphome/issues/15783) that crashed GATT service discovery on the ESP32 proxy/bridge paths is **fixed as of ESPHome 2026.7.1** (bundles ESP-IDF 5.5.5) — no workaround needed anymore. Building with an older ESPHome still requires the [compile-time workaround](docs/KNOWN_ISSUES.md#bluedroid-crash-with-bluetooth_proxy-fixed-in-esphome-202671); since bridge firmware v1.10.0 the component refuses to build the affected combination and points you to it.

### Option A: Direct Bluetooth

1.  Wake up your toothbrush (pick it up from the charger or briefly turn it on).
2.  Navigate to **Settings > Devices & Services**.
3.  The toothbrush should appear under **Discovered** -- click **Configure**.
    - If not discovered automatically, click **+ Add Integration**, search for "**Philips Sonicare**", and enter the MAC address manually.
4.  The confirmation dialog shows the current brush status and detected services, and a **Name** field pre-filled with a model + MAC-suffix default (e.g. `Sonicare HX9352 (3456)`). Edit it now if you have several brushes of the same model — you can also rename later via Settings → Devices. Make sure the toothbrush is **turned on** (status shows "Active") before clicking **Submit**.

> [!TIP]
> Some models (ExpertClean, HX991M, DiamondClean Prestige, Series 7100) require BLE bonding -- the integration detects this automatically and pairs the device during setup via D-Bus. If auto-pairing is not available (e.g. HAOS without D-Bus), manual pairing instructions are shown. Series 7100 brushes also rotate their advertised BLE address (RPA) — on some units as often as every ~15–20 seconds — so an unbonded brush appears under different MACs on each scan; bonding pins it to a stable identity. If pairing times out repeatedly on a cheap USB dongle, see [Known Issues](docs/KNOWN_ISSUES.md#some-usb-dongles-cannot-complete-smp-bonding). Simply close the Sonicare phone app to free the BLE connection.

<details>
<summary>Manual Pairing (fallback when auto-pairing fails)</summary>

If the config flow reports that auto-pairing was not successful, you have two options. Run them via the **Terminal & SSH** addon on HAOS, or any shell on the machine running Home Assistant.

#### Automated Pairing Script

```bash
bash /config/custom_components/philips_sonicare_ble/scripts/pair.sh
```

The script scans for nearby Sonicare toothbrushes, lets you choose which one to pair, and handles the `bluetoothctl` agent setup required for bonding. You can also pair a specific address directly:

```bash
bash /config/custom_components/philips_sonicare_ble/scripts/pair.sh AA:BB:CC:11:22:33
```

Keep the toothbrush awake (press the power button) while the script runs -- it is not reachable while sitting on the charger.

#### Manual Pairing with `bluetoothctl`

Start an interactive session and register a pairing agent first -- a plain `bluetoothctl pair` registers no agent, and some models reject the pairing without one:

```
bluetoothctl
agent NoInputNoOutput
default-agent
pair AA:BB:CC:11:22:33
trust AA:BB:CC:11:22:33
exit
```

Then click **Retry** in the config flow.

</details>

### Option B: ESP32 BLE Bridge

If your Home Assistant host is too far from the toothbrush for a direct Bluetooth connection, you can use an [ESP32](https://esphome.io/components/esp32.html) as a wireless BLE bridge. The ESP32 connects to the toothbrush and relays data to HA over WiFi.

This is **not** a standard ESPHome Bluetooth Proxy -- it is a dedicated component that manages the BLE connection directly on the ESP32 and provides full read/write/subscribe access to all GATT characteristics.

> [!NOTE]
> This option requires basic [ESPHome](https://esphome.io/) knowledge (flashing firmware, editing YAML configs). If you're new to ESPHome, check out [Getting Started with ESPHome](https://esphome.io/guides/getting_started_hassio) first.

For the complete setup guide, see **[ESP32 Bridge Setup Guide](esphome/SETUP.md)**.

> [!TIP]
> Each ESP bridge slot accepts optional `friendly_name:` and `area:` fields that pre-fill the HA setup form and auto-assign the brush to an HA area on first install — convenient for multi-brush setups. See [Per-slot defaults](esphome/README.md#per-slot-defaults-friendly_name-and-area).

### Option C: Bluetooth Proxy

> [!WARNING]
> **Due to stability issues, it is strongly recommended to use [Option B: ESP32 BLE Bridge](#option-b-esp32-ble-bridge) instead of a Bluetooth Proxy.** Proxy setups have shown silent-connection issues — after a brushing session a device can stop delivering notifications while the proxy itself stays reachable, requiring a Home Assistant integration reload to recover. The proxy also has no notification throttling, which overloads the WiFi socket queue when more than one Sonicare is connected to the same proxy.
>
> This option is documented for users who already operate a proxy for other devices and only have a single Sonicare.

If you already operate an [ESPHome Bluetooth Proxy](https://esphome.io/components/bluetooth_proxy.html), the integration can use it as a relay — no dedicated bridge firmware needed. Confirmed working on ESPHome 2026.2+ with `io_capability: none`.

**Known caveats:**
- **Proxy firmware built with ESPHome < 2026.7.1 needs the [Bluedroid workaround](docs/KNOWN_ISSUES.md#bluedroid-crash-with-bluetooth_proxy-fixed-in-esphome-202671)** — from 2026.7.1 on (bundles ESP-IDF 5.5.5) no patch is needed.
- **First connect after reboot takes ~5 s longer** than Direct BLE. Bond keys live on the proxy's NVS, so service discovery and re-encryption race briefly; the integration retries reads automatically during this window.
- **Notify Throttle option has no effect on Proxy** — throttling is only implemented in the ESP32 BLE Bridge firmware.
- **RSSI shown in the Connection device reflects the scanner actually carrying the link** (since v0.9.x), not the strongest advertisement.

Setup is the same as Option A — Home Assistant's Bluetooth stack picks the proxy automatically when it has a better or equal connection score to the host adapter.

### Options

---

## How It Works

### Connection Behavior

The Sonicare toothbrush has unique BLE behavior compared to other Philips devices:

* **Slow advertising** -- the toothbrush sends BLE advertisements only every 10-30 seconds (most BLE devices: every 100-500ms).
* **Short wake window** -- after turning off, the toothbrush stays connectable for only ~20 seconds before entering deep sleep.
* **Pairing varies by model** -- open GATT on some families, BLE bonding on others; Series 7100 additionally rotates its BLE address (RPA). Details in the note under [Tested Models](#tested-models) — the integration picks the right path automatically.

The integration handles this with:

1. **Advertisement-triggered reconnect** -- a BLE advertisement callback immediately wakes the connection thread, eliminating unnecessary backoff delays.
2. **Subscribe-first pattern** -- after connecting, BLE notification subscriptions are established immediately (before reading data). This keeps the connection alive because the toothbrush stays awake as long as active subscriptions exist.
3. **Smart lock management** -- the polling fallback yields to the live monitoring thread when an advertisement is detected, preventing connection contention.

### Data Flow

```
Toothbrush wakes up
    --> BLE Advertisement detected by HA
    --> Integration connects (~6s BLE stack overhead)
    --> Subscribe to 13 notification characteristics (~1s)
    --> Read all characteristics (~3s)
    --> Live updates flow until toothbrush sleeps
    --> Disconnect detected --> wait for next advertisement
```

---

## Troubleshooting & Caveats

* **Toothbrush not discovered**: Wake it up by picking it up from the charger or briefly turning it on. The toothbrush is not reachable via BLE while on the charging stand.
* **Slow connection**: The toothbrush advertises every 10-30 seconds. The integration connects as soon as the first advertisement is received, but the BLE stack adds ~6 seconds overhead.
* **Connection drops quickly**: This is normal when the toothbrush is idle. It sleeps after ~20 seconds. The integration will reconnect automatically on the next wake.
* **Phone app conflict**: The toothbrush supports only one BLE connection. Close or uninstall the Sonicare phone app if you experience connection issues.
* **Pairing issues**: If a model that requires bonding won't connect, remove the toothbrush from your phone's Bluetooth settings first (Settings → Bluetooth → Philips Sonicare → Forget/Unpair). The integration handles stale bonds automatically, but the phone's bond may block the connection.
* **ESPHome Bluetooth Proxy**: Works out of the box from ESPHome 2026.7.1 (older builders need the [Bluedroid NULL-check patch](docs/KNOWN_ISSUES.md#bluedroid-crash-with-bluetooth_proxy-fixed-in-esphome-202671)). See [Option C](#option-c-bluetooth-proxy) for scope and the dedicated [ESP32 BLE Bridge](esphome/SETUP.md) as the recommended alternative for multi-device setups.
* **Unsure if your model is compatible?** Run the [GATT scan script](scripts/sonicare_scan.py) to check which BLE protocol your toothbrush uses. It only needs Python 3 and `bleak` (`pip install bleak`).

### Known Issues

* **Direct BLE reconnect may be delayed**: Home Assistant's Bluetooth stack filters duplicate advertisements. Since the Sonicare sends identical advertisement data on every broadcast, wake-ups can be missed. On HA 2026.5+ the integration clears the advertisement de-dup history before each wait so the next broadcast gets through; on older HA versions it falls back to a D-Bus RSSI listener. Reconnects may still take a little longer than expected. See [habluetooth#397](https://github.com/Bluetooth-Devices/habluetooth/discussions/397) for the upstream discussion.

---

## BLE Protocol

The integration communicates directly via BLE -- no cloud, no app required. All communication is fully local.

The toothbrush exposes multiple GATT services with individual characteristics for each data point (battery, brushing state, pressure, brush head, etc.). Data is read directly from these characteristics and live updates are received via GATT notifications.

For a detailed technical description of the BLE protocol including service UUIDs, characteristic reference, data formats, and enum values, see [BLE_PROTOCOL.md](docs/BLE_PROTOCOL.md).

---

## Screenshots

| Sensors & Controls | Diagnostics | Dashboard Card |
| :---: | :---: | :---: |
| ![Sensors](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/ToothBrush1.png) | ![Diagnostics](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/ToothBrush2.png) | ![Card](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/Card.png) |

| Device Overview | Brush Head |
| :---: | :---: |
| ![Overview](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/DeviceOverview.png) | ![Brush Head](https://raw.githubusercontent.com/mtheli/philips_sonicare_ble/master/screenshots/BrushHead.png) |

---

## Disclaimer

This is an independent community project and is not affiliated with, endorsed by, or sponsored by Philips. All product names, trademarks, and registered trademarks are property of their respective owners.

## License

[MIT](LICENSE)

philips_sonicare_ble

philips_sonicare_ble 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

philips_sonicare_ble

philips_sonicare_ble 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README