Mbed Cloud Module

Summary of all top level APIs accessible from mbed_cloud:

from mbed_cloud import ...

Exposes the primary interfaces for the SDK.

class mbed_cloud.AccountManagementAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the AccountManagement API.

Exposing functionality for creating and managing accounts, users, groups and API keys in the organisation.

add_api_key(name, **kwargs)

Create new API key registered to organisation.

Parameters:
  • name (str) – The name of the API key (Required)
  • groups (list) – List of group IDs (str)
  • owner (str) – User ID owning the API key
  • status (str) – The status of the API key. Values: ACTIVE, INACTIVE
Returns:

Newly created API key object

Return type:

ApiKey

add_user(username, email, **kwargs)

Create a new user with provided details.

Add user example:

account_management_api = AccountManagementAPI()
# Add user
user = {
    "username": "test_user",
    "email": "test@gmail.com",
    "phone_number": "0123456789"
}
new_user = account_management_api.add_user(**user)
Parameters:
  • username (str) – The unique username of the user (Required)
  • email (str) – The unique email of the user (Required)
  • full_name (str) – The full name of the user
  • groups (list) – List of group IDs (str) which this user belongs to
  • password (str) – The password string of the user
  • phone_number (str) – Phone number of the user
  • terms_accepted (bool) – ‘General Terms & Conditions’ have been accepted
  • marketing_accepted (bool) – Marketing Information opt-in
Returns:

the new user object

Return type:

User

api_structure = {<module ‘mbed_cloud._backends.iam’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/iam/__init__.py’>: [<class ‘mbed_cloud._backends.iam.apis.developer_api.DeveloperApi’>, <class ‘mbed_cloud._backends.iam.apis.account_admin_api.AccountAdminApi’>]}
delete_api_key(api_key_id)

Delete an API key registered in the organisation.

Parameters:api_key_id (str) – The ID of the API key (Required)
Returns:void
delete_user(user_id)

Delete user specified user.

Parameters:user_id (str) – the ID of the user to delete (Required)
Returns:void
get_account()

Get details of the current account.

Returns:an account object.
Return type:Account
get_api_key(api_key_id)

Get API key details for key registered in organisation.

Parameters:api_key_id (str) – The ID of the API key to be updated (Required)
Returns:API key object
Return type:ApiKey
get_group(group_id)

Get details of the group.

Parameters:group_id (str) – The group ID (Required)
Returns:Group object.
Return type:Group
get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
get_user(user_id)

Get user details of specified user.

Parameters:user_id (str) – the ID of the user to get (Required)
Returns:the user object with details about the user.
Return type:User
list_api_keys(**kwargs)

List the API keys registered in the organisation.

List api keys Example:

account_management_api = AccountManagementAPI()

# List api keys
api_keys_paginated_response = account_management_api.list_api_keys()
# get single api key
api_keys_paginated_response.data[0]
Parameters:
  • limit (int) – Number of API keys to get
  • after (str) – Entity ID after which to start fetching
  • order (str) – Order of the records to return (asc|desc)
  • filters (dict) – Dictionary of filters to apply: str owner (eq)
Returns:

a list of ApiKey objects

Return type:

PaginatedResponse

Raises:

ApiException

list_group_api_keys(group_id, **kwargs)

List API keys of a group.

Parameters:
  • group_id (str) – The group ID (Required)
  • limit (int) – The number of api keys to retrieve.
  • order (str) – The ordering direction, ascending (asc) or descending (desc).
  • after (str) – Get API keys after/starting at given api key ID.
Returns:

a list of ApiKey objects.

Return type:

PaginatedResponse

list_group_users(group_id, **kwargs)

List users of a group.

Parameters:
  • group_id (str) – The group ID (Required)
  • limit (int) – The number of users to retrieve
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get API keys after/starting at given user ID
Returns:

a list of User objects.

Return type:

PaginatedResponse

list_groups(**kwargs)

List all groups in organisation.

Parameters:
  • limit (int) – The number of groups to retrieve
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get groups after/starting at given group ID
Returns:

