Device¶

The Device resource can be used to interact with Sensors and Cloud Connectors, together referred to as devices. Various tasks can be performed by using the API Methods included in the class.

get_device()
list_devices()
transfer_devices()
set_label()
remove_label()
batch_update_labels()

Each device fetched by an API Method is represented by an instance of the Device class that is returned to the user.

API Methods¶

disruptive.Device.get_device(device_id, project_id=None, **kwargs)¶

Gets the current state of a single device.

Parameters:

device_id (str) – Unique ID of the target device.
project_id (str, optional) – Unique ID of the target project. If not provided, a wildcard project will be used, resulting in a search for the device through all available projects.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

device – Object representing the target device.

Return type:

Device

Examples

>>> # Fetch a single device.
>>> device = dt.Device.get_device('<DEVICE_ID>')

disruptive.Device.list_devices(project_id, query=None, device_ids=None, device_types=None, label_filters=None, order_by=None, **kwargs)¶

Gets a list of the current state of all devices in a project, including emulated devices.

Parameters:

project_id (str) – Unique ID of the target project.
query (str, optional) – Keyword-based device search device type, labels, and identifiers. Does not provide additional capabilities over setting explicit parameters available in this method.
device_ids (list[str], optional) – Specify devices by their unique IDs.
device_types (list[str], optional) – Filter by device types.
label_filters (dict[str, str], optional) – Specify devices by label keys and values (i.e. {“key”: “value”}). If only a key is provided (i.e. {“key”: “”}), all device with that key is fetched.
order_by (str, optional) – The field name you want to order the response by. Referred to using dot notation (i.e. “reported.temperature.value”). Default order is ascending, but can be flipped by prefixing “-“.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

devices – List of objects each representing a device.

Return type:

list[Device]

Examples

>>> # List all devices in a project.
>>> devices = dt.Device.list_devices(
...     project_id='<PROJECT_ID>',
... )

>>> # List all touch, temperature, and proximity sensors
>>> # in a project that has both the labels "room-number"
>>> # and "external-id" set to spesific values, then
>>> # sort by their most recent touch event time.
>>> devices = dt.Device.list_devices(
...     project_id=PROJECT_ID,
...     device_types=[
...         dt.Device.TOUCH,
...         dt.Device.TEMPERATURE,
...         dt.Device.PROXIMITY,
...     ],
...     label_filters={
...         'room-number': '99',
...         'external-id': '55E21B',
...     },
...     order_by='reported.touch.updateTime',
... )

disruptive.Device.transfer_devices(device_ids, source_project_id, target_project_id, **kwargs)¶

Transfers all specified devices to the target project.

The caller must have the permissions of either project.admin or organization.admin in both the source- and target project.

Parameters:

device_ids (list[str]) – Unique IDs for the devices to transfer.
source_project_id (str) – Unique ID of the source project.
target_project_id (str) – Unique ID of the target project.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

errors – A list that contains one error object for each device that could not be successfully transferred.

Return type:

list[TransferDeviceError]

Examples

>>> # Transfer a device from one project to another.
>>> err = dt.Device.transfer_devices(
...     device_ids=[
...         '<DEVICE_ID_1>',
...         '<DEVICE_ID_2>',
...     ],
...     source_project_id='<SOURCE_PROJECT_ID>',
...     target_project_id='<TARGET_PROJECT_ID>',
... )

disruptive.Device.set_label(device_id, project_id, key, value, **kwargs)¶

Set a label key and value for a single device.

If a label key already exists, the value is updated.

Parameters:

device_id (str) – Unique ID of the target device.
project_id (str) – Unique ID of the target project.
key (str) – Label key to be added.
value (str) – Label value to be added.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

errors – A list that contains one error object for each label that could not be successfully updated.

Return type:

list[LabelUpdateError]

Examples

>>> # Add a new `room-number` label to a device.
>>> err = dt.Device.set_label(
...     device_id='<DEVICE_ID>',
...     project_id='<PROJECT_ID>',
...     key='room-number',
...     value='99',
... )

