Reference

iotcs.client.AbstractVirtualDevice

class iotcs.client.AbstractVirtualDevice

Bases: abc.ABC

AbstractVirtualDevice is a representation of a device model.

The device implements a ddevice model. A device model is a specification of the attributes, formats, and resources available on the device.

The application calls set() on an AbstractVirtualDevice attribute and results in sending a message to the server. It calls get() to obtain the value of an attribute.

The ErrorCallback is invoked if there is an error sending the message to the server. See setOnError.

The ChangeCallback is invoked when the server receives a request to change a device attribute. It forwards the request to the device and the callback is invoked. See setOnChange.

The AbstractVirtualDevice supports sending more than one message at time using the update() and finish() methods.

class ChangeCallback

Bases: abc.ABC

An attribute value change callback interface.

This interface provides notification that the value of an attribute has changed.

See setOnChange

onChange(event)

Invoke onChange when an attribute value changes.

This method is invoked when the value of an attribute has changed. If an error occurs attempting to change the value, the new value is not set.

Parameters:event – the ChangeEvent change event
class ChangeEvent

Bases: iotcs.client.client.Event

A Change Event.

This class encapsulates information about an attribute change. An instance of this class is passed to ChangeCallback.onChange() method. The NamedValue instance behaves like a linked list containing all the changed attributes and their values.

The VirtualDevice instance is the virtual device whose attributes have changed.

See ChangeCallback, Event

getNamedValue()

Return the NamedValue instance.