a list of Group objects.

Return type:

PaginatedResponse

list_users(**kwargs)

List all users in organisation.

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

a list of User objects

Return type:

PaginatedResponse

update_account(**kwargs)

Update details of account associated with current API key.

Parameters:
  • address_line1 (str) – Postal address line 1.
  • address_line2 (str) – Postal address line 2.
  • city (str) – The city part of the postal address.
  • display_name (str) – The display name for the account.
  • country (str) – The country part of the postal address.
  • company (str) – The name of the company.
  • state (str) – The state part of the postal address.
  • contact (str) – The name of the contact person for this account.
  • postal_code (str) – The postal code part of the postal address.
  • parent_id (str) – The ID of the parent account.
  • phone_number (str) – The phone number of the company.
  • email (str) – Email address for this account.
  • aliases (list[str]) – List of aliases
Returns:

an account object.

Return type:

Account

update_api_key(api_key_id, **kwargs)

Update API key.

Parameters:
  • api_key_id (str) – The ID of the API key to be updated (Required)
  • name (str) – The name of the API key
  • owner (str) – User ID owning the API key
  • status (str) – The status of the API key. Values: ACTIVE, INACTIVE
Returns:

Newly created API key object

Return type:

ApiKey

update_user(user_id, **kwargs)

Update user properties of specified user.

Parameters:
  • user_id (str) – The ID of the user to update (Required)
  • username (str) – The unique username of the user
  • email (str) – The unique email of the user
  • full_name (str) – The full name of the user
  • password (str) – The password string of the user.
  • phone_number (str) – Phone number of the user
  • terms_accepted (bool) – Is ‘General Terms & Conditions’ accepted
  • marketing_accepted (bool) – Is receiving marketing information accepted?
Returns:

the updated user object

Return type:

User

class mbed_cloud.BillingAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the Billing API.

api_structure = {<module ‘mbed_cloud._backends.billing’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/billing/__init__.py’>: [<class ‘mbed_cloud._backends.billing.apis.default_api.DefaultApi’>]}
get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
get_quota_history(**kwargs)

Get quota usage history

get_quota_remaining()

Get the remaining value

get_report_active_devices(month=None, file_path=None)

Downloads a report of the active devices

Parameters:
  • file_path (str) – [optional] location to store output file
  • month (str or datetime) – [default: utcnow] month as datetime instance, or string in YYYY-MM format
Returns:

The report structure

Return type:

dict

get_report_firmware_updates(month=None, file_path=None)

Downloads a report of the firmware updates

Parameters:
  • file_path (str) – [optional] location to store output file
  • month (str or datetime) – [default: utcnow] month as datetime instance, or string in YYYY-MM format
Returns:

The report structure

Return type:

dict

get_report_overview(month, file_path)

Downloads a report overview

Parameters:
  • month (str or datetime) – month as datetime instance, or string in YYYY-MM format
  • file_path (str) – location to store output file
Returns:

outcome

Return type:

True or None

get_service_packages()

Get all service packages

class mbed_cloud.BootstrapAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the Bootstrap API.

add_psk(**kwargs)

Add

api_structure = {<module ‘mbed_cloud._backends.connector_bootstrap’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/connector_bootstrap/__init__.py’>: [<class ‘mbed_cloud._backends.connector_bootstrap.apis.pre_shared_keys_api.PreSharedKeysApi’>]}
delete_psk(endpoint_name, **kwargs)

Delete

get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
get_psk(endpoint_name, **kwargs)

Get

list_psks(**kwargs)

List

class mbed_cloud.CertificatesAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

Certificates API reference.

add_certificate(name, type, certificate_data, signature=None, **kwargs)

Add a new BYOC certificate.

Parameters:
  • name (str) – name of the certificate (Required)
  • type (str) – type of the certificate. Values: lwm2m or bootstrap (Required)
  • certificate_data (str) – X509.v3 trusted certificate in PEM format. (Required)
  • signature (str) – This parameter has been DEPRECATED in the API and does not need to be provided.
  • status (str) – Status of the certificate. Allowed values: “ACTIVE” | “INACTIVE”.
  • description (str) – Human readable description of this certificate, not longer than 500 characters.
