Device module

A device is a rapyuta.io resource representing any physical device that typically lives at a client location and is registered on rapyuta.io. The resource encapsulates information about the device, its architecture, runtime, user-provided metadata. Once a particular piece of hardware is successfully on-boarded to rapyuta.io this entity is responsible for providing the necessary mechanics and communication channels to manage and interact with the device. The platform leverages these mechanics to provide features that can be used to communicate to the device, configure it, monitor its health and deploy packages to the device.

Client Module

class Client(auth_token, project=None)

Client class provides access to device, package, volume and deployment classes.

__init__(auth_token, project=None)

Get new client object

Parameters
  • auth_token (string) – Authentication token

  • project (string) – project_guid of the user

get_all_devices(online_device=False, arch_list=None, retry_limit=0)

Get all the devices

Parameters
  • online_device (bool) – The value True returns only those devices that are online, while the value False returns all devices

  • arch_list (list) – If set, another call is made to filter devices by architecture. Valid architectures can be found in DeviceArch class. Note: Only online devices can be filtered by architecture. Therefore if arch_list is set, non-online devices are not included in the result irrespective of the value of online_device.

  • retry_limit (int) – No of retry attempts to be carried out if any failures occurs during the API call.

Returns

List of instances of Device class

Raises

APIError: If the API returns an error, a status code of anything other than 200/201 is returned

Following example demonstrates how to get the device list

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients import DeviceArch
>>> client = Client(auth_token='auth_token', project='project_guid')
>>> devices = client.get_all_devices()
>>> filtered_by_arch_devices = client.get_all_devices(arch_list=[
>>>     DeviceArch.ARM32V7, DeviceArch.ARM64V8, DeviceArch.AMD64])

Device Module

class Device(*args, **kwargs)

Device class represents a device. Member variables of the class represent the properties of device.

Variables
  • uuid – Id of the device.

  • name – Name of the device.

  • status – Status of the device. Status can be ONLINE/OFFLINE/REGISTERED.

  • username – User log in to device

  • saltversion – Salt version of the device.

  • registration_time – Device registration time.

  • description – Description of the device.

  • labels – List of labels associated with the device.

  • config_variables – Configuration variables of the device.

  • deployments – List of deployments on device

  • error_code – Error code when device goes to FAILED state. Will be of the form: ‘DEV_E*’.

  • error_message – Error message when device goes to FAILED state.

add_config_variable(key, value)

Add new configuration variable to the device.

Parameters
  • key (string) – Configuration variable key

  • value (string) – Configuration value

Returns

instance of DeviceConfig class.

Raises

ParameterMissingException: If any parameters are missing in the request.

Raises

DeviceNotFoundException: If the device is not found.

Raises

APIError: If the API returns an error, the status code is anything other than 200/201

Following example demonstrates how to add a device configuration variable.

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.add_config_variable('config_key', 'config_value')
add_label(key, value, retry_limit=0)

Add label to the device

Parameters
  • key (string) – label key

  • key – label value

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occur during the API call.

Returns

instances of the class Label.

Raises

DeviceNotFoundException: If the device is not found.

Raises

ParameterMissingException: If any parameters are missing in the request.

Raises

APIError: If the API call returns an error, the status code is anything other than 200/201

Following example demonstrates how to add device labels

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.model import Label
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.add_label('key', 'value')
cancel_log_file_upload(request_uuid, retry_limit=0)

Cancels the ongoing upload operation.

Parameters
  • request_uuid (str) – UUID of the upload request

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

status of the cancel operation, True indicates operation succeeded False otherwise

Raises

LogsUUIDNotFoundException: If the request_uuid is not found

Raises

BadRequestError: if the upload operation is completed

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to cancel the ongoing upload operation
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> cancel_status = device.cancel_log_file_upload('request_uuid')
create_shared_url(shared_url)

Create a SharedURL that let’s you download the Log file from a Public URL.

Parameters

shared_url (SharedURL) – Instance of the SharedURL Object

Returns

Instance of SharedURL class

Following example demonstrate how to get the downloadable url
>>> from datetime import timedelta, datetime
>>> from rapyuta_io import Client
>>> expiry_time = datetime.now() + timedelta(days=7)
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> log = [log.filename == 'file.log' for log in device.list_uploaded_files_for_device()][0]
>>> shared_url = device.create_shared_url(SharedURL(log.request_uuid, expiry_time=expiry_time))
>>> print shared_url.url
delete(retry_limit=0)

Delete the device

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occur during the API call.

Returns

True if the device is deleted successfully. Otherwise returns False.

Raises

DeviceNotFoundException: If the device is not found.

Raises

