philips_shaver

KO | EN

gitlite — search

#javascript #react #ai #typescript #llm #golang #machine-learning #docker #nodejs #java #awesome #vue #security #open-source

(★ 23)

Home Assistant integration for Philips shavers and OneBlade via Bluetooth Low Energy

philips_shaver Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Philips Shaver 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_shaver)](https://github.com/mtheli/philips_shaver/releases)
[![License: MIT](https://img.shields.io/github/license/mtheli/philips_shaver)](https://raw.githubusercontent.com/mtheli/philips_shaver/main/LICENSE)

This is a custom component for Home Assistant to integrate **Philips Bluetooth-enabled shavers**.

The integration connects to your shaver via **Bluetooth Low Energy (BLE)** to provide status, usage, and advanced telemetry data. It automatically detects the capabilities of your specific model during setup to only show relevant entities.

![Device overview in Home Assistant](https://raw.githubusercontent.com/mtheli/philips_shaver/main/images/device.png)

Two connection methods are supported:

1.  **Direct Bluetooth** — connects from the HA host's Bluetooth adapter. Event-driven: detects when the shaver wakes up via BLE advertisements, then establishes a persistent live connection.
2.  **ESP32 BLE Bridge** — an ESP32 running ESPHome acts as a wireless BLE relay. Ideal when the shaver is out of Bluetooth range of the HA host.

> [!NOTE]
> The standard ESPHome `bluetooth_proxy` is **not currently supported** — it does not handle the shaver's LE Secure Connections pairing. Use the dedicated ESP32 BLE Bridge component (Option B) instead, which can run a `bluetooth_proxy` for *other* BLE devices alongside it.

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

---

## Table of Contents

- [Tested Models](#tested-models)
- [Lovelace Card](#lovelace-card)
- [Community](#community)
- [Supported Languages](#supported-languages)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Option A: Direct Bluetooth](#option-a-direct-bluetooth-pairing)
  - [Option B: ESP32 BLE Bridge](#option-b-esp32-ble-bridge)
- [Example Automations](#example-automations)
- [Troubleshooting & Caveats](#troubleshooting--caveats)
- [BLE Protocol](#ble-protocol)
- [Screenshots](#screenshots)

---

## Tested Models

| Model | Direct BLE | ESP32 Bridge | Tested by |
| :--- | :---: | :---: | :--- |
| **Shaver Series 7000** | | | |
| [S7886](https://www.usa.philips.com/c-p/S7886_84/shaver-series-7000-wet-dry-electric-shaver) | :white_check_mark: | | Community ([#5](https://github.com/mtheli/philips_shaver/issues/5)) |
| [S7887](https://www.usa.philips.com/c-p/S7887_82/shaver-series-7000-wet-dry-electric-shaver) | | :white_check_mark: | Community ([forum](https://community.home-assistant.io/t/philips-bluetooth-shaver-monitoring/858822/8)) |
| [S7788](https://www.usa.philips.com/c-p/S7788_82/norelco-shaver-7100-wet-dry-electric-shaver-series-7000) | | :white_check_mark: | Community ([#13](https://github.com/mtheli/philips_shaver/pull/13)) |
| **Shaver Series 9000** | | | |
| [S9986](https://www.philips.co.uk/c-p/S9986_55/shaver-series-9000-wet-and-dry-electric-shaver) | | :white_check_mark: | Community ([#7](https://github.com/mtheli/philips_shaver/issues/7)) |
| [S9987](https://www.philips.co.uk/c-p/S9987_55/shaver-series-9000-wet-and-dry-electric-shaver) | :white_check_mark: | | Community ([#9](https://github.com/mtheli/philips_shaver/issues/9)) |
| **Shaver Series 9000 Prestige (i9000)** | | | |
| [XP9201](https://www.usa.philips.com/c-p/XP9201_88/i9000-prestige-wet-dry-electric-shaver-with-senseiq) | :white_check_mark: | :white_check_mark: | Maintainer |
| [XP9202](https://www.philips.com.au/c-p/XP9202_33/i9000-prestige-wet-dry-electric-shaver-with-skiniq) | :white_check_mark: | | Community ([#11](https://github.com/mtheli/philips_shaver/issues/11)) |
| [XP9400](https://www.usa.philips.com/c-p/XP9400_89/i9000-prestige-ultra-wet-dry-electric-shaver-with-senseiq-pr) | :white_check_mark: | :white_check_mark: | Community ([#1](https://github.com/mtheli/philips_shaver/issues/1), [#3](https://github.com/mtheli/philips_shaver/issues/3)) |
| [XP9402](https://www.philips.com.au/c-p/XP9402_27/i9000-prestige-ultra-wet-dry-electric-shaver-with-skiniq-pro) | :white_check_mark: | :white_check_mark: | Community ([#11](https://github.com/mtheli/philips_shaver/issues/11), [#16](https://github.com/mtheli/philips_shaver/issues/16)) |
| [XP9405](https://www.usa.philips.com/c-p/XP9405_84/i9000-prestige-ultra-wet-dry-electric-shaver-with-senseiq-pr) | :white_check_mark: | | Community ([forum](https://community.home-assistant.io/t/has-anyone-integrated-philips-s9000-with-home-assistant/592101/6)) |
| **OneBlade 360** | | | |
| [QP4530](https://www.usa.philips.com/c-p/QP4530_90/oneblade-360-with-connectivity-face) | :white_check_mark: | :white_check_mark: | Maintainer |

Other BLE-enabled Philips shavers and groomers using the same GATT services may also work. The integration auto-detects available services and capabilities during setup — entities are only created for features your device supports. If your model works, please [let me know](https://github.com/mtheli/philips_shaver/issues) so I can add it to the list!

---

## Lovelace Card

A dedicated dashboard card — the **Philips Shaver Card** — ships with this integration. No separate installation and no dashboard resource setup needed: the integration registers the card automatically (you'll see one entry under *Settings → Dashboards → Resources*, which it keeps up to date). Add it via the dashboard card picker or in YAML:

```yaml
type: custom:philips-shaver-card
device_id: <your-device-id>
title: My Shaver   # optional, defaults to the device's name
show_model: true   # optional, show model number as subtitle (default: true)
```

![Philips Shaver Card](https://raw.githubusercontent.com/mtheli/philips_shaver/main/images/card_shaving.png)

The card automatically switches between standby, shaving, charging, and cleaning modes with live pressure gauge, battery status, and session stats.

> [!NOTE]
> **Upgrading from the standalone card?** The card was previously distributed separately as [philips_shaver_card](https://github.com/mtheli/philips_shaver_card). If that copy is still installed, remove it — in HACS uninstall *Philips Shaver Card* (this also removes the dashboard resource), or delete the manually added resource under *Settings → Dashboards → Resources*. A leftover standalone copy can shadow the bundled, up-to-date card; the integration raises a repair issue if it detects one. Your dashboards keep working unchanged — the card type stays `custom:philips-shaver-card`. Card development continues in that repository; releases ship here.

---

## Community

[<img src="https://img.youtube.com/vi/ROI91x2Swv8/maxresdefault.jpg" alt="Smartes Badezimmer? So hilft dir ein Shelly Wall Display beim Zähneputzen & Rasieren!" width="480">](https://www.youtube.com/watch?v=ROI91x2Swv8)

[Smartes Badezimmer? So hilft dir ein Shelly Wall Display beim Zähneputzen & Rasieren!](https://www.youtube.com/watch?v=ROI91x2Swv8) — Video by [@smartmatic](https://github.com/smartmatic) showing the integration and card on a Shelly Wall Display with XP9405 and ESP32 Bridge (German)

---

## 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_shaver/translations/en.json`, translate the values and open a pull request.

---

## Features

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

---

## Prerequisites

* A compatible Philips Shaver (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).
* The shaver supports only one active connection at a time — it must be **unpaired from your phone**, any manufacturer app ([GroomTribe](https://www.philips.at/c-w/malegrooming/products/groomtribe-app.html) / [OneBlade](https://www.philips.com/c-w/country-selectorpage/myoneblade.html)), **and from the device itself** before Home Assistant can connect.

---

## Installation

### HACS (Recommended)

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

[![Open in HACS](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=mtheli&repository=philips_shaver&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_shaver` directory from this repository into your Home Assistant `config/custom_components/` folder.
2.  Restart Home Assistant.

</details>

---

## Configuration

The integration supports two connection methods:

| | Method | Best for |
| :--- | :--- | :--- |
| **[Option A](#option-a-direct-bluetooth-pairing)** | **Direct Bluetooth** | HA host is within Bluetooth range of the shaver (typically 5–10 m / 15–30 ft, less through walls) |
| **[Option B](#option-b-esp32-ble-bridge)** | **ESP32 BLE Bridge** | Shaver is out of range — a small ESP32 device placed near the shaver relays data over WiFi |
| ❌ | ~~Stock ESPHome `bluetooth_proxy`~~ | **Not currently supported** — the standard ESPHome Bluetooth Proxy does not handle the shaver's LE Secure Connections pairing. Use Option B (the dedicated bridge component) instead, which can run a `bluetooth_proxy` for *other* BLE devices alongside it. |

> [!IMPORTANT]
> The shaver must be **fully unpaired** (from your phone **and** the device itself) before connecting to Home Assistant.
> Follow the [Unpairing Guide](docs/UNPAIRING.md) for step-by-step instructions.

> [!TIP]
> Want to see the setup dialogs before you start? The **[interactive config-flow walkthrough](https://mtheli.github.io/philips_shaver/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)).

### Option A: Direct Bluetooth (Pairing)

1.  Ensure the shaver is **turned on**.
2.  Navigate to **Settings > Devices & Services**.
3.  The shaver should appear under **Discovered** — click **Configure**.
    - If not discovered automatically, click **+ Add Integration**, search for "**Philips Shaver**", and enter the MAC address manually.
4.  Click **Submit**. The integration connects and pairs automatically.

> [!TIP]
> **Automatic pairing** works out of the box on Home Assistant OS and any Linux system with BlueZ. Pairing, trusting, and stale bond removal are handled automatically via D-Bus — no terminal commands needed. If pairing times out repeatedly on a cheap USB dongle, see [Known Issues](docs/KNOWN_ISSUES.md#some-usb-dongles-cannot-complete-smp-bonding).

<details>
<summary>Manual Pairing (Fallback for Docker, macOS, etc.)</summary>

On systems without D-Bus, the integration will show instructions for manual pairing via terminal instead. You have two options:

#### Automated Pairing Script

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

The script scans for nearby Philips devices, lets you choose which one to pair, and handles the `bluetoothctl` agent setup required for LE Secure Connections.

You can also pair a specific device directly:

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

#### Manual Pairing with `bluetoothctl`

1.  Start the Bluetooth control tool:

```bash
    bluetoothctl
    ```

2.  Register the pairing agent (required for LE Secure Connections):

```bash
    agent KeyboardDisplay
    default-agent
    ```

3.  Start scanning to find your shaver. It will appear as "Philips XP9201" or similar. Note down its **MAC Address** (e.g., `AA:BB:CC:11:22:33`).

```bash
    scan on
    # ... Wait for the shaver to appear and note the address.
    scan off
    ```

4.  Pair and trust the device:

```bash
    pair AA:BB:CC:11:22:33
    trust AA:BB:CC:11:22:33
    exit
    ```

After manual pairing, return to the integration setup dialog and click **Submit** to retry.

</details>

### Option B: ESP32 BLE Bridge

If your Home Assistant host is too far from the shaver 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 shaver and relays data to HA over WiFi.

This is **not** a standard ESPHome Bluetooth Proxy — it is a custom component that handles the shaver's LE Secure Connections pairing and provides full read/write/subscribe access to all GATT characteristics.

A single ESP32 can bridge **multiple devices** (e.g. a shaver and an OneBlade simultaneously).

> **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.

The bridge supports two pairing modes per `philips_shaver:` entry:

- **Mode A — Fixed MAC** (`ble_client_id:` references a `ble_client:` block with the shaver's MAC). Pairing happens once, manually via `pair.sh` from the host. Deterministic slot-to-shaver mapping; ideal when you already know the MAC.
- **Mode B — Auto-Discovery** (no `ble_client_id:`, no `mac_address:`). The bridge scans for the universal Philips Shaver Platform Service UUID, bonds to the first match via the HA setup dialog's pair-mode flow, and persists the bonded MAC in NVS. No terminal access needed; ideal for Bluetooth-Proxy-only setups or when you want to swap shavers without re-flashing.

For the complete setup guide and Mode A vs Mode B comparison, see **[ESP Bridge Setup Guide](esphome/SETUP.md)** and [`esphome/README.md`](esphome/README.md).

---

## Example Automations

See **[AUTOMATIONS.md](docs/AUTOMATIONS.md)** for ready-to-use automation examples, including low battery alerts, smart plug charging, usage reminders, and maintenance notifications.

---

## Troubleshooting & Caveats

* *Pairing fails*: The shaver must be unpaired from **both** your phone's Bluetooth settings **and** from the device itself. Unpairing in the app alone is not enough — see the [unpairing instructions](#configuration) for your model. This is the most common cause of pairing failures.
* *Shaver ignores all pairing requests*: If the shaver no longer pairs with anything — not even the official Philips app — a **30-second factory reset** usually recovers it. See the [Unpairing Guide](docs/UNPAIRING.md#last-resort-factory-reset-30-seconds).
* *Pairing times out on one adapter but works on another*: Some cheap USB Bluetooth dongles cannot complete the SMP bonding handshake at all — see [Known Issues](docs/KNOWN_ISSUES.md#some-usb-dongles-cannot-complete-smp-bonding).
* *Connection Conflict*: If the integration fails to set up, ensure no smartphone is currently connected to the shaver.
* *ESPHome Bluetooth Proxy*: The standard ESPHome Bluetooth Proxy does **not** work with this shaver because it requires LE Secure Connections pairing ([details](docs/KNOWN_ISSUES.md#standard-esphome-bluetooth-proxies-cannot-pair-a-shaver)). Use the dedicated [ESP32 BLE Bridge](esphome/SETUP.md) instead.
* *Stability:* Bluetooth signals are weak. Ensure your HA host or ESP32 bridge is placed as close to the shaver's location as possible.

---

## BLE Protocol

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

The shaver exposes multiple GATT services with individual characteristics for each data point (battery, motor, pressure, light ring, 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 capability flags, see [BLE_PROTOCOL.md](docs/BLE_PROTOCOL.md).

For debug service actions (reading arbitrary BLE characteristics via Developer Tools), see [ADVANCED.md](docs/ADVANCED.md).

## Screenshots

## 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_shaver

philips_shaver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

philips_shaver

philips_shaver Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README