1
2
3
4
5
6
7
8
9

┌─────────────────────────────────────────┐
│ 应用层 (Application / GATT-based Profile)│
├─────────────────────────────────────────┤
│ Host：GAP / GATT / ATT / SMP / L2CAP     │  ← LE Host（控制器之上）
├─────────────────────────────────────────┤
│ HCI（Host-Controller Interface）          │
├─────────────────────────────────────────┤
│ Controller：LL / PHY                     │  ← Controller（蓝牙芯片内）
└─────────────────────────────────────────┘

1
2
3
4
5

Profile
└── Service (128-bit UUID)
    └── Characteristic (128-bit UUID)
        ├── Value (字节数组)
        └── Descriptor (128-bit UUID, 例如 CCCD 0x2902)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import bluetooth
import ubinascii

_IRQ_CENTRAL_CONNECT = 1
_IRQ_CENTRAL_DISCONNECT = 2
_IRQ_GATTS_WRITE = 3
_IRQ_SCAN_RESULT = 5
_IRQ_SCAN_DONE = 6
_IRQ_PERIPHERAL_CONNECT = 7
_IRQ_GATTC_NOTIFY = 18

def bt_irq(event, data):
    if event == _IRQ_SCAN_RESULT:
        addr_type, addr, adv_type, rssi, adv_data = data
        print(ubinascii.hexlify(addr), rssi, ubinascii.hexlify(adv_data))

ble = bluetooth.BLE()
ble.active(True)
ble.irq(bt_irq)
ble.gap_scan(2000, 30000, 30000)  # 2s，interval=30ms，window=30ms

1
2
3
4
5
6

aioble-central   # Central + Observer
aioble-client    # GATT Client
aioble-l2cap
aioble-peripheral
aioble-security
aioble-server

1
2
3
4
5
6
7

import aioble
import bluetooth

async def scan():
    async with aioble.scan(duration_ms=5000, interval_us=30000, window_us=30000, active=True) as scanner:
        async for r in scanner:
            print(r, r.name(), r.rssi, list(r.services()), list(r.manufacturer()))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

import aioble
import bluetooth
import asyncio

_ENV_SENSE_UUID = bluetooth.UUID(0x181A)
_TEMP_UUID = bluetooth.UUID(0x2A6E)

async def read_temp(addr="aa:bb:cc:dd:ee:ff"):
    device = aioble.Device(aioble.ADDR_PUBLIC, addr)
    try:
        conn = await device.connect(timeout_ms=2000)
    except asyncio.TimeoutError:
        print("connect timeout")
        return

    service = await conn.service(_ENV_SENSE_UUID)
    char = await service.characteristic(_TEMP_UUID)
    data = await char.read(timeout_ms=1000)
    print("temperature raw:", data)
    await conn.disconnect()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

async def subscribe_temp(addr="aa:bb:cc:dd:ee:ff"):
    device = aioble.Device(aioble.ADDR_PUBLIC, addr)
    conn = await device.connect(timeout_ms=2000)

    service = await conn.service(_ENV_SENSE_UUID)
    char = await service.characteristic(_TEMP_UUID)
    await char.subscribe(notify=True)   # aioble 自动写 CCCD=0x0001
    while True:
        data = await char.notified(timeout_ms=1000)
        print("notify:", data)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

import aioble
import bluetooth
from micropython import const

_ENV_SENSE_UUID = bluetooth.UUID(0x181A)
_TEMP_UUID = bluetooth.UUID(0x2A6E)
_GENERIC_THERMOMETER = const(768)
_ADV_INTERVAL_US = const(250000)

temp_service = aioble.Service(_ENV_SENSE_UUID)
temp_char = aioble.Characteristic(temp_service, _TEMP_UUID, read=True, notify=True, indicate=True)
aioble.register_services(temp_service)

async def peripheral_loop():
    while True:
        conn = await aioble.advertise(
            _ADV_INTERVAL_US,
            name="temp-sense",
            services=[_ENV_SENSE_UUID],
            appearance=_GENERIC_THERMOMETER,
            manufacturer=(0xabcd, b"1234"),
        )
        print("connected from", conn)
        # 业务循环…
        await conn.disconnected()