DeploymentRunningException: When any deployment is running on the device.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to delete a device

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.model import Label
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.delete()
delete_config_variable(config_id, retry_limit=0)

Delete configuration variable for the device.

Parameters
  • config_id (int) – Configuration variable id

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occur during the API call.

Returns

True if the configuration variable is deleted, otherwise returns false

Raises

ParameterMissingException: If any parameters are missing in the request.

Raises

ConfigNotFoundException: If the configuration is not found.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to delete a device configuration variable.

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.delete_config(config_id='config_id')
delete_label(label_id, retry_limit=0)

Delete a device label.

Parameters
  • label_id (int) – Label Id to delete

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

Boolean value to indicate whether the label is deleted or not

Raises

LabelNotFoundException: If the label is not found.

Raises

APIError: If the API call returns an error, the status code is anything other than 200/201.

Following example demonstrates how to delete a device label

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.delete_label('label_id')
delete_uploaded_log_file(request_uuid, retry_limit=0)

Deletes the logs file from cloud storage

Parameters
  • request_uuid (str) – UUID of the upload request

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

status of the operation, True indicates operation succeeded false otherwise

Raises

LogsUUIDNotFoundException: If the request_uuid is not found

Raises

BadRequestError: if the upload is in progress

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to delete the uploaded log file from cloud storage
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> device.delete_uploaded_log_file('request_uuid')
download_log_file(request_uuid, retry_limit=0)

Returns downloadable log file URL, using this URL user can download log file using Wget or curl

Parameters
  • request_uuid (str) – UUID of the upload request

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

url of the uploaded log file in the cloud

Raises

LogsUUIDNotFoundException: If the request_uuid is not found

Raises

BadRequestError: if the upload operation is in progress

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to get the downloadable url
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> download_url = device.download_log_file('request_uuid')
execute_command(command, retry_limit=0)

Execute command on device

Parameters
  • command (Command) – Command to execute

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

Execution result

Raises

ParameterMissingException: If any parameters are missing in the request.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to execute a command.

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.model import Command
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id', )
>>> command = Command(cmd='uname -a', shell='/bin/bash', bg=False)
>>> device.execute_command(command)
get_config_variables()

Get configuration variables associated with the device

Returns

list of instances of DeviceConfig class.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

get_deployments()

Get partial details of deployments associated with the device. Also, update deployments field with these.

Note: Deployment details are partial. For full Deployment objects, use get_deployment() as shown in the example below.

Returns

List of deployment details.

Following example demonstrates how to get device deployments

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> partial_deployments = device.get_deployments()
>>> # to get full deployments objects:
>>> for dep in partial_deployments:
>>>     full_deployment = client.get_deployment(dep['io_deployment_id'])
get_labels()

Get all labels associated with the device

Returns

list of instances of the class Label.

Following example demonstrates how to get device labels

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.get_labels()
get_log_upload_status(request_uuid, retry_limit=0)

Gets the current upload status

Parameters
  • request_uuid (str) – UUID of the upload request

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

returns instance of the class LogUploadStatus

Raises

LogsUUIDNotFoundException: If the request_uuid is not found

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to get the status of ongoing upload operation
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> upload_status = device.get_log_upload_status('request_uuid')
get_runtime()

Get the device runtime :return: value of device configuration variable: runtime

Following example demonstrates how to get device runtime.

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.get_runtime()
list_uploaded_files_for_device(retry_limit=0)

Returns list of the uploaded files with status and other properties

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

returns the list of instance of the class LogUploads

Raises

BadRequestError: if the upload operation is in progress

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to get the downloadable url
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> status_list = device.list_uploaded_files_for_device()
metrics(retry_limit=0)

Gets the metric status from the device

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

list of instances of class Metric:

Raises

DeviceNotFoundException: If the device is not found

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to get the status of metric from the device
>>> from rapyuta_io import Client
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> device.metrics()
refresh(retry_limit=0)

Refresh the device details

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Raises

DeviceNotFountException: If the device is not found.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

subscribe_metric(metric, qos=<QoS.LOW: 0>, retry_limit=0)

Subscribe to given metric on the device

Parameters
  • metric (SystemMetric) – metric to be subscribed

  • qos (QoS) – QoS value of associated with metric

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

returns the boolean indicating status of the operation

Raises

DeviceNotFoundException: If the device is not found

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to subscribe to a metric
>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.device import SystemMetric, QoS
>>> client = Client(auth_token='auth_token', project='project_guid')
>>> device = client.get_device('device_id')
>>> device.subscribe_metric(SystemMetric.CPU, QoS.LOW)
subscribe_topic(topic, qos=0, kind=<TopicKind.METRIC: 'METRIC'>, whitelist_tag=[], whitelist_field=[], fail_on_topic_inexistence=True, retry_limit=0)

