Device Directory

Usage

from mbed_cloud import DeviceDirectoryAPI
deviceDirectoryApi = DeviceDirectoryAPI()

# 5 most recent devices from catalog, which are registered
filters = { 'state': {'$eq' : 'registered' }}
reg_devices = list(deviceDirectoryApi.list_devices(limit=10, order='desc', filters=filters))

# Get details about specific (registered) device
deviceDirectoryApi.get_device(reg_devices[0].id)

# List device events
for d in deviceDirectoryApi.list_device_events():
  print(d.id)

# 10 oldest device events
list(deviceDirectoryApi.list_device_events(order='asc'))[:10]

# 10 most recent events for a specific device
filters = {
  'device_id': { '$eq': '01588c0460c002420a012c0400000000' }
}
deviceDirectoryApi.list_device_events(limit=10, filters=filters)

# Specific event
deviceDirectoryApi.get_device_event("0158b997cf7102420a013f0800000000")

More examples

See full listing of examples in the examples directory.

Reference

class mbed_cloud.device_directory.DeviceDirectoryAPI(params=None)

A module to access this section of the Pelion Device Management API.

Parameters:params – Dictionary to override configuration values
add_device(**kwargs)

Add a new device to catalog.

device = {
    "mechanism": "connector",
    "certificate_fingerprint": "<certificate>",
    "name": "New device name",
    "certificate_issuer_id": "<id>"
}
resp = api.add_device(**device)
print(resp.created_at)
Parameters:
  • certificate_fingerprint (str) – Fingerprint of the device certificate
  • certificate_issuer_id (str) – ID of the issuer of the certificate
  • name (str) – The name of the device
  • account_id (str) – The owning Identity and Access Managment (IAM) account ID
  • custom_attributes (obj) – Up to 5 custom JSON attributes
  • description (str) – The description of the device
  • device_class (str) – Class of the device
  • id (str) – The ID of the device
  • manifest_url (str) – URL for the current device manifest
  • mechanism (str) – The ID of the channel used to communicate with the device
  • mechanism_url (str) – The address of the connector to use
  • serial_number (str) – The serial number of the device
  • state (str) – The current state of the device
  • vendor_id (str) – The device vendor ID
  • alias (str) – The alias of the device
  • device_type (str) – The endpoint type of the device - e.g. if the device is a gateway
  • host_gateway (str) – The endpoint_name of the host gateway, if appropriate
  • bootstrap_certificate_expiration (datetime) –
  • connector_certificate_expiration (datetime) – Expiration date of the certificate used to connect to connector server
  • device_execution_mode (int) – The device class
  • firmware_checksum (str) – The SHA256 checksum of the current firmware image
  • manifest_timestamp (datetime) – The timestamp of the current manifest version
Returns:

the newly created device object.

Return type:

Device

add_query(name, filter, **kwargs)

Add a new query to device query service.

f = api.add_query(
    name = "Query name",
    filter = {
        "device_id": {"$eq": "01234"},
        custom_attributes = {
            "foo": {"$eq": "bar"}
        }
    }
)
print(f.created_at)
Parameters:
  • name (str) – Name of query
  • filter (dict) – Filter properties to apply (Required)
Returns:

The newly created query object.

Return type:

Query

delete_device(device_id)

Delete device from catalog.

Parameters:device_id (str) – ID of device in catalog to delete (Required)
Returns:void
delete_query(query_id)

Delete query in device query service.

Parameters:query_id (int) – ID of the query to delete (Required)
Returns:void
get_device(device_id)

Get device details from catalog.

Parameters:device_id (str) – the ID of the device to retrieve (Required)
Returns:device object matching the device_id.
Return type:Device
get_device_event(device_event_id)

Get device event with provided ID.

Parameters:device_event_id (int) – id of the event to get (Required)
Return type:DeviceEvent
get_query(query_id)

Get query in device query service.

Parameters:query_id (int) – ID of the query to get (Required)
Returns:device query object
Return type:Query
list_device_events(**kwargs)

List all device logs.

Parameters:
  • limit (int) – The number of logs to retrieve.
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get logs after/starting at given device_event_id
  • filters (dict) – Dictionary of filters to apply.
Returns:

list of DeviceEvent objects

Return type:

PaginatedResponse

list_devices(**kwargs)

List devices in the device catalog.

Example usage, listing all registered devices in the catalog:

filters = { 'state': {'$eq': 'registered' } }
devices = api.list_devices(order='asc', filters=filters)
for idx, d in enumerate(devices):
    print(idx, d.id)
Parameters:
  • limit (int) – The number of devices to retrieve.
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get devices after/starting at given device_id
  • filters – Dictionary of filters to apply.
Returns:

a list of Device objects registered in the catalog.

Return type:

PaginatedResponse

list_queries(**kwargs)

List queries in device query service.

Parameters:
  • limit (int) – The number of devices to retrieve.
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get devices after/starting at given device_id
  • filters – Dictionary of filters to apply.
Returns:

a list of Query objects.

Return type:

PaginatedResponse

update_device(device_id, **kwargs)

Update existing device in catalog.

