iotcs.client.client module¶

class iotcs.client.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

class iotcs.client.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

class iotcs.client.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

class iotcs.client.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

class iotcs.client.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.

delegate¶

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`.

inputPath¶

outputPath¶

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

syncCallback¶

syncStatus¶