Cloud Connector is a new Android service used to communicate with Remote Manager, a Digi’s proprietary platform to manage devices remotely. This service is disabled by default as some configuration steps are required before running it. You can enable and configure it in the Remote management section of the Android settings. See the Remote management topic for more information about Remote Manager and the ConnectCore 6-specific features.
Cloud Connector includes a rich API that can be used in your applications to communicate with Remote Manager, receive remote commands and save data in the cloud. In the Digi APIx javadoc documentation you can find a complete list of the available methods in this API.
Unless noted, all the Cloud Connector API methods require the com.digi.android.permission.CLOUD_CONNECTOR permission.
If your application does not have the com.digi.android.permission.CLOUD_CONNECTOR permission it will not have access to any Cloud Connector service feature. |
To work with this API and communicate with Remote Manager, the first step is to instantiate a CloudConnectorManager object. To do so, you need to provide the Android application Context.
import android.app.Activity;
import android.os.Bundle;
import com.digi.android.cloudconnector.CloudConnectorManager;
public class CloudConnectorSampleActivity extends Activity {
CloudConnectorManager connectorManager;
[...]
@Override
public void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceStace);
// Instantiate the CloudConnector manager object.
connectorManager = new CloudConnectorManager(this);
[...]
}
[...]
}
The Cloud Connector API includes features that allow you to perform the following actions:
Perform basic operations
Get the device ID
Every device registered in Remote Manager has a unique identifier that is used by the platform to refer and communicate with the device. The device ID is calculated automatically by the service using the MAC address of the Ethernet interface. It can be obtained in the Remote Manager configuration within the Android settings or by using a specific method of the Remote Manager API.
Method | Description |
---|---|
getDeviceID() |
Returns the Cloud Connector Device ID |
You don’t need to be connected to Remote Manager to get the device ID. |
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Get the device ID.
String deviceID = connectorManager.getDeviceID();
Configure the vendor ID
Before connecting to Remote Manager, configure a vendor ID for the device.
The vendor ID is a 4-byte value indicating the manufacturer of the selected device. This value will be used to determine the manufacturer the device belongs to, usually tied to the Remote Manager account.
A vendor ID can be obtained by logging in to your Remote Manager account and navigating to Admin > Account Settings. This will display the My Account page; within the Vendor Information section of the page you can request a vendor ID (if you haven’t already) or view your assigned vendor ID. If you do not properly configure this setting or if it is left empty, an error will be shown while trying to connect.
The format of this setting is:
0xXXXXXXXX
You can configure it in the Remote Manager section of the Android Settings or by using the Cloud Connector API.
Method | Description |
---|---|
getVendorID() |
Returns the device vendor ID |
setVendorID(String) |
Sets the Cloud Connector vendor ID setting |
The setVendorID(String) method may fail for the following reasons: * The specified vendor ID is null, throwing a NullPointerException. * The specified vendor ID does not follow the correct format, throwing an IllegalArgumentException.
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Configure the Vendor ID (remember you must get it from your account page in Remote Manager).
connectorManager.setVendorID("0x12345678");
Configured settings are persistent between boots. There is no need to re-configure Cloud Connector service each time device is powered on. |
Connect/disconnect from Remote Manager
Once the vendor ID is configured, the next step is to open the connection with the platform. Using the Remote Manager API, you can connect or disconnect from Remote Manager at any time. You can manage the connection to Remote Manager using the following methods.
Method | Description |
---|---|
connect() |
Opens the Cloud Connector connection |
disconnect() |
Closes the Cloud Connector connection |
isConnected() |
Returns the Cloud Connector connection status |
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Check if the device is already connected to Remote Manager. If not, connect.
if (!connectorManager.isConnected())
connectorManager.connect();
[...]
// Disconnect from Remote Manager.
connectorManager.disconnect();
Depending on the value of the auto-connect setting of the Remote Manager service, the device may try to connect to Remote Manager automatically as soon as the system is initialized. |
The connect and disconnect processes generate events indicating when the device has connected and disconnected from Remote Manager. See Capture Cloud Connector events. |
Make sure your device is registered within your Remote Manager account before attempting to connect. For more information on registering your device in Remote Manager see Add your ConnectCore 6 to Remote Manager.
Enable/disable the System Monitoring feature
System Monitoring is a feature that comes embedded within the Cloud Connector service and is used to monitor some parameters of the device remotely. See Monitor the system for more information.
This feature can be enabled and configured in the Remote Manager section of the Android settings, but it can be also managed using the following Cloud Connector API methods:
Method | Description |
---|---|
enableSystemMonitor(boolean) |
Enables/disables the system monitor feature |
isSystemMonitorEnabled() |
Returns the current state of the system monitor |
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Check if the System Monitoring is already enabled. If not, enable it.
if (!connectorManager.isSystemMonitorEnabled())
connectorManager.enableSystemMonitor(true);
[...]
// Disable the System Monitor.
connectorManager.enableSystemMonitor(false);
Capture Cloud Connector events
Some processes performed by the Cloud Connector service generate events that you might want to be aware of in order to execute a specific action. The Cloud Connector API allows you to register a listener to be notified when some of these events occur such as:
-
Connection events
-
Data points events
The first thing you must do to listen for Cloud Connector events is to create your events listener. This listener must implement the ICloudConnectorEventListener interface.
import com.digi.android.cloudconnector.ICloudConnectorEventListener;
public class MyEventsListener implements ICloudConnectorEventListener {
@Override
public void connected() {
// TODO
}
@Override
public void disconnected() {
// TODO
}
@Override
public void connectionError(String s) {
// TODO
}
@Override
public void sendDataPointsSuccess() {
// TODO
}
@Override
public void sendDataPointsError(String s) {
// TODO
}
}
The ICloudConnectorEventListener interface implements the following methods to inform you about different events.
Method | Description |
---|---|
connected() |
Notifies that the Cloud Connector service has connected. The connect method returns immediately, but the connection process may take some seconds to complete. |
disconnected() |
Notifies that the Cloud Connector service has disconnected |
connectionError(String) |
Notifies that there was an error connecting and provides the error message |
sendDataPointsSuccess() |
Notifies that the data points have been sent successfully. See Send data to Remote Manager for more information about sending data points. |
sendDataPointsError(String) |
Notifies that there was an error sending the data points and provides the error message |
You must write the code you want to be executed inside the event callbacks you are interested in. You can leave blank the callbacks you don’t want to execute.
The next step is to register your events listener in the CloudConnectorManager instance. If any event is generated after registering your listener, Cloud Connector will execute the code contained in the corresponding callback. If you want to stop receiving events, unregister your events listener.
Method | Description |
---|---|
registerEventListener(ICloudConnectorEventListener) |
Registers the given listener to receive Cloud Connector events |
unregisterEventListener(ICloudConnectorEventListener) |
Removes the given listener from the event listeners list |
The previous methods may fail if the ICloudConnectorEventListener to register or unregister is null throwing a NullPointerException.
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Register an instance of your events listener class to start receiving events.
MyEventsListener myEventsListener = new MyEventsListener();
connectorManager.registerEventListener(myEventsListener);
[...]
// Unregister your events listener to stop receiving events.
connectorManager.unregisterEventListener(myEventsListener);
Configure Cloud Connector service
The Cloud Connector service comes already configured with some default values. You can check the configuration and modify it in the Remote Manager section of the Android settings, or you can use the Cloud Connector API to do so.
It does not matter if you modify a setting using the Android settings menu or the Cloud Connector API. Settings values are saved in the Android system and their value will prevail after a reboot. |
The first step to read or modify Cloud Connector settings using the Cloud Connector API is to get the CloudConnectorPreferencesManager from the CloudConnectorManager.
import com.digi.android.cloudconnector.CloudConnectorManager;
import com.digi.android.cloudconnector.CloudConnectorPreferencesManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Get the CloudConnectorPreferencesManager object.
CloudConnectorPreferencesManager preferencesManager = connectorManager.getPreferencesManager();
All the settings within the CloudConnectorPreferencesManager are set and get the same way, but they can be categorized in the following groups for a better understanding of them.
Device information
Settings of this group allow you to give some descriptive information about your device in Remote Manager. This information can be accessed through the platform and may help you to identify your devices in an easy way.
Device ID
Device ID is used to identify the device in Remote Manager. A Device ID is a 16-octet number that is unique to the device and does not change over its lifetime. The Device ID of a ConnectCore 6 is derived from the MAC address of the Ethernet interface.
The canonical method for writing Device IDs is as four groups of eight hexadecimal digits separated by a dash, as follows:
XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX
The device ID is automatically generated by the Cloud Connector service, so it cannot be set. It is a read-only setting of the CloudConnectorPreferencesManager.
Method | Description |
---|---|
getDeviceID() |
Returns the Device ID |
Vendor ID
The vendor ID is a 4-byte value indicating the manufacturer of the selected device. This value will be used to determine the manufacturer the device belongs to, usually tied to the Remote Manager account.
You can obtain a vendor ID by logging in to your Remote Manager account and navigating to Admin > Account Settings. The My Account page is displayed; within the Vendor Information section of the page you can request a vendor ID (if you haven’t already) or view your assigned vendor ID. If you do not properly configure this setting or if it is left empty, an error will be shown while trying to connect.
The format of this setting is:
0xXXXXXXXX
Before connecting your device to Remote Manager it is very important to get and configure a vendor ID.
Method | Description |
---|---|
getVendorID() |
Returns the device vendor ID |
setVendorID(String) |
Sets the Cloud Connector vendor ID setting |
The setVendorID(String) method may fail for the following reasons:
-
The specified vendor ID is null, throwing a NullPointerException.
-
The specified vendor ID does not follow the correct format, throwing an IllegalArgumentException.
Device name
This value is the device’s model information. It is a string that uniquely identifies this model of a device in the Remote Manager server. When the server finds two devices with the same device name, it infers that they are the same product and product-scoped data may be shared among all devices of the same device type. A device’s type cannot be an empty string, nor contain only white-spaces.
The device name along with the firmware version and vendor ID setting are used by Remote Manager to cache the RCI device descriptor. Changing any of these values will cause Remote Manager to ask the device for a new RCI device descriptor.
Method | Description |
---|---|
getDeviceName() |
Returns the configured device name preference |
setDeviceName(String) |
Sets the device name preference |
The setDeviceName(String) method may fail for the following reasons:
-
The specified device name is null, throwing a NullPointerException.
-
The length of the device name is 0 or greater than CloudConnectorPreferencesManager.DEVICE_NAME_MAXIMUM_LENGTH, throwing an IllegalArgumentException.
Device description
This setting is a description of the device running Cloud Connector service. It allows descriptive device information to be assigned to each of your devices.
Method | Description |
---|---|
getDeviceDescription() |
Returns the configured device description preference |
setDeviceDescription(String) |
Sets the device description preference |
The setDeviceDescription(String) method may fail for the following reasons:
-
The specified description is null, throwing a NullPointerException.
-
The length of the description is greater than CloudConnectorPreferencesManager.DESCRIPTION_MAXIMUM_LENGTH, throwing an IllegalArgumentException.
Contact information
Contact information of the maintainer of this device.
Method | Description |
---|---|
getDeviceContactInformation() |
Returns the configured device contact information preference |
setDeviceContactInformation(String) |
Sets the device contact information preference |
The setDeviceContactInformation(String) method may fail for the following reasons:
-
The specified contact information is null, throwing a NullPointerException.
-
The length of the contact information is greater than CloudConnectorPreferencesManager.CONTACT_MAXIMUM_LENGTH, throwing an IllegalArgumentException.
Connection
The CloudConnectorPreferencesManager allows you to configure some parameters related to the connection established by the ConnectCore 6 and Remote Manager.
Connection URL
The URL of Remote Manager is not intended to change, but it is possible to modify it if you want to use a different Remote Manager server such as a test server.
Method | Description |
---|---|
getURL() |
Returns the configured Cloud Connector URL preference |
setURL(String) |
Sets the Cloud Connector URL preference |
The setURL(String) method may fail if the specified URL is null, throwing a NullPointerException.
CAUTION! The value of this setting should be always set to remotemanager.digi.com. |
Auto-connect
This setting is used to indicate the Cloud Connector service that it should try to connect to Remote Manager just after booting or if the Internet connection is lost.
Method | Description |
---|---|
isAutoConnectEnabled() |
Returns whether auto-connect setting is enabled |
setAutoConnectEnabled(boolean) |
Sets the new value of the auto-connect setting |
This setting is disabled by default. |
Secure connection
This setting allows you to connect to Remote Manager using the secure protocol (SSL) or to establish standard TCP connection. When the setting is enabled, Cloud Connector will use the secure protocol (SSL) to connect to Remote Manager. If it is disabled, Cloud Connector will establish a standard TCP connection.
Method | Description |
---|---|
isSecureConnectionEnabled() |
Returns whether secure connection is enabled |
setSecureConnectionEnabled(boolean) |
Sets the new value for the use secure connection setting |
This setting is disabled by default. Changes applied to this setting only take effect after a re-connection. |
Message compression
This setting can be used to reduce the amount of network traffic. If the setting is enabled, Cloud Connector will use ZLib compression while sending/receiving data from Remote Manager.
Method | Description |
---|---|
isCompressionEnabled() |
Returns whether messages compression is enabled |
setCompressionEnabled(boolean) |
Sets the new value of the compress messages setting |
This setting is disabled by default. Changes applied to this setting only take effect after a re-connection. |
System monitor
System monitoring feature of Cloud Connector allows you to control some parameters of the device remotely. See Monitor the system.
System monitoring can currently get sample values of the System memory, CPU load, and CPU temperature. From the CloudConnectorPreferencesManager you can enable or disable this feature and configure some advanced settings such as the parameters to monitor.
Method | Description |
---|---|
isSystemMonitorEnabled() |
Returns the current state of the system monitor |
enableSystemMonitor(boolean) |
Sets the new value of the enable system monitor setting |
This setting is disabled by default. |
Sample rate
This is the time in seconds at which samples of each parameter are captured. Samples are captured and saved until they reach the getSystemMonitorUploadSamplesSize() value. Then, they are uploaded to Remote Manager.
Method | Description |
---|---|
getSystemMonitorSampleRate() |
Returns the system monitor sample rate |
setSystemMonitorSampleRate(int) |
Sets the system monitor sample rate |
The setSystemMonitorSampleRate(int) method may fail if the sample rate set is lower than five, throwing an IllegalArgumentException.
Samples before uploading
This System monitoring setting establishes the number of samples of each parameter to capture before uploading them to Remote Manager.
Method | Description |
---|---|
getSystemMonitorUploadSamplesSize() |
Returns the system monitor number of samples to store for each channel before uploading to Remote Manager |
setSystemMonitorUploadSamplesSize(int) |
Sets the system monitor number of samples to store for each channel before uploading to Remote Manager. |
The setSystemMonitorUploadSamplesSize(int) method may fail if the samples size value to set is lower than one or if it is greater than the maximum upload samples size (CloudConnectorPreferencesManager.MAXIMUM_UPLOAD_SAMPLES_SIZE), throwing an IllegalArgumentException.
Monitor system memory
This setting enables or disables the system memory monitoring. It is the total RAM memory used by the device in MB.
Method | Description |
---|---|
isSystemMonitorMemorySamplingEnabled() |
Returns whether the system monitor memory sampling is enabled |
enableSystemMonitorMemorySampling(boolean) |
Sets the new value of the enable system monitor memory sampling |
Monitor CPU load
With this setting you can enable or disable the CPU load parameter in the System monitoring feature. The CPU load is measured in %.
Method | Description |
---|---|
isSystemMonitorCPULoadSamplingEnabled() |
Returns whether the system monitor CPU load sampling is enabled |
enableSystemMonitorCPULoadSampling(boolean) |
Sets the new value of the enable system monitor CPU load sampling |
Monitor CPU temperature
This setting allows you to enable or disable the CPU temperature parameter in the System monitoring feature. The value of the temperature is taken and saved in Remote Manager in Celsius.
Method | Description |
---|---|
isSystemMonitorCPUTemperatureSamplingEnabled() |
Returns whether the system monitor CPU temperature sampling is enabled |
enableSystemMonitorCPUTemperatureSampling(boolean) |
Sets the new value of the enable system monitor CPU temperature sampling |
Configuration example
This is a usage example of the CloudConnectorPreferencesManager object:
import com.digi.android.cloudconnector.CloudConnectorManager;
import com.digi.android.cloudconnector.CloudConnectorPreferencesManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Get the CloudConnectorPreferencesManager object.
CloudConnectorPreferencesManager preferencesManager = connectorManager.getPreferencesManager();
// Configure device information parameters.
preferencesManager.setVendorID("0x12345678");
preferencesManager.setDeviceDescription("My device description");
preferencesManager.setContactInformation("my.name@company.com");
// Configure some connection parameters.
if (!preferencesManager.isAutoConnectEnabled())
preferencesManager.setAutoConnectEnabled(true);
if (!preferencesManager.isSecureConnectionEnabled()) {
preferencesManager.setSecureConnectionEnabled(true);
// This setting requires a re-connection in order to apply it.
connectorManager.disconnect();
connectorManager.connect();
}
// Configure the System monitoring and enable it. With this configuration
// the System monitoring will upload a total of 10 samples of each parameter
// every 150 seconds.
preferencesManager.setSystemMonitorSampleRate(15);
preferencesManager.setSystemMonitorUploadSamplesSize(10);
if (!preferencesManager.isSystemMonitorEnabled())
preferencesManager.enableSystemMonitor(true);
Receive data from Remote Manager
Another feature provided by the Cloud Connector service is to receive data from Remote Manager, also known as receiving Device Requests. Transfers are initiated from a Web Services client connected to Remote Manager, which hosts the ConnectCore 6 device. This transfer is used to send data to the device and the device may send a response back.
In order to make your application aware of Device Requests sent to the device, first create your own Device Requests listener. This listener class must implement the IDeviceRequestListener interface.
import com.digi.android.cloudconnector.IDeviceRequestListener;
class MyDeviceRequestListener implements IDeviceRequestListener {
@Override
public String handleDeviceRequest(String target, byte[] data) {
return null;
}
@Override
public String handleDeviceRequest(String target, String data) {
return null;
}
}
The IDeviceRequestListener interface implements the following methods to handle the data sent through the Cloud.
Method | Description |
---|---|
handleDeviceRequest(String, byte[]) |
Handles a binary device request for the given target with the given data |
handleDeviceRequest(String, String) |
Handles a plain device request for the given target with the given data |
The first parameter corresponds to the target name, which is the identifier of the Device Request. The second parameter is the data of the Device Request and, depending on the callback executed, it is provided as a string or as a byte array. The methods optionally return a string which will be sent to Remote Manager as response of the Device Request. The maximum data size of a Device Request is 2MB.
The handleDeviceRequest(String, byte[]) callback is only executed when the data format of the request sent to the device is base64. |
Write inside each callback the code you want to be executed. You can use the first parameter of the callbacks (target) to identify the ID of the Device Request received.
The next step is to register your Device Requests listener in the CloudConnectorManager instance for a specific target. Whenever a Device Request for the registered target is received by the device after registering your listener, Cloud Connector will execute the code contained in the corresponding callback. If you want to stop listening for Device Requests, unregister your listener.
Method | Description |
---|---|
registerDeviceRequestListener(String, IDeviceRequestListener) |
Registers the given listener to receive Device Requests from the Cloud Connector for the given target |
unregisterDeviceRequestListener(IDeviceRequestListener) |
Removes the given listener from the Device Request listeners list |
The previous methods may fail if the IDeviceRequestListener to register or unregister is null, throwing a NullPointerException.
import com.digi.android.cloudconnector.CloudConnectorManager;
[...]
// Instantiate the CloudConnector manager object.
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
// Register an instance of your Device Request listener class to start receiving Device Requests
// with target "myTarget".
MyDeviceRequestListener myDeviceRequestListener = new MyDeviceRequestListener();
connectorManager.registerDeviceRequestListener("myTarget", myDeviceRequestListener);
[...]
// Unregister your Device Request listener to stop listening for Device Requests.
connectorManager.unregisterDeviceRequestListener(myDeviceRequestListener);
Use the API Explorer to send Device Requests
A Device Request can be sent via Web Services within the Remote Manager platform. If you have implemented a Device Request listener and you want to test it, follow these steps:
-
Log in to your Remote Manager account (https://remotemanager.digi.com).
-
Go to Documentation > API Explorer.
-
Select Examples > SCI > Data Service > Send Request.
Remote Manager automatically creates the necessary code
-
Replace the "device id" value with the ID of your device.
-
Enter your target name and data for the device request.
Remote Manager - API Explorer<sci_request version="1.0"> <data_service> <targets> <device id="00000000-00000000-00000000-00000000"/> </targets> <requests> <device_request target_name="myTarget"> This is a Device Request sample </device_request> </requests> </data_service> </sci_request>
-
Click Send.
Send data to Remote Manager
The Cloud Connector service allows you to store time-series data in Remote Manager that can be retrieved later by an external application using WEB services. This feature is also known within Remote Manager as Data streams.
Virtually any type of data can be stored and you can create real-time charts to monitor your data streams. Data streams are fully searchable and the data within a stream can be rolled up into time interval summaries. Data is stored and replicated in multiple secure, commercial-grade storage systems to ensure complete data protection.
Time series data involves two concepts:
-
Data points are the individual values which are stored in Data streams with a unique time stamp.
-
Data streams are containers of data points. Data streams hold metadata about the data points held within them. Data streams and the data points they hold are addressed using hierarchical paths (much like folders).
Data stream
Before sending a data point to Remote Manager, you need to define the data stream that will hold it. Remember that a data stream can store multiple data points of the same type. A DataStream object (com.digi.android.cloudconnector.DataStream) represents the destination of data points in Remote Manager. For example, a DataStream object with name "temperature" will create a stream in Remote Manager with the path <DeviceID>/temperature, where <DeviceID> is the ID of your device.
A data stream can be instantiated providing just the name in the constructor and configuring the rest of parameters later, or providing all the settings directly in the constructor. Once instantiated, you can manage its parameters with the following methods.
Method | Description |
---|---|
getName() |
Returns the name of this data stream |
getForwardTo() |
Returns an array of data stream names to replicate data points to* |
setForwardTo(String[]) |
Sets the list of streams to replicate data points to |
getUnits() |
Returns the units for this data stream |
setUnits(Stream) |
Sets the data stream units |
*The list of data stream names contains the names of those data streams to replicate data points to. So, as soon as a data point is stored in the data stream, it will be also copied or replicated in each data stream whose name is contained in that list. |
import com.digi.android.cloudconnector.DataStream;
[...]
// Create a new DataStream with "temperature" as name and "C" as units.
DataStream temperatureDataStream = new DataStream("temperature");
temperatureDataStream.setUnits("C");
import com.digi.android.cloudconnector.DataStream;
[...]
// Create a new DataStream with "temperature" as name and "C" as units.
DataStream temperatureDataStream = new DataStream("temperature", "C", new String[0]);
Data point
A data point is defined by the DataPoint class (com.digi.android.cloudconnector.DataPoint) and it represents a single value that is stored at a specific time in a data stream in Remote Manager.
The data point value and the stream destination (a DataStream object) are required to create a DataPoint. You need to use the correct constructor depending on the value type of the data point. Android system time is used as a time stamp for the data point when it is instantiated. Other attributes such description, quality and location, can be specified using the corresponding set methods.
Method | Description |
---|---|
getData() |
Returns the data point data |
getDataStream() |
Returns the data stream destination of the data point |
getTimestamp() |
Returns the data point time stamp |
getDescription() |
Returns the data point description |
setDescription(String) |
Sets the data point description |
getLocation() |
Returns the data point location |
setLocation(android.location.Location) |
Sets the data point location |
getQuality() |
Returns the data point quality |
setQuality(int) |
Sets the data point quality |
import com.digi.android.cloudconnector.DataPoint;
import com.digi.android.cloudconnector.DataStream;
[...]
DataStream temperatureDataStream = new DataStream("temperature", "C", new String[0]);
DataStream inValveDataStream = new DataStream("inValve", "", new String[0]);
DataStream levelDataStream = new DataStream("level", "%", new String[0]);
DataPoint temperatureDataPoint = new DataPoint(20.7f, temperatureDataStream);
temperatureDataPoint.setDescription("Tank temperature");
DataPoint inValveDataPoint = new DataPoint(true, inValveDataStream);
inValveDataPoint.setDescription("In valve status");
DataPoint levelDataPoint = new DataPoint(64, levelDataStream);
levelDataPoint.setDescription("Tank level percentage");
Once all data points are created, send them to Remote Manager using one of the following methods within the CloudConnectorManager object.
Method | Description |
---|---|
sendDataPoint(DataPoint) |
Sends the given DataPoint to Remote Manager |
sendDataPoints(List<DataPoint>) |
Sends the given list of DataPoint to Remote Manager |
The sendDataPoint(DataPoint) method may fail for the following reasons:
-
The specified DataPoint is null, throwing a NullPointerException.
-
Cloud Connector is disconnected from Remote Manager, throwing an UnsupportedOperationException.
The sendDataPoints(List<DataPoint>) method may fail for the following reasons:
-
The specified DataPoint list is null, throwing a NullPointerException.
-
Cloud Connector is disconnected from Remote Manager throwing an UnsupportedOperationException.
-
Size of data points list is less than CloudConnectorManager.MINIMUM_DATA_POINTS or size of data points list is greater than CloudConnectorManager.MAXIMUM_DATA_POINTS, throwing an IllegalArgumentException.
import com.digi.android.cloudconnector.CloudConnectorManager;
import com.digi.android.cloudconnector.DataPoint;
import com.digi.android.cloudconnector.DataStream;
[...]
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
connectorManager.connect();
DataStream myDataStream = new DataStream("temperature", "C", new String[0]);
DataPoint dataPoint1 = new DataPoint(20.7f, myDataStream);
DataPoint dataPoint2 = new DataPoint(21.2f, myDataStream);
DataPoint dataPoint3 = new DataPoint(21.5f, myDataStream);
// Upload data points to Remote Manager one by one.
connectorManager.sendDataPoint(dataPoint1);
connectorManager.sendDataPoint(dataPoint2);
connectorManager.sendDataPoint(dataPoint3);
import com.digi.android.cloudconnector.CloudConnectorManager;
import com.digi.android.cloudconnector.DataPoint;
import com.digi.android.cloudconnector.DataStream;
[...]
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
connectorManager.connect();
DataStream myDataStream = new DataStream("temperature", "C", new String[0]);
ArrayList<DataPoint> datapoints = new ArrayList<DataPoint>();
dataPoints.add(new DataPoint(20.7f, myDataStream));
dataPoints.add(new DataPoint(21.2f, myDataStream));
dataPoints.add(new DataPoint(21.5f, myDataStream));
// Upload a list of data points to Remote Manager.
connectorManager.sendDataPoints(datapoints);
The process that uploads data points to Remote Manager generates events that can be captured by your application. Send methods return immediately so if you want to track the result of the operation you need to use Cloud Connector events listeners. See Capture Cloud Connector events for more information about events.
Binary data point
If you need to minimize the data traffic, use the binary concise alternative format to send data points to Remote Manager. It satisfies the requirement of being concise and less verbose than the sendDataPoint method: you can specify a simple binary value, when you push this value to Remote Manager it will be stored as is, in the exact binary format you provided.
To use this format, binary data points have to be defined. They are represented by the class BinaryDataPoint (com.digi.android.cloudconnector.BinaryDataPoint) and contain a single value that it is stored at a specific time in a data stream in Remote Manager, similar to the DataPoint objects with the following differences:
-
Their data is always a byte array.
-
They do not have other attributes such as description, quality or location.
-
The timestamp will be always set by Remote Manager when the value is received.
-
The data stream containing binary data points will not have units and it is not possible to use a list of other data streams names to replicate data points. This is, the units and forwardTo attributes of the associated DataStream object will not be used.
The constructor needs the value of the binary data point (which is an array of bytes) and the DataStream object as parameters. Once instantiated you can get some of its parameters using the following methods.
Method | Description |
---|---|
getData() |
Returns a copy of the data point data |
getDataStream() |
Returns the data stream destination of the data point. |
import com.digi.android.cloudconnector.BinaryDataPoint;
import com.digi.android.cloudconnector.DataStream;
[...]
DataStream binaryDataStream = new DataStream("binaryData");
BinaryDataPoint binaryDataPoint = new BinaryDataPoint(new byte[16], binaryDataStream);
The binary concise mechanism has the following limitations:
-
Only a single binary data point can be uploaded at the same time.
-
The data of the BinaryDataPoint object must be smaller than 64KB.
Once you have your binary data point instantiated you can upload it to Remote Manager using the following method of the CloudConnectorManager object.
Method | Description |
---|---|
sendBinaryDataPoint(BinaryDataPoint) |
Sends the given BinaryDataPoint to Remote Manager. |
The sendBinaryDataPoint(BinaryDataPoint) method may fail for the following reasons:
-
The specified BinaryDataPoint is null, throwing a NullPointerException.
-
Cloud Connector is disconnected from Remote Manager, throwing an UnsupportedOperationException.
-
The binary value to be sent is less than CloudConnectorManager.MAX_SIZE_OF_BINARY_DATA_POINTS_KB, throwing an IllegalArgumentException.
import com.digi.android.cloudconnector.BinaryDataPoint;
import com.digi.android.cloudconnector.CloudConnectorManager;
import com.digi.android.cloudconnector.DataStream;
[...]
CloudConnectorManager connectorManager = new CloudConnectorManager(this);
connectorManager.connect();
DataStream binaryDataStream = new DataStream("binaryData");
BinaryDataPoint binaryDataPoint = new BinaryDataPoint(new byte[16], binaryDataStream);
// Upload the binary data point to Remote Manager.
connectorManager.sendBinaryDataPoint(binaryDataPoint);
Reviewing data stream series in Remote Manager
You can view the data points stored in the cloud (in charts and in text format) from the Remote Manager platform. To do so, follow these steps:
-
Log in to your Remote Manager account (https://remotemanager.digi.com).
-
Go to the Data Services tab and select Data Streams.
-
Select the data stream you want to analyze from the list of streams.
-
In the box below, select the format to represent the values (Charts or Raw Data). Data points contained in the data stream are displayed in a chart or in a list.
Cloud Connector example
Example: Cloud Connector |
---|
The Cloud Connector Sample Application demonstrates the usage of the Cloud Connector API. In this example, you can enable and disable the service, configure some parameters, send data to Remote Manager and receive commands remotely. You can import the example using Digi’s Android Studio plugin. For more information, see Import a Digi sample application. To look at the application source code, go to the GitHub repository. |