The device and enterprise client libraries simplify working with the Oracle IoT Cloud Service.
These client libraries are a low–level abstraction over top of messages and REST APIs.
Device clients are primarily concerned with sending data and alert messages to the cloud service,
and acting upon requests from the cloud service. Enterprise clients are primarily concerned
with monitor and control of device endpoints.
- Register your device and/or enterprise application with the Cloud Service.
- Provision the device with the credentials obtained from above.
- Optionally provision the device model.
Configuration
The client must have a configuration in order to communicate with the cloud service. This configuration includes the IoT Cloud Service host, the identifier of the device or enterprise integration the client represents, and the shared secret of the device or enterprise integration.The configuration is created by using the provisioner tool: provisioner.js. This tool creates a file that is used when running the client application. Usage is available by running the tool with the -h argument.
Device and Enterprise Clients
Prerequisites:- Register your device and/or enterprise application with the Cloud Service.
- Provision the device with the credentials obtained from above.
- Optionally provision the device model.
Examples
//The following steps must be taken to run a device-client application.
//The example shows a GatewayDevice. A DirectlyConnectedDevice is identical,
//except for registering indirectly-connected devices.
// 1. Initialize device client
let gateway = new iotcs.device.util.GatewayDevice(configurationFilePath, password);
// 2. Activate the device
if (!gateway.isActivated()) {
gateway.activate([], (device, error) => {
if (!device || error) {
//handle activation error
}
});
// 3. Register indirectly-connected devices
gateway.registerDevice(hardwareId,
{serialNumber: 'someNumber',
manufacturer: 'someManufacturer',
modelNumber: 'someModel'}, ['urn:myModel'],
(response, error) => {
if (!response || error) {
//handle enroll error
}
indirectDeviceId = response;
});
// 4. Register handler for attributes and actions
let messageDispatcher = new iotcs.device.util.MessageDispatcher(gateway);
messageDispatcher.getRequestDispatcher().registerRequestHandler(id,
'deviceModels/urn:com:oracle:iot:device:humidity_sensor/attributes/maxThreshold',
requestMessage => {
//handle attribute update and validation
return iotcs.message.Message.buildResponseMessage(requestMessage, iotcs.StatusCode.OK, {}, iotcs.StatusCode.OK_MESSAGE, '');
});
// 5. Send data from the indirectly-connected device
let message = new iotcs.message.Message();
message
.type(iotcs.message.Message.Type.DATA)
.source(indirectDeviceId)
.format('urn:com:oracle:iot:device:humidity_sensor' + ":attributes");
message.dataItem('humidity', sensor.humidity);
message.dataItem('maxThreshold', sensor.maxThreshold);
messageDispatcher.queue(message);
// 6. Dispose the device client
gateway.close();
//The following steps must be taken to run an enterprise-client application.
// 1. Initialize enterprise client
iotcs.enterprise.EnterpriseClient.newClient(applicationName, (client, error) => {
if (!client || error) {
//handle client creation error
}
ec = client;
});
// 2. Select a device
ec.getActiveDevices('urn:myModelUrn').page('first').then((response, error) => {
if (!response || error) {
//handle get device model error
}
if(response.items){
response.items.forEach(item => {
//handle select of an item as a device
device = item;
});
}
});
// 3. Monitor a device
messageEnumerator = new iotcs.enterprise.MessageEnumerator(ec);
messageEnumerator.setListener(device.id, 'ALERT', items => {
items.forEach(item => {
//handle each item as a message received from the device
});
});
// 4. List the resources of a device
resourceEnumerator = new iotcs.enterprise.ResourceEnumerator(ec, device.id);
resourceEnumerator.getResources().page('first').then(response => {
response.items.forEach(item => {
//handle each item as a resource
});
}, error => {
//handle error on enumeration
});
// 5. Dispose the enterprise client
ec.close();
// This shows how to use the messaging API to upload content to,
// or download content from, the Oracle Storage Cloud Service.
// To upload or download content, there must be an attribute, field,
// or action in the device model with type URI.
// When creating a DataItem for an attribute, field, or action of type URI,
// the value is set to the URI of the content in cloud storage.
//
// Uploading/downloading content without Storage Dispatcher
//
let storageObjectUpload = gateway.createStorageObject("uploadFileName", "image/jpg");
storageObjectUpload.setInputStream(fs.createReadStream("upload.jpg"));
storageObjectUpload.sync(uploadCallback);
let messageDispatcher = new iotcs.device.util.MessageDispatcher(gateway);
messageDispatcher.getRequestDispatcher().registerRequestHandler(id,
'deviceModels/urn:com:oracle:iot:device:motion_activated_camera/attributes/image',
requestMessage => {
//handle URI attribute validation, get URI from request message
gateway.createStorageObject(URI, (storageObjectDownload, error) => {
if (error) {
// error handling
}
// only download if image is less than 4M
if (storageObjectDownload.getLength() < 4 * 1024 * 1024) {
storageObjectDownload.setOutputStream(fs.createWriteStream("download.jpg"));
// downloadCallback have to send response massage
// using messageDispatcher.queue method
storageObjectDownload.sync(downloadCallback);
}
});
return iotcs.message.Message.buildResponseWaitMessage();
});
//
// Uploading/downloading content with Storage Dispatcher
//
let storageDispatcher = new iotcs.device.util.StorageDispatcher(gateway);
storageDispatcher.onProgress = (progress, error) => {
if (error) {
// error handling
}
let storageObject = progress.getStorageObject();
if (progress.getState() === iotcs.StorageDispatcher.Progress.State.COMPLETED) {
// image was uploaded
// Send message with the storage object name
let message = new iotcs.message.Message();
message
.type(iotcs.message.Message.Type.DATA)
.source(id)
.format('CONTENT_MODEL_URN' + ":attributes");
message.dataItem('CONTENT_ATTRIBUTE', storageObject.getURI());
} else if (progress.getState() === iotcs.StorageDispatcher.Progress.State.IN_PROGRESS) {
// if taking too long time, cancel
storageDispatcher.cancel(storageObject);
}
};
let storageObjectUpload = gateway.createStorageObject("uploadFileName", "image/jpg");
storageObjectUpload.setInputStream(fs.createReadStream("upload.jpg"));
storageDispatcher.queue(storageObjectUpload);