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 accountExamples:
# 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 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 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 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 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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='UTF-8'>, 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_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 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 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 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
- add_tag(new_tags)¶
Add a tag to existing device tags. This method will not add a duplicate, if already in the list.
- Parameters
new_tags – the tag(s) to be added. new_tags can be a comma-separated string or list
- remove_tag(tag)¶
Remove tag from existing device tags
- Parameters
tag – the tag to be removed from the list
- Raises
ValueError – If tag does not exist in list