Returns:

Certificate object

Return type:

Certificate

add_developer_certificate(name, **kwargs)

Add a new developer certificate.

Parameters:
  • name (str) – name of the certificate (Required)
  • description (str) – Human readable description of this certificate, not longer than 500 characters.
Returns:

Certificate object

Return type:

Certificate

api_structure = {<module ‘mbed_cloud._backends.connector_ca’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/connector_ca/__init__.py’>: [<class ‘mbed_cloud._backends.connector_ca.apis.developer_certificate_api.DeveloperCertificateApi’>, <class ‘mbed_cloud._backends.connector_ca.apis.server_credentials_api.ServerCredentialsApi’>], <module ‘mbed_cloud._backends.iam’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/iam/__init__.py’>: [<class ‘mbed_cloud._backends.iam.apis.account_admin_api.AccountAdminApi’>, <class ‘mbed_cloud._backends.iam.apis.developer_api.DeveloperApi’>]}
delete_certificate(certificate_id)

Delete a certificate.

Parameters:certificate_id (str) – The certificate id (Required)
Returns:void
get_certificate(certificate_id)

Get certificate by id.

Parameters:certificate_id (str) – The certificate id (Required)
Returns:Certificate object
Return type:Certificate
get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
list_certificates(**kwargs)

List certificates registered to organisation.

Currently returns partially populated certificates. To obtain the full certificate object: [get_certificate(certificate_id=cert[‘id’]) for cert in list_certificates]

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

list of Certificate objects

Return type:

Certificate

update_certificate(certificate_id, **kwargs)

Update a certificate.

Parameters:
  • certificate_id (str) – The certificate id (Required)
  • certificate_data (str) – X509.v3 trusted certificate in PEM format.
  • signature (str) – This parameter has been DEPRECATED in the API and does not need to be provided.
  • type (str) – type of the certificate. Values: lwm2m or bootstrap.
  • status (str) – Status of the certificate. Allowed values: “ACTIVE” | “INACTIVE”.
  • description (str) – Human readable description of this certificate, not longer than 500 characters.
Returns:

Certificate object

Return type:

Certificate

class mbed_cloud.ConnectAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the Connect API.

Exposing functionality for doing a range of device related actions:
  • Listing connected devices
  • Exploring and managing resources and resource values on connected devices
  • Setup resource subscriptions and webhooks for resource monitoring
add_resource_subscription(device_id, resource_path, fix_path=True, queue_size=5)

Subscribe to resource updates.

When called on a valid device and resource path a subscription is setup so that any update on the resource path value triggers a new element on the FIFO queue. The returned object is a native Python Queue object.

Parameters:
  • device_id – Name of device to subscribe on (Required)
  • resource_path – The resource path on device to observe (Required)
  • fix_path – Removes leading / on resource_path if found
  • queue_size – Sets the Queue size. If set to 0, no queue object will be created
Returns:

a queue of resource updates

Return type:

Queue

add_resource_subscription_async(device_id, resource_path, callback_fn, fix_path=True, queue_size=5)

Subscribe to resource updates with callback function.

When called on a valid device and resource path a subscription is setup so that any update on the resource path value triggers an update on the callback function.

Parameters:
  • device_id – Name of device to set the subscription on (Required)
  • resource_path – The resource path on device to observe (Required)
  • callback_fn – Callback function to be executed on update to subscribed resource
  • fix_path – Removes leading / on resource_path if found
  • queue_size – Sets the Queue size. If set to 0, no queue object will be created
Returns:

void