Returns:the NamedValue instance, never ‘None`
getVirtualDevice()

Return the VirtualDevice instance.

Returns:the VirtualDevice instance, never None
class ErrorCallback

Bases: abc.ABC

An error callback interface.

This interface provides notification that an error when setting the value of an attribute.

See setOnError

onError(event)

Invoke onError when there is an error.

This method is invoked when an error occurs setting the value of an attribute or raising an Alert. :param event: The ErrorEvent error event, never None

class ErrorEvent

Bases: iotcs.client.client.Event

An Error event.

The event instance that is passed to onError() to indicate an error has occurred when setting one or more attributes, or an error occurred raising an Alert.

See ErrorCallback, Event

getMessage()

Return the error message.

Returns:the error message
class Event

Bases: abc.ABC

The base class for an event.

See ChangeCallback, AbstractVirtualDevice.ErrorCallback, ChangeEvent, ErrorEvent

getNamedValue()

Return the NamedValue instance.

Returns:the NamedValue instance, never None
getVirtualDevice()

Return the VirtualDevice instance.

Returns:the VirtualDevice instance, never None
class NamedValue

Bases: abc.ABC

This class encapsulates and name/value pair related to an event.

In some cases the name is the name of an attribute, and value is the attribute’s value and in some cases it is the name of a field in a format, or the name of an action, when an event is raised related to an alert or an action.

getName()

Return the name of the value.

Returns:the name of the value
getValue()

Return the value.

Returns:the value
next()

Return the next NamedValue in the list, or None.

Return the next NamedValue in the list or None if there are no more in the list. :return: the next NamedValue instance or None

finish()

Send the values in an update transaction to the server.

The update() method must have been called before calling finish. The update transaction mark is cleared.

See update()

get(attributeName)

Return the value of attributeName.

This method returns the current value held by the virtual device model and no call is made to the physical device.

Parameters:attributeName – the name of an attribute from the device type model
Returns:the attribute value
Raises:ValueError – if attributeName is not in the model, or attributeName is None
getDeviceModel()

Return the DeviceModel instance for this device object.

Returns:the device model DeviceModel
getEndpointId()

Return the endpoint id of the device.

The endpoint id is the identifier that the server creates when a registered device is activated.

Returns:the device’s endpoint id
getLastKnown(attributeName)

Return the last known value of attributeName.

The last known value is always the same as the current value. The last known value is maintained by the AbstractVirtualDevice instance. No REST API call is made to the server.

Parameters:attributeName – the name of an attribute from the device type model
Returns:the attribute value
Raises:ValueError – if attributeName is not in the model, or attributeName is None
set(attributeName, value)

Set the value of attributeName to value.

This method is used by the application to synchronize the AbstractVirtualDevice state with the physical device and results in an endpoint DATA message REST API call to the server.

value is validated according to the constraints in the DeviceModel. If value is not valid, a ValueError exception is raised.

Parameters:
  • attributeName – the name of an attribute from the device type model
  • value – the value to set
Returns:

this AbstractVirtualDevice instance
Raises:

ValueError – if value is not valid, attributeName is not in the model, or attributeName is None. or if attributeName is not writable.
setOnChange(callback, attributeName=None)

Set a ChangeCallback instance.

If attributeName is None, callback is invoked when the value of any attribute changes.

If attributeName is not None, callback is invoked when the value of attributeName changes.

If callback is None, the callback instance is removed and no callback is invoked for attribute value changes.

Parameters:
  • attributeName – the name of an attribute from the device model
  • callback – a ChangeCallback instance
Raises:

ValueError – if attributeName is not in the model, or attributeName is None
setOnError(callback, attributeName=None)

Set a ErrorCallback instance.

If attributeName is None, callback is invoked if an error occurs when setting any attribute or an error occurs when raising an Alert.

If attributeName is not None, callback is invoked if an error occurs when setting the value for attributeName or an error occurs when raising an Alert.

If callback is None, the callback instance is removed and no callback is invoked if an error occurs.

Parameters:
  • attributeName – the name of an attribute from the device model
  • callback – a ErrorCallback instance
Raises:

ValueError – if attributeName is not in the model, or attributeName is None
update()

Set a mark for beginning an update transaction.

If the update method had not been called and there is no open update transaction, calls to set() sends the new value to the server. The update method opens an update transaction and future calls to set() do not immediatelly send the new value to the server, but accumulates the changes to be sent in one call to the server.

The accumulated changes in an open update transaction are sent to the server when the finish() method is called. finish() sends the updated values to the server and closes the open update transaction.

For example:

virtualDevice.update().set("min", 10).set("max", 20).finish()

See finish()

Returns:this AbstractVirtualDevice instance

iotcs.client.Client

class iotcs.client.Client

Bases: iotcs.common.Closeable

Client of the Oracle IoT Cloud Service.

A client is a directly-connected device, or a gateway.

See DirectlyConnectedDevice, GatewayDevice

Create a new Client instance.

createStorageObject(name, contentType)

Create a new StorageObject. with name and contentType.

If contentType is None, the mime-type defaults to

“application/octet-stream”.

Parameters:
  • name – the unique name to be used to reference the content in storage
  • contentType – The mime-type of the content
Returns:

a StorageObject
Raises:

TransportException if there is an Exception raised by the runtime, or an abnormal response from the storage cloud
Raises:

SecurityException if there is an exception establishing a secure connection to the storage cloud
createVirtualDevice(deviceId, deviceModel)

Create an AbstractVirtualDevice instance.

A instance of AbstractVirtualDevice is created with the the given DeviceModel instance and the given device identifier. This method creates a new VirtualDevice instance with the given parameters. The client library does not cache created VirtualDevice instances.

Parameters:
  • deviceId – the device identifier of the device being modeled
  • deviceModel – an instance of DeviceModel that this device implements.
Raises:

ValueError – if the device does not implement the model, if deviceId or deviceModel are None.
Returns:

a VirtualDevice instance
getDeviceModel(deviceModelUrn)

Return the DeviceModel for deviceModelUrn.

This method returns None if there is no device model identified by deviceModelUrn. This method will also return None if the model is a draft model and the config property allow_draft_device_models in section device_model is set to False (the default).

Parameters:deviceModelUrn – the URN of the device model
Raises:ValueError – if deviceModelUrn is None or there is an I/O error when communicating with the server, or when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid
Returns:a DeviceModel instance or None

iotcs.client.device.Alert

class iotcs.client.device.Alert

Bases: abc.ABC

An Alert to be sent to the server.

The alert is sent by calling the raise_() method. The time of the alert is set when raise_() is called, allowing raise_() to be called more than once.

The set() method returns the Alert instance to allow the fields of the alert to be set in fluent style. See iotcs.client.device.VirtualDevice.createAlert()

raise_()

Send the alert. The event time is set when this method is called.

The onError handler of the parent virtual device will be called if there is error sending the alert.

All fields defined in the format that are “optional”, True must be set before calling raise_(). If raise_() is called before setting all “optional” True fields, IllegalStateException is raised.

Raises:ValueError – if raise_() is called if the alert message cannot be queued before setting all “optional”, True fields
set(field, value)

Set the value of a field in the Alert.

The fields are determined by the format given when the Alert is created. The value is validated according to the constraints in the format. If the value is not valid, an IllegalArgumentException is raised.

All fields defined in the format that are ‘optional”, True must be set before calling raise_().

:param field the name of a field from the alert format :param value the value to set :return: this Alert instance :raises ValueError: if the value is not valid, or field is None See iotcs.client.device.VirtualDevice.createAlert()

iotcs.client.device.Data

class iotcs.client.device.Data

Bases: abc.ABC

Represents a set of custom data fields.

The custom data fields are key, value pairs to be sent to the server. The custom data is sent by calling the submit() method. The time of the data fields are set when submit() is called, allowing submit() to be called more than once.

The set() method returns the Data instance to allow fields of data to be set in fluent style. See iotcs.client.device.VirtualDevice.createData()

set(field, value)

Set the value of a field in the Data.

The fields are determined by the format given when the Data is created. The value is validated according to the constraints in the format. If the value is not valid, an IllegalArgumentException is raised.

All fields defined in the format that are “optional” : false must be set before calling submit().

See iotcs.client.device.VirtualDevice.createData()

Parameters:
  • field – the name of a field from the custom data format
  • value – the value to set
Returns:

this Data instance
Raises:

ValueError – if the value is not valid, or field is None
submit()

Submit the data.

The event time is set when this method is called. The onError handler of the parent virtual device will be called if there is error submiting the custom data fields. See iotcs.client.device.VirtualDevice.setOnError()

All fields defined in the format that are “optional” : false must be set before calling submit(). If submit is called before setting all non optional fields, an IllegalStateException is raised.

Raises:ValueError – if submit is called before setting all optional fields

iotcs.client.DeviceModel

class iotcs.client.DeviceModel

Bases: abc.ABC

Detailed information on a device model.

A device model is a specification of the attributes, formats, and resources available on the device.

getDescription()

Return the free form description of the device model.

Returns:the description of the model
getName()

Return the name of the device model.

Returns:the device model name
getURN()

Return the URN of the device model.

Returns:the URN of the model

iotcs.client.device.DirectlyConnectedDevice

class iotcs.client.device.DirectlyConnectedDevice(path=None, passphrase=None, dcdImpl=None)

Bases: iotcs.client.client.Client

A DirectlyConnnectedDevice can send and receive messages.

A DirectlyConnectedDevice sends and receives messages to and from an IoT server. The directly-connected device is assigned an activation identifier when the device is registered on the server. When the directly-connected device is activated, the server assigns an endpoint identifer that is used by the DirectlyConnectedDevice for sending messages to, and receiving messages from, the server.

See activate(), getEndpointId()

Create a DirectlyConnectedDevice instance.

Load the device configuration from the given path and passphrase. See Configuration for details.

Parameters:
  • path – configFilePath the path of the configuration file
  • passphrase – configFilePassword the configuration file password, or None if the configurationFile is not encrypted
Raises:

ValueError – if the configuration could not be loaded, or the server scheme is not supported.
activate(deviceModels)

Activate the device.

The device will be activated on the server if necessary. When the device is activated on the server, the server assigns an endpoint identifier to the device.

If the device is already activated, this method will raise an IllegalArgumentException. The user should call the isActivated() method prior to calling activate.

Parameters:deviceModels – should contain the device model type URNs of this directlyconnected device. The device is activated with the given device models. The deviceModels parameter is zero or more, comma separated, device model URNs.
Raises:ValueError – if there is an I/O exception, when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid or if the device has already been activated

See isActivated()

close()

Close the directly connected device and its resources.

Raises:IOEerror – if an I/O error occurs
createStorageObject(name, contentType)

Create a new StorageObject.

The created storage object that will have a name with the given object name prefixed with the device’s endpoint ID and a directory separator. The prefix addition can be disabled by setting the config property disable_storage_object_prefix in section media_storage to True.

if contentType is None, the mime-type defaults to application/octet-stream.

:param name the unique name to be used to reference the content in storage :param contentType The mime-type of the content or None :return a StorageObject <.messaging.client.device.StorageObjectDelegate # noqa: E501 :raises TransportError: if exception raised by the runtime, or an abnormal response from the storage cloud :raises SecurityException: if there is an exception establishing a secure connection to the storage cloud

createVirtualDevice(endpointId, deviceModel)

Create a iotlic.clien.device.VirtualDevice instance.

The virtual device is created with the given device model and given device identifier.

This method creates a new iotcs.client.device.VirtualDevice instance for the given parameters. The client library does not cache previously created VirtualDevice objects.

Parameters:
  • endpointId – The device identifier of the device being modeled
  • deviceModel – The device model URN that this device implements
Raises:

ValueError – if the device does not implement the model, if deviceId or deviceModel are None
Returns:

a new VirtualDevice
getDeviceModel(urn)

Get the DeviceModel for the device model URN.

This method may return None if there is no device model for the URN. None may also be returned if the device model is a “draft” and the property allow_draft_device_models is set to False, which is the default.

Parameters:urn – the URN of the device model
Returns:A representation of the device model iotcs.client.DeviceModel or None if it does not exist
Raises:ValueError – if deviceModel is None, if there is an I/O error when communicating with the server or when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid
getEndpointId()

Return the endpoint identifier of this directly connected device.

The endpoint identifier is assigned by the server as part of the activation process.

Returns:the endpoint identifier of this directly-connected device.

See activate()

isActivated()

Return True if the device has been activated.

Returns:True if activated else False

iotcs.client.device.GatewayDevice

class iotcs.client.device.GatewayDevice(path, passphrase)

Bases: iotcs.client.device.device.DirectlyConnectedDevice

A GatewayDevice is a directly connected device.

A GatewayDevice differs from other directly connected devices in that it is capable of registering indirectly connected devices and proxies messages for indirectly connected devices.

Create a GatewayDevice instance.

The device configuration is loaded from the given file path and passphrase. See Configuration for details.

Parameters:
  • path – the path of the configuration file
  • passphrase – the configuration file passphrase, or None if the configurationFile is not encrypted
Raises:

ValueError – if the configuration file could not be loaded
DEVICE_CLASS = 'deviceClass'

The deviceClass attribute. This attribute is to be used when setting the deviceClass value in the meta-data.

MANUFACTURER = 'manufacturer'

The manufacturer attribute. This attribute is to be used when setting the manufacturer value in the meta-data.

MODEL_NUMBER = 'modelNumber'

The modelNumber attribute. This attribute is to be used when setting the modelNumber value in the meta-data.

PROTOCOL = 'protocol'

The protocol attribute. This attribute is to be used when setting the protocol value in the meta-data.

PROTOCOL_DEVICE_CLASS = 'protocolDeviceClass'

The protocolDeviceClass attribute. This attribute is to be used when setting the protocolDeviceClass value in the meta-data.

PROTOCOL_DEVICE_ID = 'protocolDeviceId'

The protocolDeviceId attribute. This attribute is to be used when setting the protocolDeviceId value in the meta-data.

SERIAL_NUMBER = 'serialNumber'

The serialNumber attribute. This attribute is to be used when setting the serialNumber value in the meta-data.

registerDevice(hardwareId, metaData, deviceModels, restricted=True)

Register an indirectly-connected device with the cloud service.

The restricted parameter controls whether or not the client library is required to supply credentials for activating the indirectly-connected device. The client library will always supply credentials for an indirectly-connected device whose trusted assets have been provisioned to the client. If however, the trusted assets of the indirectly-connected device have not been provisioned to the client, the client library can create credentials that attempt to restrict the indirectly connected device to this gateway device.

If the restricted parameter is True the indirectly-connected device cannot be activated by this gateway device without presenting credentials. If restricted is True, the client library will provide credentials to the server. The server will reject the activation request if the indirectly connected device is not allowed to roam to this gateway device.

If the restricted parameter is False the indirectly-connected can be activated without presenting credentials if the trusted assets of the indirectly-connected device have not been provisioned to the client. If restricted is False, the client library will provide credentials if, and only if, the credentials have been provisioned to the client. The server will reject the activation if credentials are required but not supplied, or if the provisioned credentials do not allow the indirectly connected device to roam to this gateway device.

The hardwareId is a unique identifier within the cloud service instance and may not be None. If one is not present for the device, it should be generated based on other metadata such as, model niumber, manufacturer, serial number, etc.

The metaData dict() should typically contain all the standard metadata (the constants documented in this class) along with any other vendor defined metadata.

Parameters:
  • restricted – indicate whether or not credentials are required for activating the indirectly connected device
  • hardwareId – an identifier unique within the Cloud Service instance
  • metaData – The metadata of the device
  • deviceModels – should contain the device model type URNs supported by the indirectly connected device. The deviceModels parameter is one or more, comma separated, device model URNs.
Returns:

The endpoint id of the indirectly-connected device
Raises:
  • IOError – if the message could not be sent
  • ValueError – when key or signature algorithm class cannot be loaded, or the key is not in the trusted assets store, or the private key is invalid or if hardwareId is null, or deviceModels is null or zero length

iotcs.client.device.VirtualDevice

class iotcs.client.device.VirtualDevice

Bases: iotcs.client.client.AbstractVirtualDevice

The VirtualDevice to represent a device-client.

The VirtualDevice provides methods to handle write-only and executable actions.

class ActionCallback

Bases: abc.ABC

A callback interface for receiving notification of a DeviceModelAction.

onAction(actionEvent)

Called to perform a DeviceModelAction action.

Parameters:actionEvent – the ActionEvent
class ActionEvent

Bases: iotcs.client.client.Event

An Event class that is passed to ActionCallback callbacks.

getName()

Return the action name. :return: the action name

class Callable

Bases: abc.ABC

Callback interface for device model actions.

This class is implemented to handle iotcs.client.device.DeviceModel actions. :deprecated:

call(virtualDevice, data)

Handle a device model action.

For an execute action the client library will pass None as the data parameter. For a write-only action, the type of data should match the expected data type of the action.

Parameters:
createAlert(alertformaturn)

Create an Alert for this VirtualDevice.

The alert will be created with the given format URN. :param alertformaturn: the alert format URN. :return: an iotcs.client.Device.Alert

createData(messageformaturn)

Create a custom data object for this VirtualDevice.

The custom data object will be created with the given message format URN. :param messageformaturn: the custom data message format URN. :return: a custom data object iotcs.client.device.Data

offer(attributeName, value)

Offer to set the value of an attribute.

The attribute value is set depending upon any policy that may have been configured for the attribute. If there is no policy for the given attribute, offer behaves as if the AbstractVirtualDevice.set(String, Object) method were called. The value is validated according to the constraints in the device model. If the value is not valid, an IllegalArgumentException is raised. :param attributeName: the name of an attribute from the device type model :param value: the value to set :return: this VirtualDevice instance :raises ArgumentException: if the value is not valid, the attribute is not in the model, or attributeName is None

setCallable(actionName, callable)

Set a Callable instance for handling an action, actionName.

Parameters:
  • actionName – The action name
  • callable – The Callbable instance to invoke
Deprecated:
setOnAction(callback, actionName=None)

Set a callback for a specific action or all actions.

If actionName is None, callback is invoked any all requested actions. If actionName is not `None then callback is invoked for that specific actionName

