ManagerBLE
homey.manager.ble
Manages Bluetooth Low Energy communication.
You can access this manager through the Homey instance as self.homey.ble.
Ancestors
- Manager
- SimpleClass
- homey.util.event_emitter.EventEmitter
- typing.Generic
- abc.ABC
Methods
discover
async def discover(self, service_filter: list[str] | None = None) ‑> tuple[BleAdvertisement, ...]Discover BLE peripherals for a certain time.
Requires the homey:wireless:ble permission.
For more information about permissions read the Permissions tutorial.
Args
| Name | Type | Description |
|---|---|---|
service_filter |
list[str] | None | A collection of service UUIDs the peripheral should expose. |
Returns
A tuple of BLE advertisements, filtered by the service filter if given.
find
async def find(self, peripheral_uuid: str) ‑> BleAdvertisementFind a BLE peripheral with the given UUID.
Requires the homey:wireless:ble permission.
For more information about permissions read the Permissions tutorial.
Args
peripheral_uuid:
Returns
The BLE advertisement of the peripheral.
Raises
NotFound- Raised if no peripheral with the given UUID is found.
subscribe_to_advertisements
async def subscribe_to_advertisements(self,peripheral_uuid: str,
callback: Callable[[m_ble_advertisement.BleAdvertisement], None],
rate_limit_ms: int = 1000) ‑> None
Subscribe to BLE advertisements from a specific peripheral.
The callback is called with a BleAdvertisement
instance whenever a new advertisement is received from the peripheral.
The same instance is reused and updated in place across broadcasts.
Does not require a GATT connection — uses passive BLE scanning.
Requires the homey:wireless:ble permission.
For more information about permissions read the Permissions tutorial.
Not all Homey models support this. Check support with
homey.has_feature("ble-advertisements") before calling.
Only one callback can be active per peripheral; subscribing again replaces the previous callback.
Args
| Name | Type | Description |
|---|---|---|
peripheral_uuid |
str | The UUID of the peripheral to subscribe to. |
callback |
Callable[[m_ble_advertisement.BleAdvertisement], None] | A callback that receives the updated advertisement. |
rate_limit_ms |
int | Minimum interval between delivered advertisements, in ms. |
unsubscribe_from_advertisements
async def unsubscribe_from_advertisements(self, peripheral_uuid: str) ‑> NoneUnsubscribe from BLE advertisements from a specific peripheral.