Device

homey.device

A device paired in Homey. It should be extended and exported from device.py as homey_export, or any custom class as returned in Driver#on_map_device_class.

Example

from homey.device import Device

class MyDevice(Device):
    """My Homey device"""

    async def on_init(self):
        self.register_capability_listener("onoff", self.on_onoff)

    async def on_onoff(self, value: bool, **kwargs):
        """Turn the device on or off."""

homey_export = MyDevice

This class must not be initialized by the developer, but is instantiated by Homey after being added by a user.

Ancestors

SimpleClass
homey.util.event_emitter.EventEmitter
typing.Generic

Instance variables

driver

var driver : Final[Driver]

homey

var homey : Final[Homey]

Methods

on_init

async def on_init(self) ‑> None

This method is called when the device is loaded, and properties such as data, settings, and capabilities 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 the device is unloaded. 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 device is ready, meaning Device.on_init() has been run.

on_added

async def on_added(self) ‑> None

This method is called when the device is added by a user.

This method is expected to be overridden.

on_deleted

async def on_deleted(self) ‑> None

This method is called when the device is removed by a user.

This method is expected to be overridden.

get_capability_value

def get_capability_value(self, id: str) ‑> bool | float | str | None

Get the current value of the capability with the given ID.

Raises

NotFound

set_capability_value

async def set_capability_value(self, id: str, value: bool | float | str | None) ‑> None

Set the value of the capability with the given ID.

Raises

NotFound

get_state

def get_state(self) ‑> mappingproxy[str, bool | float | str | None]

Get the state of all capabilities of this device.

has_capability

def has_capability(self, id: str) ‑> bool

Get whether the device has the capability with the given ID.

register_capability_listener

def register_capability_listener(self,
capability_id: str,
listener: CapabilityListener[Value]) ‑> None

Args

Name	Type	Description
`listener`	CapabilityListener[Value]	An async listener for when a capability value is changed. It receives the new value, as well as any optional arguments, such as duration.

register_multiple_capability_listener

def register_multiple_capability_listener(self,
capability_ids: list[str],
listener: MultipleCapabilityListener[MultipleValues],
debounce_timeout: int = 250) ‑> None

Args

Name	Type	Description
`listener`	MultipleCapabilityListener[MultipleValues]	An async listener for multiple capabilities at once. It receives a mapping containing from each capability to its new value, as well as a mappings containing any optional arguments, such as duration, for each capability.
`debounce_timeout`	int	For how many milliseconds value changes are debounced before calling the listener.

trigger_capability_listener

async def trigger_capability_listener(self, capability_id: str, value: bool | float | str | None, **kwargs) ‑> None

Trigger the capability listener registered to the given capability with the given value and any keyword arguments. Also updates the capability's value.

add_capability

async def add_capability(self, id: str) ‑> None

Add a capability to this device.

Note: this is an expensive method so use it only when needed.

remove_capability

async def remove_capability(self, id: str) ‑> None

Remove the capability with the given ID from this device.

Note: Any flow that depends on this capability will become broken. This is an expensive method so use it only when needed.

get_capabilities

def get_capabilities(self) ‑> tuple[str, ...]

get_capability_options

def get_capability_options(self, id: str) ‑> mappingproxy[str, typing.Any]

Get the current options configuration of the capability with the given ID.

Raises

NotFound

set_capability_options

async def set_capability_options(self, id, options: dict[str, Any]) ‑> None

Set the options configuration of the capability with the given ID.

Note: this is an expensive method so use it only when needed.

Raises

NotFound

on_settings

This method is called when the settings of the device are change in Homey by a user, so that they can be synchronized with the device or a bridge.

This method is expected to be overridden.

Args

Name	Type	Description
`old_settings`	dict[str, bool \| float \| str \| None]	The settings object before the changes.
`new_settings`	dict[str, bool \| float \| str \| None]	The settings object after the changes.
`changed_keys`	tuple[str, ...]	The keys of the settings that were changed.

Returns

A custom message that will be displayed to the user, or None if no message should be shown.

get_setting

def get_setting(self, key: str) ‑> bool | float | str | None

Get the value of the setting with the given key.

get_settings

def get_settings(self) ‑> mappingproxy[str, bool | float | str | None]

Get the settings object of this device.

set_settings

async def set_settings(self, settings: dict[str, bool | float | str | None]) ‑> None

Update the settings object of the device. The given settings may be a subset of the settings defined for the device.

Note: the Device.on_settings() method will not be called when the settings are changed programmatically.

get_id

def get_id(self) ‑> str

Get the ID assigned to this device by Homey.

get_data

def get_data(self) ‑> mappingproxy[str, typing.Any]

Get the data object of this device.

get_store

def get_store(self) ‑> mappingproxy[str, typing.Any]

Get the store object of this device.

set_store_value