If there is a callback for a specific action and for all actions, both callbacks will be invoked, with the specific action invoked first. :param actionName: The action name from the device model, or None :param callback: the ActionCallback that is inkoked. If None an existing callback is removed.

iotcs.client.ExternalObject

class iotcs.client.ExternalObject(uri)

Bases: object

ExternalObject represents the value of a URI type in a device model.

The application is responsible for uploading/downloading the content referred to by the URI.

Create an ExternalObject.

Parameters:uri – The URI
getURI()

Get the URI value.

Returns:the URI

iotcs.client.StorageObject

class iotcs.client.StorageObject(delegate)

Bases: iotcs.client.client.ExternalObject

StorageObject provides information about content in the cloud storage.

Implementation for <.StorageObject>.

Create a StorageObject.

Parameters:delegate – the StorageObject delegate implementation.
class SyncCallback

Bases: object

A callback interface for receiving a SyncEvent.

This callback is invoked when an attribute value refers to a StorageObject and has been successfully synchronized or has failed to be synchronized with the cloud storage service. See setOnSync

onSync(event)

Call when content is synchronized.

This method is called when a StorageObject attribute value has been successfully synchronized, or has failed to be synchronized.

This method never be invoked by the client library with a None argument. :param event: The synchronization event

class SyncEvent

