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 8M Mini-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.

Instantiating the CloudConnectorManager
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.
Getting 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.

Configuring vendor ID
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
Managing Remote Manager connection
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 8M Mini 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
Managing System Monitoring feature
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.

Cloud Connector events listener
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.

Registering and unregistering an event listener
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.

Getting the CloudConnectorPreferencesManager
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 8M Mini 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 8M Mini 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.

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:

Configuring settings using the CloudConnectorPreferencesManager
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 8M Mini 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.

Cloud Connector Device Request listener
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.

Registering and unregistering an events listener
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:

  1. Log in to your Remote Manager account (https://remotemanager.digi.com).

  2. Go to Documentation > API Explorer.

  3. Select Examples > SCI > Data Service > Send Request.

    Remote Manager automatically creates the necessary code

  4. Replace the "device id" value with the ID of your device.

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

  6. 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.
DataStream constructor 1
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");
DataStream constructor 2
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). 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
DataPoint constructors
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.

Sending a single data point
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);
Sending a list of data points
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). It contains 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.
BinaryDataPoint constructor
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.

Sending a binary data point
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:

  1. Log in to your Remote Manager account (https://remotemanager.digi.com).

  2. Go to the Data Services tab and select Data Streams.

  3. Select the data stream you want to analyze from the list of streams.

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

    Remote Manager: Data Streams

Cloud Connector example

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.