api_structure = {<module ‘mbed_cloud._backends.mds’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/mds/__init__.py’>: [<class ‘mbed_cloud._backends.mds.apis.endpoints_api.EndpointsApi’>, <class ‘mbed_cloud._backends.mds.apis.notifications_api.NotificationsApi’>, <class ‘mbed_cloud._backends.mds.apis.device_requests_api.DeviceRequestsApi’>, <class ‘mbed_cloud._backends.mds.apis.resources_api.ResourcesApi’>, <class ‘mbed_cloud._backends.mds.apis.subscriptions_api.SubscriptionsApi’>], <module ‘mbed_cloud._backends.statistics’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/statistics/__init__.py’>: [<class ‘mbed_cloud._backends.statistics.apis.account_api.AccountApi’>, <class ‘mbed_cloud._backends.statistics.apis.statistics_api.StatisticsApi’>], <module ‘mbed_cloud._backends.device_directory’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/device_directory/__init__.py’>: [<class ‘mbed_cloud._backends.device_directory.apis.default_api.DefaultApi’>]}
delete_device_subscriptions(device_id)

Removes a device’s subscriptions

Parameters:device_id – ID of the device (Required)
Returns:None
delete_presubscriptions()

Deletes pre-subscription data.

Returns:None
delete_resource_subscription(device_id=None, resource_path=None, fix_path=True)

Unsubscribe from device and/or resource_path updates.

If device_id or resource_path is None, or this method is called without arguments, all subscriptions are removed. Calling it with only device_id removes subscriptions for all resources on the given device.

Parameters:
  • device_id – device to unsubscribe events from. If not provided, all registered devices will be unsubscribed.
  • resource_path – resource_path to unsubscribe events from. If not provided, all resource paths will be unsubscribed.
  • fix_path – remove trailing / in resouce path to ensure API works.
Returns:

void

delete_subscriptions()

Remove all subscriptions.

Warning: This could be slow for large numbers of connected devices. If possible, explicitly delete subscriptions known to have been created.

Returns:None
delete_webhook()

Delete/remove registered webhook.

If no webhook is registered, an exception (404) will be raised.

Note that every registered subscription will be deleted as part of deregistering a webhook.

Returns:void
ensure_notifications_thread()

Ensure notification thread is running

execute_resource(device_id, resource_path, fix_path=True, timeout=None)

Execute a function on a resource.

Will block and wait for response to come through. Usage:

try:
    v = api.execute_resource(device, path)
    print("Success, returned value:", v)
except AsyncError, e:
    print("Error", e)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to update (Required)
  • resource_function (str) – Unused
  • fix_path – Unused
  • timeout – Timeout in seconds
Raises:

AsyncError

Returns:

The value returned from the function executed on the resource

Return type:

str

execute_resource_async(device_id, resource_path, fix_path=True)

Execute a function on a resource.

Will not block. Returns immediately. Usage:

a = api.execute_resource_async(device, path)
while not a.is_done:
    time.sleep(0.1)
if a.error:
    print("Error", a.error)
print("Success, returned value:", a.value)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to update (Required)
  • fix_path – Unused
Returns:

An async consumer object holding reference to request

Return type:

AsyncConsumer

get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
get_resource(device_id, resource_path)

Get a resource.

Parameters:
  • device_id (str) – ID of the device (Required)
  • path (str) – Path of the resource to get (Required)
Returns:

Device resource

:rtype Resource

get_resource_subscription(device_id, resource_path, fix_path=True)

Read subscription status.

Parameters:
  • device_id – Name of device to set the subscription on (Required)
  • resource_path – The resource path on device to observe (Required)
  • fix_path – Removes leading / on resource_path if found
Returns:

status of subscription

get_resource_value(device_id, resource_path, fix_path=True, timeout=None)

Get a resource value for a given device and resource path by blocking thread.

Example usage:

try:
    v = api.get_resource_value(device_id, path)
    print("Current value", v)
except CloudAsyncError, e:
    print("Error", e)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to get (Required)
  • fix_path – if True then the leading /, if found, will be stripped before doing request to backend. This is a requirement for the API to work properly
  • timeout – Seconds to request value for before timeout. If not provided, the program might hang indefinitely.
Raises:

CloudAsyncError, CloudTimeoutError

Returns:

The resource value for the requested resource path

Return type:

str