Bases: object

An event passed to the setOnSync() SyncCallback.

This event occurs when an attribute value’s content refers to a StorageObject and has been successfully synchronized, or has failed to be synchronized.

getName()

Return the name of the attribute, action, or format.

Return the name of the attribute, action, or format that this event is associated with.

Returns:the name, or None if sync() was called independently
getSource()

Return the StorageObject source of this event.

:return the storageObject, never None

getVirtualDevice()

Return the virtual device that is the source of the event.

Returns:the virtual device, or None if sync() was called independently
class SyncStatus

Bases: enum.Enum

The storage cloud content status.

IN_SYNC = 'IN_SYNC'

The upload or download is complete.

NOT_IN_SYNC = 'NOT_IN_SYNC'

The content has not been uploaded or downloaded.

SYNC_FAILED = 'SYNC_FAILED'

The upload or download failed.

SYNC_PENDING = 'SYNC_PENDING'

An upload or download is pending.

getContentType()

Return the mime-type of the content.

See IANA Media Types # noqa: E501 :return: The mime-type of the content

getCustomMetadata()

This method return unmodifiable copy of metadata. :return: a dict of metadata. It may be empty.

getDate()

Return the date and time the content was created or last modified.

Return the date and time the content was created or last modified in the cloud storage in ISO 8601 format. This may be None if the content has not been uploaded.

