ESPHome Cosori Kettle BLE Component

Control your Cosori smart kettle from Home Assistant using an ESP32 and BLE.

Features

• Real-time monitoring: Temperature, setpoint, on-base status, heating state
• Remote control: Start/stop heating, adjust target temperature (104-212°F)
• Persistent connection: Auto-reconnect on disconnect
• BLE connection toggle: Disable BLE to use official mobile app (kettle only supports 1 connection)
• Home Assistant integration: Native entities (sensors, switches, numbers)
• Automation-ready: Use in HA automations, scripts, and scenes

Hardware Requirements

• ESP32 board with Bluetooth LE support (e.g., ESP32-DevKitC, ESP32-WROOM-32)
• Cosori smart kettle with BLE: https://www.amazon.com/COSORI-Electric-Gooseneck-Variable-Stainless/dp/B07T1CH2HH
• Stable power supply for ESP32

Quick Start

Copy this complete configuration, change the MAC address, and flash to your ESP32:

esphome:
  name: cosori-kettle
  platform: ESP32
  board: esp32dev

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Cosori Kettle Fallback"
    password: !secret fallback_password

api:
  encryption:
    key: !secret api_encryption_key

ota:
  password: !secret ota_password

logger:

# External component from GitHub
external_components:
  - source: github://barrymichels/CosoriKettleBLE
    components: [cosori_kettle_ble]
    refresh: 0s

# BLE tracker
esp32_ble_tracker:
  scan_parameters:
    active: false

# BLE client - CHANGE THIS MAC ADDRESS TO YOUR KETTLE'S ADDRESS
ble_client:
  - mac_address: "C4:A9:B8:73:AB:29"
    id: cosori_kettle_client
    auto_connect: true

# Cosori kettle component
cosori_kettle_ble:
  ble_client_id: cosori_kettle_client
  id: my_kettle
  name: "Kettle"
  update_interval: 1s

# Sensors
sensor:
  - platform: cosori_kettle_ble
    cosori_kettle_ble_id: my_kettle
    temperature:
      name: "Kettle Temperature"
    kettle_setpoint:
      name: "Kettle Setpoint"

# Binary sensors
binary_sensor:
  - platform: cosori_kettle_ble
    cosori_kettle_ble_id: my_kettle
    on_base:
      name: "Kettle On Base"
    heating:
      name: "Kettle Heating"

# Number (target temperature control)
number:
  - platform: cosori_kettle_ble
    cosori_kettle_ble_id: my_kettle
    target_setpoint:
      name: "Kettle Target Temperature"

# Switches
switch:
  - platform: cosori_kettle_ble
    cosori_kettle_ble_id: my_kettle
    heating_switch:
      name: "Kettle Heating"
    ble_connection_switch:
      name: "Kettle BLE Connection"

That's it! Just find your kettle's MAC address (see below) and you're ready to go.

Native Home Assistant Integration

If you'd prefer a native HA integration (no ESP32 required), check out ha-cosori-kettle by @rygwdn.

Climate Entity & Thermostat Card

The kettle automatically appears as a climate entity in Home Assistant when you add the component! This means you can use the beautiful native thermostat card with its semi-circle temperature slider right away.

Home Assistant Integration

Here's what the integration looks like in Home Assistant:

The component provides:

• Climate entity (Kettle) - Off/Heat mode with temperature control
• Switches - BLE Connection toggle, Heating control
• Sensors - Temperature, Setpoint, On Base status, Heating status
• Number slider - Target temperature adjustment (104-212°F)

Customizing the Climate Entity Name

In your ESPHome config, you can optionally set a name for the climate entity:

cosori_kettle_ble:
  ble_client_id: cosori_kettle_client
  id: my_kettle
  name: "Kettle"  # This sets the climate entity name

Using the Thermostat Card

Add this to your Lovelace dashboard:

type: thermostat
entity: climate.kettle  # or whatever name you chose

The thermostat card provides:

• Semi-circle temperature slider (40-100°C / 104-212°F)
• Current temperature display
• Mode control (OFF / HEAT)
• Action indicator (IDLE / HEATING)

How It Works

• OFF mode: Kettle is idle, not heating
• HEAT mode: Kettle will heat to target temperature
• Temperature slider: Adjust target temperature (40-100°C / 104-212°F)
• Current temperature: Shows actual water temperature
• Action: Shows HEATING when actively warming, IDLE otherwise

Note: Home Assistant will display temperatures in your preferred unit (Celsius or Fahrenheit). The kettle natively uses Fahrenheit, and all conversions are handled automatically.

Alternative: Individual Entities

You can also use the individual entities (sensors, switches, numbers) for more granular control or custom card designs. Both approaches work simultaneously!

Finding Your Kettle's MAC Address

