Driver

homey.driver

The Driver class manages all Device instances, which represent all paired devices. This class should be extended and exported as homey_export from driver.py.

Example

from homey.driver import Driver, ListDeviceProperties

class MyDriver(Driver):
    async def on_pair_list_devices(self):
        api_devices = await get_api_devices()
        pair_devices: list[ListDeviceProperties] = [
            {"data": {"id": api_device.id}}
            for api_device in api_devices
            if api_device.type == 5
        ]
        return pair_devices

homey_export = MyDriver

This class must not be initialized by the developer, but is instantiated when starting the app.

Ancestors

SimpleClass
homey.util.event_emitter.EventEmitter
typing.Generic

Instance variables

homey

var homey : Final[Homey]

manifest

var manifest : Final[Any]

The app.json manifest of this driver.

id

var id : Final[str]

Methods

on_init

async def on_init(self) ‑> None

This method is called when the driver is loaded, and properties such as its devices are available. It can be used for setup.

This method is expected to be overridden.

on_uninit

async def on_uninit(self) ‑> None

This method is called when unloading the driver. It can be used for cleanup.

This method is expected to be overridden.

ready

async def ready(self) ‑> None

Get an awaitable that is resolved when the driver is ready, meaning Driver#on_init has been run.

on_pair

async def on_pair(self, session: PairSession) ‑> None

This method is called when a pairing session is started. It can be used to hook into the pairing flow.

This method can be overridden, with the default implementation supporting the standard pairing flow.

Args

Name	Type	Description
`session`	PairSession	The `PairSession` that is starting.

on_repair

async def on_repair(self, session: PairSession, device: Device | None = None) ‑> None

This method is called when a re-pairing session is started. It can be used to hook into the pairing flow.

This method can be overridden, with the default implementation supporting the standard re-pairing flow.

Args

Name	Type	Description
`session`	PairSession	The `PairSession` that is starting.
`device`	Device \| None	The `Device` that is being re-paired.

on_unpair

async def on_unpair(self, session: PairSession, device: Device | None = None) ‑> None

This method is called when an unpairing session is started. It can be used to hook into the pairing flow.

This method can be overridden, with the default implementation supporting the standard unpairing flow.

Args

Name	Type	Description
`session`	PairSession	The `PairSession` that is starting.
`device`	Device \| None	The `Device` that is being unpaired.

on_pair_list_devices

async def on_pair_list_devices(self, view_data) ‑> list[ListDeviceProperties]

This method is called when a pairing session is started and the default on_pair implementation has not been overridden. It can be used to get a list of devices to pair the user can choose from.

This method is expected to be overridden.

Args

Name	Type	Description
`view_data`		Data from the pairing view that requested the list of devices.

Returns

A tuple with device descriptions, which are used in the rest of the default pairing flow.

on_map_device_class

async def on_map_device_class(self,
device: ListDeviceProperties) ‑> type[~Device]

This method is called when initializing a device to determine which class to construct it with.

This method is expected to be overridden.

Example:

from homey.driver import Driver
from device import MyDevice, MyDimDevice

class MyDriver(Driver):
    def on_map_device_class(self, device):
        return MyDimDevice if device.has_capability("dim") else MyDevice

Args

Name	Type	Description
`device`	ListDeviceProperties	The properties of the device, which can be used to determine which class to use.

get_device

def get_device(self, device_data: dict[str, Any]) ‑> ~Device

Get a device belonging to this driver that matches the given data.

Raises

NotFound

get_device_by_id

def get_device_by_id(self, device_id: str) ‑> ~Device

Get a device belonging to this driver by the ID assigned by Homey.

Raises

NotFound:

get_devices

def get_devices(self) ‑> tuple[~Device, ...]

Get all devices belonging to this driver.

get_discovery_strategy

def get_discovery_strategy(self) ‑> DiscoveryStrategy | None

Get the discovery strategy for this driver, as defined in app.json.

Inherited members

SimpleClass:
- debug
- error
- log
- on_debug
- on_error
- on_log

ListDeviceProperties

class ListDeviceProperties

The properties of a device shown in the pairing screen. Only the data object is required.

Ancestors

builtins.dict

Instance variables

data

var data : dict[str, typing.Any]

The immutable data of this device. By default data.id is used to distinguish between devices.

store

var store : dict[str, typing.Any]

Mutable data of this device that should persist.

settings

var settings : dict[str, bool | float | str | None]

A mapping from setting IDs to the initial value of the setting for this particular device.

capabilities

var capabilities : list[str]

The capabilities of this particular device.

capabilitiesOptions

var capabilitiesOptions : dict[str, dict[str, typing.Any]]

A mapping from capability IDs to options for the capability of this particular device.

name

var name : str

The name of the device to be used in the UI.

icon

var icon : str

The filename of the icon for the device to be used in the UI.