Returns:The date the content was last modified in cloud storage in ISO 8601 format, or None if the content has not been uploaded.
getEncoding()

Return the compression scheme of the content.

Returns:the compression scheme of the content, or None if the content is not compressed
getInputPath()

Return the input path.

:return the input path, or None if not set

getLength()

Return the length of the content in bytes.

This is the number of bytes required to upload or download the content.

Returns:The length of the content, or -1 if unknown
getName()

Return the the name of this object in the storage cloud.

It is the name and path of the file that was uploaded to the storage cloud.

:return the name of this object in the storage cloud

getOutputPath()

Return the output path.

Returns:the output path, or None if not set
getSyncCallback()

Return syncCallback.

Used internally by the client library. Not intended for general use. :return: the SyncCallback

getSyncStatus()

Return the SyncStatus of this StorageObject.

Returns:the SyncStatus of this StorageObject.
setCustomMetadata(key, value)

Sets the metadata for the StorageObject.

All metdata will be added to Storage Cloud Service as custom metadata with the X-Object-Meta-KeyName header. :param key: The metadata key :param value: The metadata value :raises: Argument if the key or value is None or empty

setInputPath(inputPath)

Set the input path for uploading content to the storage cloud.

The implementation allows for either the input path to be set, or the output path to be set, but not both. If inputPath is not None, the output path will be set to None. If inputPath is not None and does not equal the current input path, syncStatus will be reset to NOT_IN_SYNC This method raises ValueError if getSyncStatus() returns SYNC_PENDING.