async def set_store_value(self, key: str, value: Any) ‑> None

Set the value for the given key in the store object of the device.

unset_store_value

async def unset_store_value(self, key: str) ‑> None

Remove the given key from the store object of the device.

set_album_art_image

async def set_album_art_image(self, image: Image) ‑> None

Set the album art used for this device.

set_camera_image

async def set_camera_image(self, id: str, title: str, image: Image) ‑> None

Set the camera image for this device.

Args

Name	Type	Description
`id`	str	Unique identifier of the image, e.g. `front`.
`title`	str	Title of the image used in the UI, e.g. `Front Camera`.

set_camera_video

async def set_camera_video(self, id: str, title: str, video: Video) ‑> None

Set the camera video for this device.

Args

Name	Type	Description
`id`	str	Unique identifier of the video, e.g. `front`.
`title`	str	Title of the video used in the UI, e.g. `Front Camera`.

get_energy

def get_energy(self) ‑> mappingproxy[str, typing.Any]

Get the energy configuration of this device.

set_energy

async def set_energy(self, energy: dict[str, Any]) ‑> None

Set the energy configuration of this device.

get_available

def get_available(self) ‑> bool

Get whether the device is marked as available.

set_unavailable

async def set_unavailable(self, message: str | None = None) ‑> None

Mark the device as unavailable.

Args

Name	Type	Description
`message`	str \| None	A message to display to the user, or None if the default message should be shown.

set_available

async def set_available(self) ‑> None

Mark this device as available.

set_warning

async def set_warning(self, message: str | None = None) ‑> None

Set a warning message for this device, to be shown to the user. This message is persistent, so make sure to unset it when necessary.

Args

Name	Type	Description
`message`	str \| None	The message to display to the user, or None to show no message.

unset_warning

async def unset_warning(self) ‑> None

Remove the warning message for this device.

get_class

def get_class(self) ‑> str

Get the Homey device class of this device.

set_class

async def set_class(self, device_class: str) ‑> None

Set the Homey device class of this device.

get_name

def get_name(self) ‑> str

Get the name of the device in Homey.

on_renamed

async def on_renamed(self, name: str) ‑> None

This method is called when the device is renamed in Homey by a user, so that the name can be synchronized with the device or a bridge.

This method is expected to be overridden.

set_last_seen_at

async def set_last_seen_at(self) ‑> None

Set when the device has last been seen. This method should be called if the device is known to be alive and responding.

on_discovery_result

async def on_discovery_result(self, discovery_result: DiscoveryResult) ‑> bool

This method is called when a device has been discovered to check whether it is this device. By default, the method will compare this and the discovered device's data.id property.

This method is expected to be overridden.

Args

Name	Type	Description
`discovery_result`	DiscoveryResult	A possible `DiscoveryResult` for this device.

Returns

Whether the discovery result is for this device.

on_discovery_available

async def on_discovery_available(self, discovery_result: DiscoveryResult) ‑> None

This method is called when a discovery result matching this device is found, in order to set up a connection with the device. Raising an exception here will make the device unavailable with the exception's message.

This method is expected to be overridden.

Args

Name	Type	Description
`discovery_result`	DiscoveryResult	The `DiscoveryResult` for this device.

on_discovery_last_seen_changed

async def on_discovery_last_seen_changed(self, discovery_result: DiscoveryResult) ‑> None

This method is called when the device has been found again.

This method is expected to be overridden.

Args

Name	Type	Description
`discovery_result`	DiscoveryResult	The `DiscoveryResult` for this device.

on_discovery_address_changed

async def on_discovery_address_changed(self, discovery_result: DiscoveryResult) ‑> None

This method is called when the device was found again at a different address.

This method is expected to be overridden.

Args

Name	Type	Description
`discovery_result`	DiscoveryResult	The `DiscoveryResult` for this device.

Inherited members

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

CapabilityListener

class CapabilityListener

A listener for when a capability value is changed. It receives the new value, as well as any optional arguments, such as duration.

If an exception is raised, the capability value will not be changed and the error message will be shown to the user.

For example:

listener(0.8, duration=300)

Ancestors

typing.Protocol
typing.Generic

Methods

call

async def __call__(self, value: ValueType, **kwargs: Any) ‑> None

Call self as a function.

MultipleCapabilityListener

class MultipleCapabilityListener

A listener for multiple capabilities at once. It receives a mapping from each capability to its new value, as well as a mappings containing any optional arguments, such as duration, for each capability.

If an exception is raised, the capability values will not be changed and the error message will be shown to the user.

For example:

listener({"onoff": True, "dim": 0.8}, dim={"duration": 300})

Ancestors

typing.Protocol
typing.Generic

Methods

call

async def __call__(self, values: MultipleValuesType, **kwargs: dict[str, Any]) ‑> None

Call self as a function.