get_resource_value_async(device_id, resource_path, fix_path=True)

Get a resource value for a given device and resource path.

Will not block, but instead return an AsyncConsumer. Example usage:

a = api.get_resource_value_async(device, path)
while not a.is_done:
    time.sleep(0.1)
if a.error:
    print("Error", a.error)
print("Current value", a.value)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to get (Required)
  • fix_path (bool) – strip leading / of path if present
Returns:

Consumer object to control asynchronous request

Return type:

AsyncConsumer

get_webhook()

Get the current callback URL if it exists.

Returns:The currently set webhook
has_active_notification_thread

Has active notification thread

list_connected_devices(**kwargs)

List connected devices.

Example usage, listing all registered devices in the catalog:

filters = {
    'created_at': {'$gte': datetime.datetime(2017,01,01),
                   '$lte': datetime.datetime(2017,12,31)
                  }
}
devices = api.list_connected_devices(order='asc', filters=filters)
for idx, device in enumerate(devices):
    print(device)

## Other example filters

# Directly connected devices (not via gateways):
filters = {
    'host_gateway': {'$eq': ''},
    'device_type': {'$eq': ''}
}

# Devices connected via gateways:
filters = {
    'host_gateway': {'$neq': ''}
}

# Gateway devices:
filters = {
    'device_type': {'$eq': 'MBED_GW'}
}
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 connected Device objects.

Return type:

PaginatedResponse

list_device_subscriptions(device_id, **kwargs)

Lists all subscribed resources from a single device

Parameters:device_id – ID of the device (Required)
Returns:a list of subscribed resources
Return type:list of str
list_metrics(include=None, interval=‘1d’, **kwargs)

Get statistics.

Parameters:
  • include (list[str]) – List of fields included in response. None, or an empty list will return all fields. Fields: transactions, successful_api_calls, failed_api_calls, successful_handshakes, pending_bootstraps, successful_bootstraps, failed_bootstraps, registrations, updated_registrations, expired_registrations, deleted_registrations
  • interval (str) – Group data by this interval in days, weeks or hours. Sample values: 2h, 3w, 4d.
  • start (datetime) – Fetch the data with timestamp greater than or equal to this value. The parameter is not mandatory, if the period is specified.
  • end (datetime) – Fetch the data with timestamp less than this value. The parameter is not mandatory, if the period is specified.
  • period (str) – Period. Fetch the data for the period in days, weeks or hours. Sample values: 2h, 3w, 4d. The parameter is not mandatory, if the start and end time are specified
  • limit (int) – The number of devices to retrieve
  • order (str) – The ordering direction, ascending (asc) or descending (desc)
  • after (str) – Get metrics after/starting at given metric ID
Returns:

a list of Metric objects

Return type:

PaginatedResponse

list_presubscriptions(**kwargs)

Get a list of pre-subscription data

Returns:a list of Presubscription objects
Return type:list of mbed_cloud.presubscription.Presubscription
list_resources(device_id)

List all resources registered to a connected device.

>>> for r in api.list_resources(device_id):
        print(r.name, r.observable, r.uri)
None,True,/3/0/1
Update,False,/5/0/3
...
Parameters:device_id (str) – The ID of the device (Required)
Returns:A list of Resource objects for the device
Return type:list
notify_webhook_received(payload)

Callback function for triggering notification channel handlers.

Use this in conjunction with a webserver to complete the loop when using webhooks as the notification channel.

Parameters:payload (str) – the encoded payload, as sent by the notification channel
set_resource_value(device_id, resource_path, resource_value, fix_path=True, timeout=None)

Set resource value for given resource path, on device.

Will block and wait for response to come through. Usage:

try:
    v = api.set_resource_value(device, path, value)
    print("Success, new value:", v)
except AsyncError, e:
    print("Error", e)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to update (Required)
  • resource_value (str) – The new value to set for given path
  • fix_path – Unused
  • timeout – Timeout in seconds
Raises:

AsyncError

Returns:

The value of the new resource

Return type:

str

set_resource_value_async(device_id, resource_path, resource_value=None, fix_path=True)