Parameters:inputPath – the path from which to read the content for upload
Raises:OSError – if the input path cannot be read
Raises:StateException if called when sync status is SYNC_PENDING.
setOnSync(callback)

Set a StorageObject.SyncCallback.

The callback is invoked when the content referred to by this StorageObject is synchronized.

Parameters:callback – a StorageObject.SyncCallback to invoke when there is an error setting a value, if None, the existing syncCallback is removed.
setOutputPath(outputPath)

Set the output path for downloading content from the storage cloud.

The implementation allows for either the output path to be set, or the input path to be set, but not both. If outputPath is not None, the input path will be set to None. If outputPath is not None and does not equal the current output

syncStatus will be reset to NOT_IN_SYNC. This method raises ValueError if getSyncStatus() returns SYNC_PENDING.

Parameters:outputPath – the path to which the content will be downloaded. If the path does not already exist, it will be created.
Raises:OSError – if the output path cannot be written
Raises:StateException if called when sync status is SYNC_PENDING.
setSyncStatus(syncStatus)

Set the syncStatus.

Used internally by the client library. Not intended for general use. :param syncStatus: the StorageObject.SyncStatus

sync()

Notify the library to sync content with the storage cloud.

The direction of the sync, upload or download, depends on whether inputPath or the outputPath have been set. This method does not start any uploads or downloads if sycn status is other than NOT_IN_SYNC.

This is a non-blocking call. The sync is performed on a separate thread on this StorageObject.

If the input path cannot be read, or the output path cannot be written, an OSError is raised. Any I/O exceptions during the background sync are reported through the virtual device error callback of the virtual device.

Raises:StateException if both input path and output path are None

iotcs.exception

exception iotcs.exception.ArgumentException(*args, **kwargs)

Bases: ValueError

This exception is raised if a method receives an invalid argument.

exception iotcs.exception.HttpException

Bases: Exception

This exception is raised if an HTTPError or HTTTPWarning occurs.

exception iotcs.exception.NetworkException(*args, **kwargs)

Bases: Exception

This exception is raised if an IoT REST API request fails.