existing_device = api.get_device(...)
updated_device = api.update_device(
    existing_device.id,
    certificate_fingerprint = "something new"
)
Parameters:
  • device_id (str) – The ID of the device to update (Required)
  • custom_attributes (obj) – Up to 5 custom JSON attributes
  • description (str) – The description of the device
  • name (str) – The name of the device
  • alias (str) – The alias of the device
  • device_type (str) – The endpoint type of the device - e.g. if the device is a gateway
  • host_gateway (str) – The endpoint_name of the host gateway, if appropriate
  • certificate_fingerprint (str) – Fingerprint of the device certificate
  • certificate_issuer_id (str) – ID of the issuer of the certificate
Returns:

the updated device object

Return type:

Device

update_query(query_id, name=None, filter=None, **kwargs)

Update existing query in device query service.

q = api.get_query(...)
q.filter["custom_attributes"]["foo"] = {
    "$eq": "bar"
}
new_q = api.update_query(
    query_id = q.id,
    name = "new name",
    filter = q.filter
)
Parameters:
  • query_id (str) – Existing query ID to update (Required)
  • name (str) – name of query
  • filter (dict) – query properties to apply
Returns:

the newly updated query object.

Return type:

Query

class mbed_cloud.device_directory.Device(dictionary)

Initialize object.

account_id

The owning IAM account ID.

Return type:str
alias

The alias of the device.

Return type:str
bootstrap_certificate_expiration

Expiration date of certificate.

Return type:datetime
bootstrapped_timestamp

The time the device was created.

Return type:datetime
certificate_fingerprint

Fingerprint of the device certificate.

This is not part of the certificate but rather the SH-256 hash of the certificate.

Return type:str
certificate_issuer_id

ID of the issuer of the certificate.

This is the value of the CN field (in the Subject) of the Issuer of the certificate.

Return type:str
claimed_at

When the device was first claimed/enrolled.

Return type:datetime
connector_certificate_expiration

Expiration date of the certificate used to connect to connector server.

Return type:datetime
created_at

The time the device was created.

Return type:datetime
custom_attributes

Up to 5 custom JSON attributes.

Return type:object
deployed_state

State of the device’s deployment.

Return type:str
description

The description of the device.

Return type:str
device_class

Class of the device.

Return type:str
device_execution_mode

The device class.

Return type:int
device_type

The type of the device - e.g. if the device is a gateway.

Return type:str
firmware_checksum

The SHA256 checksum of the current firmware image.

Return type:str
host_gateway

The device name of the host gateway, if appropriate.

Return type:str
id

The ID of the device.

Return type:str
last_deployment

The last deployment used on the device.

Return type:datetime
manifest_timestamp

The timestamp of the current manifest version.

Return type:datetime
manifest_url

URL for the current device manifest.

Return type:str
mechanism

The ID of the channel used to communicate with the device.

Return type:str
mechanism_url

The address of the connector to use.

Return type:str
name

The name of the device.

Return type:str
serial_number

The serial number of the device.

Return type:str
state

The current state of the device.

Return type:str
update_attributes(updates)

Update attributes.

updated_at

The time the device was updated.

Return type:datetime
vendor_id

The device vendor ID.

Return type:str
class mbed_cloud.device_directory.DeviceEvent(device_event_obj)

Override __init__ and allow passing in backend object.

changes

Gets the changes of this DeviceEventData. Additional data relevant to the event.

Returns:The changes of this DeviceEventData.
Return type:dict(str, str)
created_at

Gets the created_at of this DeviceEventData.

Returns:The created_at of this DeviceEventData.
Return type:datetime
data

Gets the data of this DeviceEventData.

Returns:The data of this DeviceEventData.
Return type:object
date_time

Gets the date_time of this DeviceEventData.

Returns:The date_time of this DeviceEventData.
Return type:datetime
description

Gets the description of this DeviceEventData.

Returns:The description of this DeviceEventData.
Return type:str
device_id

Gets the device_id of this DeviceEventData.

Returns:The device_id of this DeviceEventData.
Return type:str
etag

Gets the etag of this DeviceEventData.

Returns:The etag of this DeviceEventData.
Return type:datetime
event_type

Gets the event_type of this DeviceEventData. Event code

Returns:The event_type of this DeviceEventData.
Return type:str
event_type_category

Gets the event_type_category of this DeviceEventData. Category code which groups the event type by a summary category.

Returns:The event_type_category of this DeviceEventData.
Return type:str
event_type_description

Gets the event_type_description of this DeviceEventData. Generic description of the event

Returns:The event_type_description of this DeviceEventData.
Return type:str
id

Gets the id of this DeviceEventData.

Returns:The id of this DeviceEventData.
Return type:str
object

Gets the object of this DeviceEventData. The API resource entity.

Returns:The object of this DeviceEventData.
Return type:str
state_change

Gets the state_change of this DeviceEventData.

Returns:The state_change of this DeviceEventData.
Return type:bool
class mbed_cloud.device_directory.Query(dictionary)

Initialize object.

created_at

Get the created_at of this Query.

The time the object was created

Returns:The created_at of this Query.
Return type:datetime
description

Get the description of this Query.

The description of the object

Returns:The description of this Query.
Return type:str
filter

Get the query of this Query.

The device query

Returns:The query of this Query.
Return type:dict
id

Get the id of this Query.

The ID of the query

Returns:The id of this Query.
Return type:str
name

Get the name of this Query.

The name of the query

Returns:The name of this Query.
Return type:str
update_attributes(updates)

Update attributes.

updated_at

Get the updated_at of this Query.

The time the object was updated

Returns:The updated_at of this Query.
Return type:datetime