1
2
3
4

temp_char.write(b'\x00\x01')                       # 仅本地写
temp_char.write(b'\x00\x01', send_update=True)    # 本地写 + 通知订阅者
temp_char.notify(conn)                              # 用当前值通知指定连接
await temp_char.indicate(conn, timeout_ms=2000)     # 等待 indication 确认；未确认状态可抛 GattError，超时抛 asyncio.TimeoutError

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

// esp32_ble_tracker.h:175
enum class ClientState : uint8_t {
  INIT, DISCONNECTING, IDLE, DISCOVERED,
  CONNECTING, CONNECTED, ESTABLISHED,
};

// esp32_ble_tracker.h:193
enum class ScannerState {
  IDLE, STARTING, RUNNING, FAILED, STOPPING,
};

1
2
3
4
5
6
7
8
9

class ESPBTClient : public ESPBTDeviceListener {
  void set_tracker_state_version(uint8_t *version) { this->tracker_state_version_ = version; }
  void set_state_internal_(ClientState st) {
    this->state_ = st;
    if (this->tracker_state_version_ != nullptr) {
      (*this->tracker_state_version_)++;   // 通知 tracker::loop() 下次重新统计 client 状态
    }
  }
};

1
2
3
4
5
6
7
8
9

class ESPBTDeviceListener {
 public:
  virtual void on_scan_end() {}
  virtual bool parse_device(const ESPBTDevice &device) = 0;        // 高层解析
  virtual bool parse_devices(const BLEScanResult *scan_results, size_t count) { return false; }  // 原始包
  virtual AdvertisementParserType get_advertisement_parser_type() {
    return AdvertisementParserType::PARSED_ADVERTISEMENTS;
  }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

class ESPBTDevice {
  esp_bd_addr_t address_;
  esp_ble_addr_type_t address_type_;
  int rssi_;
  std::string name_;
  std::vector<int8_t> tx_powers_;
  optional<uint16_t> appearance_;
  optional<uint8_t> ad_flag_;
  std::vector<ESPBTUUID> service_uuids_;
  std::vector<ServiceData> manufacturer_datas_;
  std::vector<ServiceData> service_datas_;
  const BLEScanResult *scan_result_;          // 原始包也保留
  void parse_adv_(const uint8_t *payload, uint8_t len);   // 解析 AD Type
  optional<ESPBLEiBeacon> get_ibeacon() const;
};

1
2
3
4
5
6
7
8
9

// bthome_ble.h:15
class BTHomeMiThermometer final : public esp32_ble_tracker::ESPBTDeviceListener, public Component {
  void set_address(uint64_t address);
  void set_bindkey(std::initializer_list<uint8_t> bindkey);
  bool parse_device(const esp32_ble_tracker::ESPBTDevice &device) override;
  bool handle_service_data_(const ServiceData &service_data, const ESPBTDevice &device);
  bool decrypt_bthome_payload_(...) const;
  sensor::Sensor *temperature_, *humidity_, *battery_level_, *battery_voltage_, *signal_strength_;
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

switch (obj_type) {
  case 0x00: /* packet id */         // 1 byte
  case 0x01: /* battery */            // uint8
  case 0x02: /* temperature 0.01C */ // sint16 LE
  case 0x03: /* humidity */           // uint16 LE
  case 0x0C: /* voltage mV */         // uint16
  case 0x12: /* CO2 */                // uint16
  case 0x13: /* TVOC */               // uint16
  ...
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// bluetooth_proxy.h:56
class BluetoothProxy final : public esp32_ble_tracker::ESPBTDeviceListener,
                             public esp32_ble_tracker::BLEScannerStateListener,
                             public Component {
  bool parse_device(const esp32_ble_tracker::ESPBTDevice &device) override;
  bool parse_devices(const esp32_ble::BLEScanResult *scan_results, size_t count) override;
  AdvertisementParserType get_advertisement_parser_type() override;

  void bluetooth_device_request(const api::BluetoothDeviceRequest &msg);
  void bluetooth_gatt_read(const api::BluetoothGATTReadRequest &msg);
  void bluetooth_gatt_write(const api::BluetoothGATTWriteRequest &msg);
  void bluetooth_gatt_read_descriptor(const api::BluetoothGATTReadDescriptorRequest &msg);
  void bluetooth_gatt_write_descriptor(const api::BluetoothGATTWriteDescriptorRequest &msg);
  void bluetooth_gatt_send_services(const api::BluetoothGATTGetServicesRequest &msg);
  void bluetooth_gatt_notify(const api::BluetoothGATTNotifyRequest &msg);
  void bluetooth_set_connection_params(const api::BluetoothSetConnectionParamsRequest &msg);
  ...
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// bluetooth_proxy.h:41
enum BluetoothProxyFeature : uint32_t {
  FEATURE_PASSIVE_SCAN = 1 << 0,
  FEATURE_ACTIVE_CONNECTIONS = 1 << 1,
  FEATURE_REMOTE_CACHING = 1 << 2,
  FEATURE_PAIRING = 1 << 3,
  FEATURE_CACHE_CLEARING = 1 << 4,
  FEATURE_RAW_ADVERTISEMENTS = 1 << 5,
  FEATURE_STATE_AND_MODE = 1 << 6,
  FEATURE_CONNECTION_PARAMS_SETTING = 1 << 7,
};

1
2
3
4
5
6
7

// bluetooth_proxy.cpp:274
void BluetoothProxy::bluetooth_gatt_read(const api::BluetoothGATTReadRequest &msg) {
  // 1. 找到 address 对应的 BluetoothConnection 槽位
  // 2. 通过它发 esp_ble_gattc_read_char(...)
  // 3. 在 gattc_event_handler 收到 ESP_GATTC_READ_CHAR_EVT 时
  //    把 value 回封 api::BluetoothGATTReadResult 推给 HA
}

1
2

// bluetooth_connection.h:11
class BluetoothConnection final : public esp32_ble_client::BLEClientBase { ... };

1
2
3
4
5
6

// esp32_ble_tracker.h:218
enum class ConnectionType : uint8_t {
  V1,                  // 全程保留 services 在内存
  V3_WITH_CACHE,       // 客户端已有缓存，不重复拉取
  V3_WITHOUT_CACHE,    // 拉一次发完即丢，节省内存
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// bluetooth_proxy.cpp:143
esp32_ble_tracker::AdvertisementParserType BluetoothProxy::get_advertisement_parser_type() {
  return esp32_ble_tracker::AdvertisementParserType::RAW_ADVERTISEMENTS;
}

// bluetooth_proxy.cpp:73
bool BluetoothProxy::parse_device(const esp32_ble_tracker::ESPBTDevice &device) {
  // This method should never be called since bluetooth_proxy always uses raw advertisements
  // but we need to provide an implementation to satisfy the virtual method requirement
  return false;
}

// bluetooth_proxy.cpp:80
bool BluetoothProxy::parse_devices(const esp32_ble::BLEScanResult *scan_results, size_t count) {
  if (!api::global_api_server->is_connected() || this->api_connection_ == nullptr)
    return false;

  auto &advertisements = this->response_.advertisements;

  for (size_t i = 0; i < count; i++) {
    auto &result = scan_results[i];
    uint8_t length = result.adv_data_len + result.scan_rsp_len;

    // Fill in the data directly at current position
    auto &adv = advertisements[this->response_.advertisements_len];
    adv.address = esp32_ble::ble_addr_to_uint64(result.bda);
    adv.rssi = result.rssi;
    adv.address_type = result.ble_addr_type;
    adv.data_len = length;
    std::memcpy(adv.data, result.ble_adv, length);   // ← 原始 adv+scan_resp 字节流，零解析
    this->response_.advertisements_len++;
    ...
  }
  return true;
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

ESPHome bluetooth_proxy (raw adv bytes)
   │  via aioesphomeapi / bleak_esphome
   ▼
bleak_esphome.connect_scanner(...) 创建的 ESPHomeScanner
   │  在 HA core 中通过 esphome/bluetooth.py 注册
   ▼
homeassistant.components.bluetooth.api.async_register_scanner(...)
   ▼
homeassistant.components.bluetooth.manager.HomeAssistantBluetoothManager
   │  async_register_hass_scanner(...) 接入 scanner pipeline
   ▼
HomeAssistantBluetoothManager._discover_service_info(service_info)
   │  _integration_matcher.match_domains(service_info)  ← 用各集成 manifest.json 的 "bluetooth" 规则做 discovery 匹配
   │  _callback_index.match_callbacks(service_info)      ← 已注册设备/协调器的运行时 callback
   ▼
两条分发路径：
   ├─→ callback(service_info, BluetoothChange.ADVERTISEMENT)   ← 给已注册设备（bthome/xiaomi/atc 等 coordinator）
   └─→ discovery_flow.async_create_flow(domain, ..., service_info)  ← 触发新设备发现流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

matched_domains = self._integration_matcher.match_domains(service_info)
...
for match in self._callback_index.match_callbacks(service_info):
    callback = match[CALLBACK]
    try:
        callback(service_info, BluetoothChange.ADVERTISEMENT)   # 推给具体集成
    except Exception:
        _LOGGER.exception("Error in bluetooth callback")

if not matched_domains:
    return  # avoid creating DiscoveryKey if there are no matches

discovery_key = discovery_flow.DiscoveryKey(domain=DOMAIN, key=service_info.address, version=1)
for domain in matched_domains:
    discovery_flow.async_create_flow(
        self.hass, domain,
        {"source": config_entries.SOURCE_BLUETOOTH},
        service_info,
        discovery_key=discovery_key,
    )

1
2
3
4
5
6

# homeassistant/components/bluetooth/models.py:6-10
from home_assistant_bluetooth import BluetoothServiceInfoBleak

BluetoothChange = Enum("BluetoothChange", "ADVERTISEMENT")           # 唯一事件：收到广播
type BluetoothCallback = Callable[[BluetoothServiceInfoBleak, BluetoothChange], None]
type ProcessAdvertisementCallback = Callable[[BluetoothServiceInfoBleak], bool]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# homeassistant/components/bthome/__init__.py:76
def process_service_info(
    hass: HomeAssistant,
    entry: BTHomeConfigEntry,
    device_registry: DeviceRegistry,
    service_info: BluetoothServiceInfoBleak,
) -> SensorUpdate:
    """Process a BluetoothServiceInfoBleak."""
    coordinator = entry.runtime_data
    data = coordinator.device_data
    update = data.update(service_info)
    ...
    return update

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

# homeassistant/components/esphome/bluetooth.py
from bleak_esphome import connect_scanner

@hass_callback
def async_connect_scanner(hass, entry, entry_data, cli, device_info, device_id):
    """Connect scanner."""
    client_data = connect_scanner(cli, device_info, entry_data.available)   # ← 桥接器
    scanner = client_data.scanner                                             # ESPHomeScanner 实例
    feature_flags = device_info.bluetooth_proxy_feature_flags_compat(api_version)
    state_and_mode = bool(feature_flags & BluetoothProxyFeature.FEATURE_STATE_AND_MODE)
    ...
    callbacks = [
        async_register_scanner(                                              # ← 注册进 HA BluetoothManager
            hass, scanner,
            source_domain=DOMAIN,
            source_model=device_info.model,
            source_config_entry_id=entry_data.entry_id,
            source_device_id=device_id,
        ),
        scanner.async_setup(),
    ]

1
2
3
4
5
6
7
8

custom_components/foo_ble/
├── manifest.json
├── const.py
├── config_flow.py
├── __init__.py
├── coordinator.py
├── sensor.py
└── button.py          # 可选：触发 GATT 配置写入

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "domain": "foo_ble",
  "name": "Foo BLE",
  "codeowners": ["@yourhandle"],
  "config_flow": true,
  "dependencies": ["bluetooth"],
  "bluetooth": [
    {
      "connectable": true,
      "service_data_uuid": "0000fff0-0000-1000-8000-00805f9b34fb"
    }
  ],
  "requirements": []
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# custom_components/foo_ble/config_flow.py
from homeassistant import config_entries
from homeassistant.components.bluetooth import BluetoothServiceInfoBleak

from .const import DOMAIN

class FooBleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
    VERSION = 1

    async def async_step_bluetooth(
        self, discovery_info: BluetoothServiceInfoBleak
    ):
        address = discovery_info.address
        await self.async_set_unique_id(address)
        self._abort_if_unique_id_configured()

        # 这里可以解析 service_info.service_data / manufacturer_data 判断型号
        self.context["title_placeholders"] = {"name": discovery_info.name or address}
        return self.async_create_entry(
            title=discovery_info.name or address,
            data={"address": address},
        )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

# custom_components/foo_ble/__init__.py
from bleak import BleakClient, BleakError

from homeassistant.components import bluetooth
from homeassistant.components.bluetooth.match import ADDRESS, BluetoothCallbackMatcher
from homeassistant.const import Platform
from homeassistant.core import HomeAssistant, callback
from homeassistant.exceptions import ConfigEntryNotReady

from .const import DOMAIN
from .coordinator import FooBleCoordinator

PLATFORMS = [Platform.SENSOR, Platform.BUTTON]

async def async_setup_entry(hass: HomeAssistant, entry):
    address = entry.data["address"]

    # 若启动时还没见过广播，可以等下一次 callback；若必须立即连接，
    # 可像 ld2410_ble 一样先 async_ble_device_from_address(..., connectable=True)。
    ble_device = bluetooth.async_ble_device_from_address(hass, address, connectable=True)
    if ble_device is None:
        raise ConfigEntryNotReady(f"{address} not reachable by a connectable scanner")

    coordinator = FooBleCoordinator(hass, entry, ble_device)
    entry.runtime_data = coordinator

    @callback
    def _async_update_ble(service_info, change):
        coordinator.async_handle_advertisement(service_info)

    entry.async_on_unload(
        bluetooth.async_register_callback(
            hass,
            _async_update_ble,
            BluetoothCallbackMatcher({ADDRESS: address}),
            bluetooth.BluetoothScanningMode.ACTIVE,
        )
    )

    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
    return True

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# custom_components/foo_ble/coordinator.py
import asyncio
from bleak import BleakClient, BleakError

from homeassistant.components import bluetooth
from homeassistant.core import HomeAssistant, callback
from homeassistant.helpers.update_coordinator import DataUpdateCoordinator

FOO_SERVICE_UUID = "0000fff0-0000-1000-8000-00805f9b34fb"
FOO_CONFIG_CHAR_UUID = "0000fff2-0000-1000-8000-00805f9b34fb"

class FooBleCoordinator(DataUpdateCoordinator):
    def __init__(self, hass: HomeAssistant, entry, ble_device):
        super().__init__(hass, None, name=entry.title)
        self.entry = entry
        self.ble_device = ble_device
        self.state = {}
        self._configure_task: asyncio.Task | None = None

    @callback
    def async_handle_advertisement(
        self, service_info: bluetooth.BluetoothServiceInfoBleak
    ) -> None:
        self.ble_device = service_info.device

        # 解析 ESPHome proxy 转来的广播：service_data / manufacturer_data / rssi / name 等
        self.state.update(parse_foo_advertisement(service_info))
        self.async_set_updated_data(self.state)

        if self.state.get("needs_configure") and self._configure_task is None:
            self._configure_task = self.hass.async_create_task(self.async_configure())

    async def async_configure(self) -> None:
        try:
            async with BleakClient(self.ble_device) as client:
                await client.write_gatt_char(FOO_CONFIG_CHAR_UUID, b"\x01\x02", response=True)
                raw = await client.read_gatt_char(FOO_CONFIG_CHAR_UUID)
        except BleakError as exc:
            self.logger.warning("GATT configure failed for %s: %s", self.ble_device.address, exc)
            return
        finally:
            self._configure_task = None

        self.state["config_value"] = bytes(raw)
        self.state["needs_configure"] = False
        self.async_set_updated_data(self.state)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

// ble_client_base.h:26
class BLEClientBase : public espbt::ESPBTClient, public Component {
  void setup() override; void loop() override;
  bool parse_device(const espbt::ESPBTDevice &device) override;   // 等到匹配 mac 才 connect
  bool gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
                           esp_ble_gattc_cb_param_t *param) override;
  void gap_event_handler(...) override;
  void connect() override; void disconnect() override;
  void unconditional_disconnect();
  void release_services();

  bool connected() { return this->state() == espbt::ClientState::ESTABLISHED; }

  BLEService *get_service(espbt::ESPBTUUID uuid);
  BLECharacteristic *get_characteristic(espbt::ESPBTUUID service, espbt::ESPBTUUID chr);
  BLEDescriptor *get_descriptor(...);
  BLEDescriptor *get_config_descriptor(uint16_t handle);   // 找 CCCD

  void set_address(uint64_t address);   // 把 uint64 拆成 esp_bd_addr_t
  void set_remote_addr_type(esp_ble_addr_type_t);
  uint16_t get_conn_id() const { return this->conn_id_; }
  int get_gattc_if() const { return this->gattc_if_; }
};

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

void set_idle_() {
  this->set_state(espbt::ClientState::IDLE);
  this->conn_id_ = UNSET_CONN_ID;
}

void set_disconnecting_() {
  this->disconnecting_started_ = millis();
  this->set_state(espbt::ClientState::DISCONNECTING);
  this->enable_loop();   // 让 loop() 能跑 10s 安全超时
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

ble_client:
  - mac_address: AA:BB:CC:DD:EE:FF
    id: mybeacon

sensor:
  - platform: ble_client
    ble_client_id: mybeacon
    name: "Beacon Temperature"
    type: characteristic
    service_uuid: "181A"
    characteristic_uuid: "2A6E"
    notify: true        # 订阅 notify
    update_interval: 60s

1
2
3
4
5

class BLESensor : public sensor::Sensor, public PollingComponent, public BLEClientNode {
  void gattc_event_handler(esp_gattc_cb_event_t, esp_gatt_if_t, esp_ble_gattc_cb_param_t *) override;
  void update() override;             // 周期 esp_ble_gattc_read_char
  void set_enable_notify(bool n) { this->notify_ = n; }
};

1
2
3
4
5

custom_components/foo_beacon/
├── __init__.py         # Python 配置入口（注册 COMPONENT_SCHEMA）
├── foo_beacon.h        # C++ 头文件
├── foo_beacon.cpp      # C++ 实现
└── sensor.py           # 注册 sensor 平台

1
2
3
4
5

# custom_components/foo_beacon/__init__.py
import esphome.codegen as cg

CODEOWNERS = ["@yourhandle"]
foo_beacon_ns = cg.esphome_ns.namespace("foo_beacon")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

# custom_components/foo_beacon/sensor.py
import esphome.codegen as cg
import esphome.config_validation as cv
from esphome.components import ble_client, sensor
from esphome.const import (
    CONF_ID, UNIT_CELSIUS,
    STATE_CLASS_MEASUREMENT, DEVICE_CLASS_TEMPERATURE,
)

from . import foo_beacon_ns

CONF_TEMPERATURE = "temperature"
CONF_BATTERY = "battery"

FooBeaconSensor = foo_beacon_ns.class_(
    "FooBeaconSensor", sensor.Sensor, cg.PollingComponent, ble_client.BLEClientNode
)

CONFIG_SCHEMA = (
    sensor.sensor_schema(
        unit_of_measurement=UNIT_CELSIUS,
        accuracy_decimals=2,
        device_class=DEVICE_CLASS_TEMPERATURE,
        state_class=STATE_CLASS_MEASUREMENT,
    )
    .extend(
        {
            cv.GenerateID(): cv.declare_id(FooBeaconSensor),
        }
    )
    .extend(cv.polling_component_schema("60s"))
    .extend(ble_client.BLE_CLIENT_SCHEMA)
)

async def to_code(config):
    var = cg.new_Pvariable(config[CONF_ID])
    await cg.register_component(var, config)
    await sensor.register_sensor(var, config)
    await ble_client.register_ble_node(var, config)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// custom_components/foo_beacon/foo_beacon.h
#pragma once

#ifdef USE_ESP32

#include "esphome/core/component.h"
#include "esphome/components/ble_client/ble_client.h"
#include "esphome/components/esp32_ble_tracker/esp32_ble_tracker.h"
#include "esphome/components/sensor/sensor.h"

#include <esp_gattc_api.h>

namespace esphome::foo_beacon {

namespace espbt = esphome::esp32_ble_tracker;

// 信标约定的 Service / Characteristic UUID（16-bit 0xFFF0/0xFFF1 展开为 128-bit）
static constexpr uint16_t FOO_SERVICE_UUID16 = 0xFFF0;
static constexpr uint16_t FOO_CHAR_NOTIFY_UUID16 = 0xFFF1;

class FooBeaconSensor : public sensor::Sensor,
                        public PollingComponent,
                        public ble_client::BLEClientNode {
 public:
  void setup() override;
  void loop() override;
  void update() override;            // PollingComponent 周期触发
  void gattc_event_handler(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if,
                           esp_ble_gattc_cb_param_t *param) override;
  void dump_config() override;

  // 当前 BLEClientNode 没有 node_connected()；连接后初始化在 gattc_event_handler()
  // 的 ESP_GATTC_SEARCH_CMPL_EVT 分支中完成。

 protected:
  void handle_frame_(const uint8_t *data, size_t len);   // 解析 [seq,t_lo,t_hi,bat]

  uint16_t char_handle_{0};   // notify 特征句柄，发现时填
  bool subscribed_{false};
};

}  // namespace esphome::foo_beacon

#endif  // USE_ESP32

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

// custom_components/foo_beacon/foo_beacon.cpp
#include "foo_beacon.h"

#ifdef USE_ESP32

#include "esphome/components/esp32_ble_client/ble_client_base.h"
#include "esphome/core/log.h"

#include <esp_gattc_api.h>
#include <cstring>

namespace esphome::foo_beacon {

static const char *const TAG = "foo_beacon";

void FooBeaconSensor::dump_config() {
  ESP_LOGCONFIG(TAG, "FooBeacon Sensor:");
  ESP_LOGCONFIG(TAG, "  Service: 0x%04X", FOO_SERVICE_UUID16);
  ESP_LOGCONFIG(TAG, "  Char:    0x%04X", FOO_CHAR_NOTIFY_UUID16);
  LOG_UPDATE_INTERVAL(this);
}

void FooBeaconSensor::setup() {
  this->node_state = espbt::ClientState::IDLE;
}

void FooBeaconSensor::loop() {
  // Parent BLEClientNode 有 loop()，本组件依赖 polling update() 和 GATT 回调即可。
  this->disable_loop();
}

void FooBeaconSensor::update() {
  // 仅当 node 自己完成 service/notify 初始化后才主动读一次（轮询模式）
  auto *client = this->parent();   // ble_client::BLEClient *
  if (client == nullptr || this->node_state != espbt::ClientState::ESTABLISHED)
    return;

  if (this->char_handle_ != 0) {
    esp_ble_gattc_read_char(client->get_gattc_if(), client->get_conn_id(),
                            this->char_handle_, ESP_GATT_AUTH_REQ_NONE);
  }
}

void FooBeaconSensor::gattc_event_handler(esp_gattc_cb_event_t event,
                                           esp_gatt_if_t gattc_if,
                                           esp_ble_gattc_cb_param_t *param) {
  auto *client = this->parent();
  if (client == nullptr) return;
  if (gattc_if != client->get_gattc_if()) return;   // 不是我的接口

  switch (event) {
    case ESP_GATTC_SEARCH_CMPL_EVT: {
      ESP_LOGI(TAG, "Connected, discovering FOO service 0x%04X", FOO_SERVICE_UUID16);

      espbt::ESPBTUUID svc = espbt::ESPBTUUID::from_uint16(FOO_SERVICE_UUID16);
      espbt::ESPBTUUID chr = espbt::ESPBTUUID::from_uint16(FOO_CHAR_NOTIFY_UUID16);

      auto *characteristic = client->get_characteristic(svc, chr);
      if (characteristic == nullptr) {
        ESP_LOGW(TAG, "FOO characteristic not found, disconnecting");
        client->disconnect();
        return;
      }
      this->char_handle_ = characteristic->handle;

      auto status = esp_ble_gattc_register_for_notify(client->get_gattc_if(), client->get_remote_bda(),
                                                      characteristic->handle);
      if (status) {
        ESP_LOGW(TAG, "esp_ble_gattc_register_for_notify failed, status=%d", status);
      }
      break;
    }
    case ESP_GATTC_REG_FOR_NOTIFY_EVT: {
      if (param->reg_for_notify.handle != this->char_handle_) return;
      if (param->reg_for_notify.status != ESP_GATT_OK) {
        ESP_LOGW(TAG, "Error registering for notifications at handle %d, status=%d",
                 param->reg_for_notify.handle, param->reg_for_notify.status);
        return;
      }
      // 非 V3 模式下，BLEClientBase 会在 REG_FOR_NOTIFY_EVT 里查找 CCCD 并写入 notify enable。
      this->subscribed_ = true;
      this->node_state = espbt::ClientState::ESTABLISHED;
      ESP_LOGI(TAG, "Registered FOO notify (handle=%u)", this->char_handle_);
      break;
    }
    case ESP_GATTC_NOTIFY_EVT: {
      if (param->notify.handle != this->char_handle_) return;
      this->handle_frame_(param->notify.value, param->notify.value_len);
      break;
    }
    case ESP_GATTC_READ_CHAR_EVT: {
      if (param->read.handle != this->char_handle_) return;
      if (param->read.status == ESP_GATT_OK)
        this->handle_frame_(param->read.value, param->read.value_len);
      break;
    }
    case ESP_GATTC_DISCONNECT_EVT:
      this->subscribed_ = false;
      this->char_handle_ = 0;
      this->node_state = espbt::ClientState::IDLE;
      break;
    default:
      break;
  }
}

void FooBeaconSensor::handle_frame_(const uint8_t *data, size_t len) {
  if (len < 4) {
    ESP_LOGW(TAG, "frame too short: %u", len);
    return;
  }
  // [seq, temp_lo, temp_hi, bat]
  int16_t temp_raw = (int16_t)((data[2] << 8) | data[1]);
  float temp_c = temp_raw / 100.0f;
  uint8_t bat = data[3];

  this->publish_state(temp_c);
  ESP_LOGD(TAG, "seq=%u temp=%.2f°C bat=%u%%", data[0], temp_c, bat);
}

}  // namespace esphome::foo_beacon

#endif  // USE_ESP32

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 把 external_components 引入本地路径
external_components:
  - source:
      type: local
      path: custom_components

esp32:
  board: esp32dev
  framework:
    type: esp-idf     # 推荐用 ESP-IDF 而非 Arduino，BLE 更稳定

esp32_ble_tracker:
  scan_parameters:
    interval: 30ms
    window: 30ms
    active: true

ble_client:
  - mac_address: AA:BB:CC:DD:EE:FF
    id: my_foo_beacon

sensor:
  - platform: foo_beacon
    ble_client_id: my_foo_beacon
    name: "FooBeacon Temperature"
    update_interval: 60s
    # 本最小示例只把温度作为 sensor 发布；bat 字段在 C++ 中仅记录日志