Devices (yombo.lib.devices.__init__)


The devices library is primarily responsible for:

  • Keeping track of all devices.

  • Maintaining device state.

  • Routing commands to modules for processing.

  • Managing delay commands to send later.

The device (singular) class represents one device. This class has many functions that help with utilizing the device. When possible, this class should be used for controlling devices and getting/setting/querying status. The device class maintains the current known device state. Any changes to the device state are periodically saved to the local database.

To send a command to a device is simple.


# Three ways to send a command to a device. Going from easiest method, but less assurance of correct command
# to most assurance.

# Lets turn on every device this module manages.
for device in self._Devices:

# Lets turn off every every device, using a very specific command id.
for device in self._Devices:
    self.Devices[device].command(command="js83j9s913")  # Made up id, but can be same as off

# Turn off the christmas tree.
self._Devices.command("christmas tree", "off")

# Get devices by device type:
deviceList ="x10_appliance")  # Can search on any device attribute

# Turn on all x10 lights off (regardless of house / unit code)
allX10lights = self._DeviceTypes.devices_by_device_type("x10_light")
# Turn off all x10 lights
for light in allX10lights:

Module author: Mitch Schwenk <>


Copyright 2012-2020 by Yombo.


LICENSE for details.


View Source Code

Devices Library Class

class yombo.lib.devices.__init__.Devices(parent, *args, **kwargs)[source]

Manages all devices and provides the primary interaction interface. The primary functions developers should use are:

  • __getitem__ - Get a pointer to a device, using self._Devices as a dictionary of objects.

  • command - Send a command to a device.

  • search - Get a pointer to a device, using device_id or device label.

devices = {}
_storage_primary_field_name: ClassVar[str] = 'device_id'
_storage_attribute_name: ClassVar[str] = 'devices'
_storage_label_name: ClassVar[str] = 'device'

alias of yombo.lib.devices.device.Device

_storage_schema: ClassVar = <DeviceSchema(many=False)>
_storage_pickled_fields: ClassVar[Dict[str, str]] = {'energy_map': 'json'}
_storage_search_fields: ClassVar[List[str]] = ['device_id', 'device_type_id', 'machine_label', 'label', 'area_label_lower', 'full_label_lower', 'area_label', 'full_label', 'description']
_storage_attribute_sort_key: ClassVar[str] = 'machine_label'

Sets up basic attributes.


Load devices from the database.




_device_state_(arguments, **kwargs)[source]

Sets up the callLater to calculate total energy usage. Called by send_state when a devices status changes.



Return type




Iterates thru all the devices and adds up the energy usage across all devices.

This function is called after a 1 second delay by _device_state_ hook.

Return type



load_an_item_to_memory(incoming, load_source=None, **kwargs)[source]

This method is here to be overridden incase any data manipulation needs to take place before doing the actual load into memory.

This method simply just calls do_class_storage_load_an_item_to_memory using the library variables for references.

  • incoming (dict) –

  • authentication – An authentication (AuthMixin source) to set request_by and request_type

  • load_source (Optional[str]) – Where the data originated from. One of: local, database, yombo, system

  • generated_source – Last resource string to use as a source.

  • save_into_storage – If false, won’t save into the library storage

  • kwargs

Return type



The new instance.

_load_node_into_memory_failure(failure, device)[source]
Return type


create_child_device(existing, label, machine_label, device_type, description=None)[source]
Return type


command(device, **kwargs)[source]

Tells the device to do a command. This in turn calls the hook _device_command_ so modules can process the command if they are supposed to.

If a pin is required, “pin” must be included as one of the arguments. All kwargs are sent with the hook call.

  • command doesn’t exist

  • delay or max_delay is not a float or int.



Raised when:

  • pin is required but not received one.

  • device (str) – Device Instance, Device ID, machine_label, or Label.

  • command (str) – Command InstanceCommand ID, machine_label, or Label to send.

  • pin (str) – A pin to check.

  • request_id (str) – Request ID for tracking. If none given, one will be created.

  • delay (int or float) – How many seconds to delay sending the command. Not to be combined with “not_before”

  • not_before (int or float) – An epoch time when the command should be sent. Not to be combined with “delay”.

  • max_delay (int or float) – How many second after the “delay” or “not_before” can the command be send. This can occur if the system was stopped when the command was supposed to be send.

  • inputs – A list of dictionaries containing the “input_type_id” and any supplied “value”.

  • kwargs (named arguments) – Any additional named arguments will be sent to the module for processing.


The request id.

Return type


device_user_access(device_id, access_type=None)[source]

Gets all users that have access to this device.


access_type – If set to “direct”, then gets list of users that are specifically added to this device. if set to “roles”, returns access based on role membership.



Return a list of devices, returning the value specified in field.


field (string) – A string referencing an attribute of a device.



Return a list of dictionaries representing all known devices. Can be restricted to a single gateway by supplying a gateway_id, use “local” for the local gateway.


gateway_id (string) – Filter selecting to a specific gateway. Use “local” for the local gateway.



Add a new device. This will also make an API request to add device at the server too.

  • data

  • kwargs


__annotations__ = {'_storage_attribute_name': typing.ClassVar[str], '_storage_attribute_sort_key': typing.ClassVar[str], '_storage_class_reference': typing.ClassVar, '_storage_label_name': typing.ClassVar[str], '_storage_pickled_fields': typing.ClassVar[typing.Dict[str, str]], '_storage_primary_field_name': typing.ClassVar[str], '_storage_schema': typing.ClassVar, '_storage_search_fields': typing.ClassVar[typing.List[str]]}
__module__ = 'yombo.lib.devices.__init__'

Last updated: Jun 17, 2020