disruptive.Device.remove_label(device_id, project_id, key, **kwargs)¶

Remove a label (key and value) from a single device.

Parameters:

device_id (str) – Unique ID of the target device.
project_id (str) – Unique ID of the target project.
key (str) – Key of the label to be removed.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

errors – A list that contains one error object for each label that could not be successfully updated.

Return type:

list[LabelUpdateError]

Examples

>>> # Remove the `room-number` label from a device.
>>> dt.Device.remove_label(
...     device_id='<DEVICE_ID>',
...     project_id='<PROJECT_ID>',
...     key='room-number',
... )

disruptive.Device.batch_update_labels(device_ids, project_id, set_labels=None, remove_labels=None, **kwargs)¶

Add, update, or remove multiple labels (key and value) on multiple devices

Must provide either set_labels or remove_labels. If neither are provided, a BadRequest error will be raised.

Parameters:

device_ids (list[str]) – List of unique IDs for the target devices.
project_id (str) – Unique ID of target project.
set_labels (dict[str, str], optional) – Key and value of labels to be added. If a label key already exists, the value is updated.
remove_labels (list[str], optional) – Label keys to be removed.
**kwargs (Any) – Arbitrary keyword arguments. See the Configuration page.

Returns:

errors – A list that contains one error object for each label that could not be successfully updated.

Return type:

list[LabelUpdateError]

Raises:

BadRequest – If neither set_labels nor remove_labels is provided.

Examples

>>> # Add 3 new and remove 2 old labels for a few devices.
>>> err = dt.Device.batch_update_labels(
...     device_ids=[
...         '<DEVICE_1>',
...         '<DEVICE_2>',
...         '<DEVICE_3>',
...     ],
...     project_id='<PROJECT_ID>',
...     set_labels={
...         'room-number': '99',
...         'group': 'favorite',
...         'alias': 'cookies',
...     },
...     remove_labels=[
...         'external-id',
...         'old-tag',
...     ],
... )

Class¶

class disruptive.Device(device)¶

Represents Sensors and Cloud Connectors, together referred to as devices.

When a device response is received, the content is unpacked and the related attributes are set.

Variables:

device_id (str) – Unique device ID.
project_id (str) – Project in which the device resides.
display_name (str, None) – Given device name if set through a label with key name. Otherwise None.
device_type (str) – Device type.
product_number (str) – The product number of the device.
labels (dict) – Label keys and values.
is_emulated (bool) – True if the device is emulated, otherwise False.
reported (Reported) – Object containing the data from the most recent events.
raw (dict[str, str]) – Unmodified API response JSON.

Type Constants¶

The Device class contains a string constant for each available device type.

Device.TEMPERATURE: str = 'temperature'¶

Device.PROXIMITY: str = 'proximity'¶

Device.TOUCH: str = 'touch'¶

Device.HUMIDITY: str = 'humidity'¶

Device.PROXIMITY_COUNTER: str = 'proximityCounter'¶

Device.TOUCH_COUNTER: str = 'touchCounter'¶

Device.WATER_DETECTOR: str = 'waterDetector'¶

Device.CLOUD_CONNECTOR: str = 'ccon'¶

Device.CO2: str = 'co2'¶

Device.DESK_OCCUPANCY: str = 'deskOccupancy'¶

Device.CONTACT: str = 'contact'¶

Device.DEVICE_TYPES = ['temperature', 'proximity', 'touch', 'humidity', 'proximityCounter', 'touchCounter', 'waterDetector', 'ccon', 'co2', 'motion', 'deskOccupancy', 'contact']¶

This can be a useful alternative to writing the strings directly.

# List all temperature- and touch sensors in a project.
devices = dt.Device.list_devices(
    project_id='<PROJECT_ID>',
    device_types=[
        dt.Device.TEMPERATURE,
        dt.Device.TOUCH,
        dt.Device.WATER_DETECTOR,
    ],
)

Navigation

Related Topics

Device¶

API Methods¶

Class¶

Type Constants¶