DeviceCore API¶

DeviceCore Overview¶

DeviceCore provides access to core device information such as which devices are in a given device cloud account, which of those are connected, etc.

DeviceCore API Documentation¶

class devicecloud.devicecore.DeviceCoreAPI(conn, sci)¶

Encapsulate DeviceCore interface

get_devices(condition=None, page_size=1000)¶

Iterates over each Device for this device cloud account

Examples:

# get a list of all devices
all_devices = list(dc.devicecore.get_devices())

# build a mapping of devices by their vendor id using a
# dict comprehension
devices = dc.devicecore.get_devices()  # generator object
devs_by_vendor_id = {d.get_vendor_id(): d for d in devices}

# iterate over all devices in 'minnesota' group and
# print the device mac and location
for device in dc.get_devices(group_path == 'minnesota'):
    print "%s at %s" % (device.get_mac(), device.get_location())

Parameters:	condition – An `Expression` which defines the condition which must be matched on the devicecore. If unspecified, an iterator over all devices will be returned. page_size (int) – The number of results to fetch in a single page. In general, the default will suffice.
Returns:	Iterator over each `Device` in this device cloud account in the form of a generator object.

get_group_tree_root(page_size=1000)¶

Return the root group for this accounts’ group tree

This will return the root group for this tree but with all links between nodes (i.e. children starting from root) populated.

Examples:

# print the group hierarchy to stdout
dc.devicecore.get_group_tree_root().print_subtree()

# gather statistics about devices in each group including
# the count from its subgroups (recursively)
#
# This also shows how you can go from a group reference to devices
# for that particular group.
stats = {}  # group -> devices count including children
def count_nodes(group):
    count_for_this_node = \
        len(list(dc.devicecore.get_devices(group_path == group.get_path())))
    subnode_count = 0
    for child in group.get_children():
        subnode_count += count_nodes(child)
    total = count_for_this_node + subnode_count
    stats[group] = total
    return total
count_nodes(dc.devicecore.get_group_tree_root())

Parameters:	page_size (int) – The number of results to fetch in a single page. In general, the default will suffice.
Returns:	The root group for this device cloud accounts group hierarchy.

get_groups(condition=None, page_size=1000)¶

Return an iterator over all groups in this device cloud account

Optionally, a condition can be specified to limit the number of groups returned.

Examples:

# Get all groups and print information about them
for group in dc.devicecore.get_groups():
    print group

# Iterate over all devices which are in a group with a specific
# ID.
group = dc.devicore.get_groups(group_id == 123)[0]
for device in dc.devicecore.get_devices(group_path == group.get_path()):
    print device.get_mac()

Parameters:	condition – A condition to use when filtering the results set. If unspecified, all groups will be returned. page_size (int) – The number of results to fetch in a single page. In general, the default will suffice.
Returns:	Generator over the groups in this device cloud account. No guarantees about the order of results is provided and child links between nodes will not be populated.

delete_device(dev)¶

Delete a from the cloud account associated with the handle.

Raises DeviceCloudHttpException:
	If there is an unexpected error reported by the device cloud.
Parameters:	dev – Device object of the device to delete.
Returns:	the Response from the delete request.

provision_device(**kwargs)¶

Provision a single device with the specified information

This API call provisions a new device on this cloud account. In order for this to work, a mac_address, device_id, or imei must be provided. All other parameters are optional and can be specified in addition to the primary identifier for the device.

This request will always return a dictionary unless the request fails altogether. The dictionary returned will have the following form:

{
    "error": <bool>,
    "error_msg": <string|None>,
    "location": <string|None>,
}

Parameters:	mac_address (str) – The MAC address of the device being added as a string in the form “00:00:00:00:00:00”. This is one of the options for the required primary id. device_id (str) – The ID of the device to add. This is the ‘devConnectwareId’ referenced in the API docs and should look like “00000000-00000000-000000FF-FF000000”. This is one of the options for the required primary id. imei (str) – The IMEI of the device to be added (if no MAC/ID available). This is one of the options for the required primary id. group_path (str) – (optional) Path of group that this device should be added to. metadata (str) – (optional) Arbitrary metadata to associate with this device. map_lat (float) – (optional) Latitude of this device in degrees map_long (float) – (optional) Longitude of this device in degrees contact (str) – (optional) Contact associted with this device (or whatever you want). description (str) – (optional) Textual description of this device.
Raises:	DeviceCloudHttpException – If there is an unexpected error reported by the device cloud. ValueError – If any input fields are known to have a bad form.
Returns:	A dictionary matching the format specified above.

provision_devices(devices)¶

Provision multiple devices with a single API call