exception iotcs.exception.SecurityException(*args, **kwargs)

Bases: Exception

This exception is raised if credentials failure.

exception iotcs.exception.SocketException

Bases: Exception

This exception is raised if a socket error occurs.

exception iotcs.exception.SocketTimeoutException

Bases: Exception

This exception is raised if a socket timeout error occurs.

exception iotcs.exception.StateException(*args, **kwargs)

Bases: Exception

This exception is raised if an object is in an inconsistent state.

exception iotcs.exception.TransportException(status=None, message=None, method=None, path=None, httpresponse=None, *args, **kwargs)

Bases: Exception

This exception is raised if an HTTP error occurs.

Parameters:
  • statuscode – The HTTP error status code
  • message –
  • method –
  • path –
  • httpresponse –
  • args –
  • kwargs –
getStatusCode()

Return the HTTP error status code causing this exception.

Returns:The HTTP error status code causing this exception

iotcs.config module

The config module defines a set of tunable parameters.

The tunable parameter control various behaviors of the library including messaging, network, etc..

# Copyright (c) 2018, 2019, Oracle and/or its affiliates.  All rights reserved.
#
# This software is dual-licensed to you under the MIT License (MIT) and
# the Universal Permissive License (UPL).  See the LICENSE file in the root
# directory for license terms.  You may choose either license, or both.

###############################################################################
[device_model]

# Set this property to a valid path to enable local storage of device models
device_model_store=

# When ${device_model_store} is a valid path device models will have a prefix
# of ${prefix} and suffix of ${suffix}
prefix=dm-
suffix=.json

# Default: false
# If true, a device can be activated without a device model on the server for
# the device. The server will create a
# draft device model which contains no attributes. A draft device model allows
# devices to be brought on-line ahead of the server being provisioned with the
# device model. However, attempts by the device to set an attribute when using a
# draft device model will fail.
allow_draft_device_models=False

##############################################################################
[rest_api]

# Set to True to use the IOT Cloud Service web REST api
use_webapi=False

##############################################################################
[device_messaging]

# Default: 4192 bytes
# The total size all of incoming messages received from the server that have
# not been handled by callbacks to the
# application.
request_buffer_size=4192

# Default: false
# Long polling is used by default, set this to true to disable it.
disable_long_polling=False

# Default: 1
# Number of threads created for dispatching request messages so that
# request handlers can be executed in parallel.
# This number should be specified as greater than one, else it will be ignored
# and the default value of one will be used for request handler thread pool
# size. Request Dispatcher should be used for request handling for this setting
# to be effective.
request_dispatcher_thread_pool_size=1

# Default: 10000
# Total messages to queue. Attempts to send messages when the queue is full
# will result in an error.
dispatcher_max_queue_size=10000

# Default: 100
# Maximum number of outgoing messages to send in one payload per HTTPS
# connection to the server.
dispatcher_max_messages_per_connection=100

# Default: 3 seconds
# The polling interval, in seconds, for message dispatching. If a message is
# not sent to the server within this timeout, an empty message will be sent in
# order to solicit request messages that may be queued in the server.
dispatcher_polling_interval=3000

# Default: 100 milliseconds
# The time, in milliseconds, added to the receive timeout given by the
# application and then used for the client transport timeout.
long_polling_timeout_offset=100

# Default: 100 milliseconds
# Only used when long polling is disabled. The minimum time, in milliseconds,
# since the last send before polling the server for incoming messages if the
# receive buffer is empty. A larger value may cause a delay in the receipt of
# incoming messages, but will cause less network overhead. A value of zero
# will cause the library to skip the poll for incoming messages when calling
# receive if the receive buffer is empty.
send_receive_timeout=100

# Default: 15000 milliseconds
# Only used when long polling is disabled. The amount of time, in milliseconds,
# to wait for the server to respond
# to an HTTPS request.
http_response_timeout=15000

# The number of retry attempts made by the MessageDispatcher
dispatcher_basic_number_of_retries = 3

# The amount of time to wait before dispatching requests that were dispatched
# when initially received, milliseconds
dispatcher_settle_time = 10000

# The maximum number of times to try and obtain an access token
access_token_max_retries = 3

# The number of seconds to wait for a message to become available in the
# message queue or for space to become available if the maximum size,
# dispatcher_max_queue_size, is reached
message_queue_waittime = 10