Set resource value for given resource path, on device.

Will not block. Returns immediately. Usage:

a = api.set_resource_value_async(device, path, value)
while not a.is_done:
    time.sleep(0.1)
if a.error:
    print("Error", a.error)
print("Success, new value:", a.value)
Parameters:
  • device_id (str) – The name/id of the device (Required)
  • resource_path (str) – The resource path to update (Required)
  • resource_value (str) – The new value to set for given path
  • fix_path – Unused
Returns:

An async consumer object holding reference to request

Return type:

AsyncConsumer

start_notifications()

Start the notifications thread.

If an external callback is not set up (using update_webhook) then calling this function is mandatory to get or set resource.

>>> api.start_notifications()
>>> print(api.get_resource_value(device, path))
Some value
>>> api.stop_notifications()
Returns:void
stop_notifications()

Stop the notifications thread.

Returns:
update_presubscriptions(presubscriptions)

Update pre-subscription data. Pre-subscription data will be removed for empty list.

Parameters:presubscriptions – list of Presubscription objects (Required)
Returns:None
update_webhook(url, headers=None)

Register new webhook for incoming subscriptions.

If a webhook is already set, this will do an overwrite.

Parameters:
  • url (str) – the URL with listening webhook (Required)
  • headers (dict) – K/V dict with additional headers to send with request
Returns:

void

class mbed_cloud.DeviceDirectoryAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the Device API.

Exposing functionality for doing a range of device related actions:
  • Listing registered devices
  • Create and manage device queries
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
  • trust_class (int) – The device trust class
  • vendor_id (str) – The device vendor ID
  • alias (str) – The alias of the device
  • 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
Parama str device_type:
 

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

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 (Required)
  • filter (dict) – Filter properties to apply (Required)
  • return – The newly created query object.
Returns:

the newly created query object

Return type:

Query

api_structure = {<module ‘mbed_cloud._backends.device_directory’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/device_directory/__init__.py’>: [<class ‘mbed_cloud._backends.device_directory.apis.default_api.DefaultApi’>]}
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_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
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.EnrollmentAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

API reference for the Enrollment API.

add_enrollment_claim(**kwargs)

Add

api_structure = {<module ‘mbed_cloud._backends.enrollment’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/enrollment/__init__.py’>: [<class ‘mbed_cloud._backends.enrollment.apis.public_api_api.PublicAPIApi’>]}
delete_enrollment_claim(id, **kwargs)

Delete

get_enrollment_claim(id, **kwargs)

Get

get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
list_enrollment_claims(**kwargs)

List

class mbed_cloud.UpdateAPI(params=None)

Bases: mbed_cloud.core.BaseAPI

Describing the public update API.

Exposing functionality from the following underlying services:

  • Update service
  • Update campaigns
  • Manifest management
add_campaign(name, device_filter, **kwargs)

Add new update campaign.

Add an update campaign with a name and device filtering. Example:

device_api, update_api = DeviceDirectoryAPI(), UpdateAPI()

# Get a filter to use for update campaign
query_obj = device_api.get_query(query_id="MYID")

# Create the campaign
new_campaign = update_api.add_campaign(
    name="foo",
    device_filter=query_obj.filter
)
Parameters:
  • name (str) – Name of the update campaign (Required)
  • device_filter (str) – The device filter to use (Required)
  • manifest_id (str) – ID of the manifest with description of the update
  • description (str) – Description of the campaign
  • scheduled_at (int) – The timestamp at which update campaign is scheduled to start
  • state (str) – The state of the campaign. Values: “draft”, “scheduled”, “devicefetch”, “devicecopy”, “publishing”, “deploying”, “deployed”, “manifestremoved”, “expired”
Returns:

newly created campaign object

Return type:

Campaign

add_firmware_image(name, datafile, **kwargs)

Add a new firmware reference.

Parameters:
  • name (str) – Firmware file short name (Required)
  • datafile (str) – The file object or path to the firmware image file (Required)
  • description (str) – Firmware file description