This method takes an iterable of dictionaries where the values in the dictionary are expected to match the arguments of a call to provision_device(). The contents of each dictionary will be validated.

Parameters:	devices (list) – An iterable of dictionaries each containing information about a device to be provision. The form of the dictionary should match the keyword arguments taken by `provision_device()`.
Raises:	DeviceCloudHttpException – If there is an unexpected error reported by the device cloud. ValueError – If any input fields are known to have a bad form.
Returns:	A list of dictionaries in the form described for `provision_device()` in the order matching the requested device list. Note that it is possible for there to be mixed success and error when provisioning multiple devices.

class devicecloud.devicecore.Group(group_id, name, description, path, parent_id)¶

Provides access to information about a group in the device cloud

Note

This is primarily a container object and does not provide any functions itself at this time. Information from here can be used along with other APIs to, for example, get all devices with a given group path. This may change in the future.

classmethod from_json(json_data)¶: Build and return a new Group object from json data (used internally)

print_subtree(fobj=<open file '<stdout>', mode 'w'>, level=0)¶: Print this group node and the subtree rooted at it

is_root()¶: Return True if the group is the root for this account

add_child(group)¶: Add a child group reference to this one

get_children()¶: Return each child Group of this one in a list

get_id()¶: Get the ID of this group as as string

get_name()¶: Get the name of this group as a string

get_description()¶: Get the description of this group as a string

get_path()¶: Get the full path of this group as a string

get_parent_id()¶: Get the ID of this groups parent as a string

class devicecloud.devicecore.Device(conn, sci, device_json)¶

Interface to a device in the device cloud

get_device_json(use_cached=True)¶

Get the JSON metadata for this device as a python data structure

If use_cached is not True, then a web services request will be made synchronously in order to get the latest device metatdata. This will update the cached data for this device.

get_tags(use_cached=True)¶: Get the list of tags for this device

is_connected(use_cached=True)¶: Return True if the device is currrently connect and False if not

get_connectware_id(use_cached=True)¶: Get the connectware id of this device (primary key)

get_device_id(use_cached=True)¶: Get this device’s device id

get_ip(use_cached=True)¶: Get the last known IP of this device

get_mac(use_cached=True)¶: Get the MAC address of this device

get_mac_last4(use_cached=True)¶

Get the last 4 characters in the device mac address hex (e.g. 00:40:9D:58:17:5B -> 175B)

This is useful for use as a short reference to the device. It is not guaranteed to be unique (obviously) but will often be if you don’t have too many devices.

get_registration_dt(use_cached=True)¶: Get the datetime of when this device was added to the device cloud

get_meid(use_cached=True)¶: Return the meid as a string of this device if it has one or None

get_customer_id(use_cached=True)¶: Get the automatically generated customer id for this device

get_group_id(use_cached=True)¶: Get the id of the group with which this device is associated

get_group_path(use_cached=True)¶: Get the path of the group with which this device is associated

get_vendor_id(use_cached=True)¶: Get the vendor id associated with this device if any

get_device_type(use_cached=True)¶: Get the device type of this device if present

get_firmware_level(use_cached=True)¶: Get the firmware level of this device if present

get_firmware_level_description(use_cached=True)¶: Get the firmware level as a string (rather than a number)

get_restricted_status(use_cached=True)¶

Get the restricted status of this device

The value here will be returned as an integer with 3 potential values:

0 - unrestricted
2 - restricted
3 - untrusted

get_last_known_ip(use_cached=True)¶: Get the last known IP address of this device

get_global_ip(use_cached=True)¶: Get the last known global IP from which a device connected (out of NAT)

get_last_connected_dt(use_cached=True)¶: Get the datetime that the device last connected to the device cloud

get_contact(use_cached=True)¶: Get the contact (if any) associated with this device

get_description(use_cached=True)¶: Get the description associated with this device

get_location(use_cached=True)¶: Get the location (string) associated with this device

get_latlon(use_cached=True)¶: Get a tuple with device latitude and longitude... these may be None

get_user_metadata(use_cached=True)¶: Get the user metadata for this device (string) if present

get_zb_pan_id(use_cached=True)¶: Get the Zigbee PAN ID from the device if present

get_zb_extended_address(use_cached=True)¶: Get the Zigbee extended address of this device if present

get_server_id(use_cached=True)¶: Get the ID of the server this device is currently connected to

get_provision_id(use_cached=True)¶: Get the provisioning ID of this device if used

get_current_connect_pw(use_cached=True)¶: Get the current connection password for this device

add_to_group(group_path)¶

Add a device to a group, if the group doesn’t exist it is created

Parameters:	group_path – Path or “name” of the group

remove_from_group()¶: Place a device back into the root group