To subscribe a topic

Parameters
  • topic (string) – topic name to subscribe

  • qos (integer) – QoS value for topic subscription

  • kind (enum TopicKind) – subscribe the topic as a metric or log

  • whitelist_tag (list) – Optional parameter to specify the tags that needs to be whitelisted in metrics

  • whitelist_field (list) – Optional parameter to specify the fields that needs to be whitelisted in metrics

  • fail_on_topic_inexistence (bool) – Optional parameter to fail with error if topic doesnt exists on device

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

list containing subscription status.

Raises

DeviceNotFountException: If the device is not found.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to subscribe a topic

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.device import QoS
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.subscribe_topic('test_topic', qos=QoS.MEDIUM.value, kind=TopicKind.METRIC)
topic_status(retry_limit=0)

Get the subscribed and unsubscribed topics status

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

Instance of class TopicsStatus.

Raises

DeviceNotFoundException: If the device is not found.

Raises

UnknownTopicStatusException: If the topic status is empty.

Raises

APIError: If the API call returns an error, the status code is anything other than 200/201.

Following example demonstrates how to get the topic status

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.topic_status()
topics(retry_limit=0)

Fetching the available topics on the device

Parameters

retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

List of topics in the device (list(string)

Raises

DeviceNotFountException: If the device is not found.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to get the topic list

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.topics()
unsubscribe_metric(metric, retry_limit=0)

Unsubscribe to given metric

Parameters
  • metric (SystemMetric) – metric to be unsubscribed

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

boolean indicates the status of the operation

Raises

DeviceNotFoundException: If the device is not found

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to unsubscribe to a metric
>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.device import SystemMetric
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> device.unsubscribe_metric(SystemMetric.CPU)
unsubscribe_topic(topic, kind=<TopicKind.METRIC: 'METRIC'>, retry_limit=0)

To unsubscribe a topic

Parameters
  • topic (string) – topic name to unsubscribe

  • kind (enum TopicKind) – unsubscribe the topic as a metric or log

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

list containing unsubscription status.

Raises

DeviceNotFountException: If the device is not found.

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrates how to unsubscribe a topic

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> device.unsubscribe_topic('test_topic', TopicKind.METRIC)
update_config_variable(config)

Update device configuration variable of a device.

Parameters

config (instance of DeviceConfig class) – Configuration variable

Returns

instance of DeviceConfig class.

Raises

ParameterMissingException: If any parameters are missing in the request.

Raises

DeviceNotFoundException: If the device is not found.

Raises

APIError: If the API call returns an error, the status code is anything other than 200/201.

Following example demonstrates how to update a device configuration variable.

>>> from rapyuta_io import Client
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> config_var = device.get_config_variables()[0]
>>> config_var.value = 'new_config_value'
>>> device.update_config_variable(config_var)
update_label(label, retry_limit=0)

Update device label

Parameters
  • label (Label) – instance of class Label to update

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failures occurs during the API call.

Returns

updated instance of the class Label.

Raises

LabelNotFoundException: If the label is not found.

Raises

APIError: If the API call returns an error, the status code is anything other than 200/201.

Following example demonstrates how to update a device label

>>> from rapyuta_io import Client
>>> from rapyuta_io.clients.model import Label
>>> client = Client(auth_token='auth_token', project="project_guid")
>>> device = client.get_device('test_device_id')
>>> label = device.get_labels()[0]
>>> label.value = 'new label value'
>>> device.update_label(label)
upload_log_file(upload_request, retry_limit=0)

Uploads the specified logfile in request to the cloud storage

Parameters
  • upload_request (LogsUploadRequest) – upload specific details

  • retry_limit (int) – Optional parameter to specify the number of retry attempts to be carried out if any failure occurs during API invocation

Returns

UUID of the upload request using which user can query the status/download the file from cloud

Raises

APIError: If the api returns an error, the status code is anything other than 200/201

Following example demonstrate how to upload the log file from device
>>> from rapyuta_io import Client
>>> from rapyuta_io.clients import LogsUploadRequest
>>> client = Client(auth_token='token', project='project_id')
>>> device = client.get_device('device_id')
>>> upload_request = LogsUploadRequest('/path/to/file.log', file_name='new-file-name.log', override=False,
>>>                    purge_after=False, metadata={'key': 'value'})
>>> request_uuid = device.upload_log_file(upload_request)
class DeviceStatus(value)

DeviceStatus enumeration represents the supported device status. Device status can be any of the below types

DeviceStatus.ONLINE

DeviceStatus.REJECTED

DeviceStatus.ACCEPTED

DeviceStatus.OFFLINE

DeviceStatus.REGISTERED

DeviceStatus.INITIALIZING

DeviceStatus.FAILED

DeviceStatus.NEW

DeviceStatus.DELETED

class QoS(value)

Enumeration variables for QoS for topic/metric subscription.

QoS.LOW

QoS.MEDIUM

QoS.HIGH

class SystemMetric(value)

Metrics options that are currently supported by device. User can subscribe any of metrics options given below

SystemMetric.CPU

SystemMetric.MEMORY

SystemMetric.DISK

SystemMetric.DISKIO

SystemMetric.NETWORK

SystemMetric.WIRELESS

class TopicKind(value)

Enumeration variables for the Topic kind. Topic kind may be ‘Metric’ or ‘Log’

TopicKind.METRIC

TopicKind.LOG

class TopicQOS(value)

Deprecated since version 0.7.0: Use QoS instead.

Enumeration variables for the Topic qos. Topic qos may be 0, 1 or 2

TopicQOS.ZERO

TopicQOS.ONE

TopicQOS.TWO

class DeviceArch(value)

DeviceArch enumeration represents supported device architectures. Device architecture can be any of the below types

DeviceArch.ARM32V7

DeviceArch.ARM64V8

DeviceArch.AMD64

class Command(cmd, shell=None, env=None, bg=False, runas=None, pwd=None, cwd=None)

Command class represent command that is executed on a device.

Variables
  • shell – Represents the shell where it is going to execute

  • env – List of environment variables.

  • bg – Boolean value specifying whether the execution runs on the background or not

  • runas – Run the command as a specific user

  • cmd – Command to execute on the device

  • pwd – Present working directory

  • cwd – Current working directory

Note

pwd is deprecated. Although backward compatibility is supported, it is recommended to use cwd instead.

class DeviceConfig(*args, **kwargs)

DeviceConfig class represents configuration of a device. Member variables of the class represent the properties of device.

Variables
  • id – Id of the configuration.

  • key – Configuration key.

  • value – Value of the configuration key.

class Label(*args, **kwargs)

Label class represents labels associated with a device.

Variables
  • id – Integer represents the id of the label

  • key – Key or label name

  • value – Value of the label

class LogUploadStatus(*args, **kwargs)

This class instance represent current status of the upload request

Variables
  • status – Represents the current file upload status

  • error_message – Any error message during file upload

  • creator – User guid who initiated the upload operation

  • created_at – Timestamp at which logs upload initiated

  • request_uuid – An uniquely identifier associated with current upload

  • filename – Name of the file which is to be uploaded

  • updated_at – Timestamp at which file is updated

class LogUploads(*args, **kwargs)

This class represents the status and other attributes associated with upload files.

Variables
  • status – Represents the current upload status

  • content_length – Length in bytes

  • creator – User guid who initiated the upload operation

  • created_at – Timestamp at which logs upload initiated

  • request_uuid – UUID associated with the request

  • creation_time – Timestamp at which file upload is completed

  • updated_at – Timestamp at which last file updated happened

  • filename – Name of the file which is to be uploaded

  • last_modified – represents the time at which last modification done to the file on cloud

  • metadata – key/value pair associated with upload request

class LogsUploadRequest(device_path, file_name='', max_upload_rate=1048576, override=False, purge_after=False, metadata=None)

Request class for log upload API

Variables
  • device_path – absolute path of file on device

  • file_name – Name of the file in cloud storage. If not provided, file name is derived from the device_path

  • max_upload_rate – network bandwidth to be used for upload

  • override – If true overrides the destination file

  • purge_after – If true purges the log file after upload

  • metadata – Key/value to be associated with log file

class Metric(*args, **kwargs)

Class represents current status of subscription of the metric

Variables
  • name – Name of the metric

  • kind – metric

  • config – Metric collection configuration

class SharedURL(request_uuid, expiry_time)

This class represents the Shared URL for Logs uploaded from the Device.

Parameters
  • request_uuid (str) – Request GUID of the Log file

  • expiry_time (datetime.datetime) – Datetime object for the time at which Shared URL is supposed to expire.

  • creator (str) – User GUID that created the Shared URL

  • created_at (str) – Timestamp at which Shared URL was created

property url

The generated public URL.

Raises

InvalidParameterException: If the Shared URL is not created

class TopicsStatus(*args, **kwargs)

Topic class represents the status - subscribed and unsubscribed - for logs and metrics

Variables
  • master_up – Boolean represents whether the master is running or not

  • subscribed – List of subscribed topics

  • unsubscribed – List of unsubscribed topics