Returns:

the newly created firmware file object

Return type:

FirmwareImage

add_firmware_manifest(name, datafile, key_table_file=None, **kwargs)

Add a new manifest reference.

Parameters:
  • name (str) – Manifest file short name (Required)
  • datafile (str) – The file object or path to the manifest file (Required)
  • key_table_file (str) – The file object or path to the key_table file (Optional)
  • description (str) – Manifest file description
Returns:

the newly created manifest file object

Return type:

FirmwareManifest

api_structure = {<module ‘mbed_cloud._backends.update_service’ from ‘/tmp/workspace/artifacts/R3.0/mbed-cloud-sdk-python/build_artifacts/venv/lib/python3.6/site-packages/mbed_cloud/_backends/update_service/__init__.py’>: [<class ‘mbed_cloud._backends.update_service.apis.default_api.DefaultApi’>]}
delete_campaign(campaign_id)

Delete an update campaign.

Parameters:campaign_id (str) – Campaign ID to delete (Required)
Returns:void
delete_firmware_image(image_id)

Delete a firmware image.

Parameters:image_id (str) – image ID for the firmware to remove/delete (Required)
Returns:void
delete_firmware_manifest(manifest_id)

Delete an existing manifest.

Parameters:manifest_id (str) – Manifest file ID to delete (Required)
Returns:void
get_campaign(campaign_id)

Get existing update campaign.

Parameters:campaign_id (str) – Campaign ID to retrieve (Required)
Returns:Update campaign object matching provided ID
Return type:Campaign
get_firmware_image(image_id)

Get a firmware image with provided image_id.

Parameters:image_id (str) – The firmware ID for the image to retrieve (Required)
Returns:FirmwareImage
get_firmware_manifest(manifest_id)

Get manifest with provided manifest_id.

Parameters:manifest_id (str) – ID of manifest to retrieve (Required)
Returns:FirmwareManifest
get_last_api_metadata()

Get meta data for the last Mbed Cloud API call.

Returns:meta data of the last Mbed Cloud API call
Return type:ApiMetadata
list_campaign_device_states(campaign_id, **kwargs)

List campaign devices status.

Parameters:
  • campaign_id (str) – Id of the update campaign (Required)
  • limit (int) – number of devices state to retrieve
  • order (str) – sort direction of device state when ordered by creation time (desc|asc)
  • after (str) – get devices state after given id
Returns:

List of CampaignDeviceState objects

Return type:

PaginatedResponse

list_campaigns(**kwargs)

List all update campaigns.

Parameters:
  • limit (int) – number of campaigns to retrieve
  • order (str) – sort direction of campaigns when ordered by creation time (desc|asc)
  • after (str) – get campaigns after given campaign ID
  • filters (dict) – Dictionary of filters to apply
Returns:

List of Campaign objects

Return type:

PaginatedResponse

list_firmware_images(**kwargs)

List all firmware images.

Parameters:
  • limit (int) – number of firmware images to retrieve
  • order (str) – ordering of images when ordered by time. ‘desc’ or ‘asc’
  • after (str) – get firmware images after given image_id
  • filters (dict) – Dictionary of filters to apply
Returns:

list of FirmwareImage objects

Return type:

PaginatedResponse

list_firmware_manifests(**kwargs)

List all manifests.

Parameters:
  • limit (int) – number of manifests to retrieve
  • order (str) – sort direction of manifests when ordered by time. ‘desc’ or ‘asc’
  • after (str) – get manifests after given image_id
  • filters (dict) – Dictionary of filters to apply
Returns:

list of FirmwareManifest objects

Return type:

PaginatedResponse

start_campaign(campaign_object)

Start a draft update campaign.

Parameters:campaign_object (Campaign) – Campaign object to schedule for immediate start (Required)
Returns:newly edited campaign object
Return type:Campaign
update_campaign(campaign_object=None, campaign_id=None, **kwargs)

Update an update campaign.

:param Campaign campaign_object: Campaign object to update (Required) :return: updated campaign object :rtype: Campaign