Method 1: Using bluetoothctl (Linux)

sudo bluetoothctl
scan on
# Look for your kettle in the list (usually shows as "Cosori" or similar)
# Note the MAC address (e.g., C4:A9:B8:73:AB:29)
scan off
exit

Method 2: Using BLE Scanner App

• iOS: Download "BLE Scanner" or "LightBlue"
• Android: Download "nRF Connect" or "BLE Scanner"
• Scan for devices and look for your kettle
• Note the MAC address

Method 3: Using Python Script

#!/usr/bin/env python3
import asyncio
from bleak import BleakScanner

async def main():
    devices = await BleakScanner.discover()
    for d in devices:
        if "cosori" in d.name.lower() or "kettle" in d.name.lower():
            print(f"Found: {d.name} - {d.address}")

asyncio.run(main())

Advanced Configuration

See cosori-kettle-example.yaml for a complete configuration example.

Entities

Sensors

| Entity | Type | Description | Unit | |--------|------|-------------|------| | temperature | Sensor | Current water temperature | °F | | kettle_setpoint | Sensor | Actual setpoint on kettle | °F |

Binary Sensors

| Entity | Type | Description | |--------|------|-------------| | on_base | Binary Sensor | True if kettle is on charging base | | heating | Binary Sensor | True if kettle is actively heating |

Numbers

| Entity | Type | Description | Range | |--------|------|-------------|-------| | target_setpoint | Number | User-adjustable target temperature | 104-212°F |

Switches

| Entity | Type | Description | |--------|------|-------------| | heating_switch | Switch | Start/stop heating (uses target_setpoint) | | ble_connection_switch | Switch | Enable/disable BLE connection |

Usage

Starting the Kettle

1. Set target temperature:

   service: number.set_value
   target:
     entity_id: number.kettle_target_temperature
   data:
     value: 180
   

2. Turn on heating switch:

   service: switch.turn_on
   target:
     entity_id: switch.kettle_heating
   

Stopping the Kettle

service: switch.turn_off
target:
  entity_id: switch.kettle_heating

Using Official Mobile App

To use the official Cosori mobile app (which requires exclusive BLE access):

1. Turn off BLE connection switch in Home Assistant
2. Use the mobile app as normal
3. Turn on BLE connection switch when done

Home Assistant Automations

Example 1: Morning Kettle Automation

automation:
  - alias: "Morning Kettle"
    trigger:
      - platform: time
        at: "07:00:00"
    condition:
      - condition: state
        entity_id: binary_sensor.kettle_on_base
        state: "on"
    action:
      - service: number.set_value
        target:
          entity_id: number.kettle_target_temperature
        data:
          value: 212
      - service: switch.turn_on
        target:
          entity_id: switch.kettle_heating

Example 2: Kettle Ready Notification

Note: The kettle holds temperature when it reaches setpoint, so heating doesn't turn off. Use temperature threshold instead:

automation:
  - alias: "Kettle Ready"
    trigger:
      - platform: numeric_state
        entity_id: sensor.kettle_temperature
        above: 205  # Trigger a few degrees before setpoint
    condition:
      - condition: state
        entity_id: binary_sensor.kettle_heating
        state: "on"
    action:
      - service: notify.mobile_app
        data:
          title: "Kettle Ready"
          message: "Your water is hot! ☕"

Example 3: Using Climate Entity

automation:
  - alias: "Morning Tea"
    trigger:
      - platform: time
        at: "07:00:00"
    condition:
      - condition: state
        entity_id: binary_sensor.kettle_on_base
        state: "on"
    action:
      # Set temperature using climate entity
      - service: climate.set_temperature
        target:
          entity_id: climate.kettle
        data:
          temperature: 100  # 100°C = 212°F
      # Turn on heating
      - service: climate.set_hvac_mode
        target:
          entity_id: climate.kettle
        data:
          hvac_mode: heat
      # Wait 5 minutes then notify
      - delay: "00:05:00"
      - service: notify.mobile_app
        data:
          message: "Your tea water should be ready! ☕"

Protocol Information

This component implements the Cosori kettle BLE protocol reverse-engineered from packet captures:

• Service UUID: 0000fff0-0000-1000-8000-00805f9b34fb
• RX Characteristic: 0000fff1-... (notifications from kettle)
• TX Characteristic: 0000fff2-... (commands to kettle)
• Sequence: Registration handshake → Continuous polling (1s) → Commands

See the protocol documentation for details (if available).

Troubleshooting

Kettle Not Connecting

1. Check MAC address: Ensure it matches your kettle
2. Check distance: ESP32 should be within ~10m of kettle
3. Check kettle: Ensure it's on the base and powered
4. Check logs: Enable logger in ESPHome config
5. **Rest