# Amount of time in milliseconds to backoff in the face of a 503 from the
# server. This is the starting value for the amount of time to backoff.
# The backoff time increases exponentially if the server continues to return
# a 503. Defaults to 1000 milliseconds. Not less than 100 milliseconds.
message_dispatcher_backoff=1000

# The default Message.Reliability for DataMessages.
# One of "GUARANTEED_DELIVERY", "BEST_EFFORT", "NO_GUARANTEE"
data_message_reliability=BEST_EFFORT

# The default Message.Reliability for AlertMessages
# One of "GUARANTEED_DELIVERY", "BEST_EFFORT", "NO_GUARANTEE"
alert_message_reliability=GUARANTEED_DELIVERY

#############################################################################
[diagnostics]

# The client library version
client_version=18.3.5

# The library assumes that if client_ip_address is set,
# client_mac_addrese is also set

# The fixed client IP address
#client_ip_address=192.168.1.10

# The client MAC address
#client_mac_address=XX:XX:XX:XX

# A colon separated string of paths <path0>:<path1> or a single path used
# by diagnostics to collect total and free disk usage
client_paths=.

#############################################################################
[enterprise_messaging]

# Default: 3000 milliseconds
# The amount of delay, in milliseconds, between polls for messages by the
# MessagePoller. This setting affects how
# often a MessageEnumerator.MessageListener instance may be called.
message_polling_interval=3000

# Default: 10
# The maximum number of messages to return on a single poll by the
# MessagePoller. The value will be clamped
# between 10 and 200, inclusive.
message_polling_limit=10

# Default: 10 messages
# The number of messages in each page the message enumerator retrives from the
# server.
message_refill_count=10


##############################################################################
[logging]

# Default: true
# Controls whether or not logged messages should be pretty printed. Pretty
# printing the messages makes the JSON easier to read. By default, pretty
# printing is enabled. Set this property to false to disable pretty printing
# for a more compact view of the logged messages.
pretty_print_messages=False


###############################################################################
[http]

# Default: -1 seconds (default to the servers timeout)
# The maximum time in seconds iotcs.http.SecureConnection will wait for the
# the server to respond to a request. If the library is "long polling"
# "[device_messaging]["disable_long_polling"] == False", the request will wait
# for the server to respond, typically 10 minutes.
# If set to -1 SecureConnection will defer to the server. If greater than zero
# the SecureConnection will use the value set here.
http_connection_timeout=-1

# Default: -1 (default to the servers timeout)
# The maximum time in seconds (a float) iotcs.http.SecureConnection will wait
# for the the server to respond to a request. If the library is "long polling"
# ''["device_messaging"]["disable_long_polling"] == False', the request will
# wait for the server to respond, typically 10 minutes.
# If not set or 0.0 SecureConnection will defer to the server. If greater than
# zero the SecureConnection will use the value set here.
http_read_timeout=-1

# Default: None
# The proxy to use for requests. The form of the url is
# <scheme>://<host>:<port>/ eg. https://proxyserver.com:9090/
# Note: The url MUST have a trailing slash
#proxy=

# Default: None
# The user ID and password, separated by a colon, for basic proxy authentication.
# proxy_auth=userid:password
###############################################################################
[media_storage]

# Default: false
# Disable the prefixing the storage object's name with the device's client ID
# and a directory separator.
disable_storage_object_prefix=False
storage_connection_host_name=storage.oraclecloud.com
storage_connection_retry_limit=2

# Default: None
# The proxy to use for all media storage requests. The form of the url is
# <scheme>://<host>:<port>/ eg. https://proxyserver.com:9090/
# Note: The url MUST have a trailing slash
#proxy=

###############################################################################
[device_policy]

# Default: ETHERNET
# Used by the "batchByCost" device function, set this property to the type of
# connected network. The property may be set from the application code; for
# example, when the type of connected network changes.
network_cost=ETHERNET


###############################################################################
[message_persistence]

# Default: persistence store database name for messages
# The name the database used for persisting messages.
# If a relative path (no leading "/") the library uses the user's HOME
# directory.
db_name=iotcs/msps.db

# Default: true
# If True, the client library will persist data.
enabled=True

###############################################################################
[batchby_persistence]

# Default: persistence store database name for policy batch persistence
# The name the database used for persisting "batchBy" policy data.
# If a relative path (no leading "/") the library uses the user's HOME
# directory
db_name=iotcs/bbps.db

# Default: true
# If True, the client library will persist data.
enabled=True