To connect your device to Device Cloud there are several required steps:
|
|
Before starting the creation of a Device Cloud connected application, the specific Cloud Connector for your platform should be provided.
In this guide we will use the |
To properly establish a connection with Device Cloud, you must configure Cloud Connector. General and Connection Settings of the connector_config.txt file manage the device identification and the TCP connection with Device Cloud. This is very important because it defines the way the application communicates with Device Cloud.
|
|
The configuration of Cloud Connector includes more settings that will not be covered in this section. Next topics will cover some of the configurations needed. For more information about all the settings, read the Cloud Connector Configuration section. |
This category includes some parameters that make a device unique for Device Cloud:
vendor_id. The vendor ID is assigned by Device Cloud to uniquely identify the manufacturer of a product; you can retrieve the vendor ID from your Device Cloud account.hardware_name. Also known as Device Type, this is the device's model information. It is a string that uniquely identifies this model of a device in Device Cloud. When Device Cloud finds two devices with the same device type and Vendor ID, it infers that they are the same product and product-scoped data may be shared among all devices with this device type. A device's type cannot be an empty string, nor contain only white space.device_id contains the Device ID, a unique identifier for the device itself. There are several means of generating one: from a MAC address, IMEI number, providing one statically or even asking Device Cloud for a unique identifier.device_id_type determines the way your Device ID will be generated, using the MAC address of the device (mac), its IMEI number (imei), retrieving one from Device Cloud (provisioning) or specifying it manually (static).firmware_version is a mandatory parameter which contains the version of the application running Cloud Connector. The firmware version cannot be empty, it should be a numeric value with at most 4 levels: X.X.X.X.description represents a description of the device running Cloud Connector. This setting is optional and can be left blank.contact is a parameter that contains the contact information of the maintainer of the device. This is an optional parameter that can be left blank.location is an optional parameter that is a readable location of the device.Some parameters manage the TCP connection with Device Cloud. Basically there are three decisions to be taken: Connection cluster, Keepalive and Reconnect configuration and Connection type.
This will vary depending on which cloud you selected when you initially created your account: Device Cloud US (login.etherios.com) or Device Cloud Europe (login.etherios.co.uk).
url parameter value specifies the Device Cloud cluster the application will connect to. This parameter cannot be empty should be login.etherios.com or login.etherios.co.uk.One characteristic of the Device Cloud’s TCP connection is that it needs to periodically send keepalive messages so the connection keeps opened in both directions:
server_keep_alive_time is the TX Keepalive interval, how often Device Cloud sends keepalives to the device.keep_alive_time represents the RX Keepalive interval, how often the device sends keepalives to Device Cloud.wait_time determines the number of lost keepalives messages before considering the connection lost.You must decide how often they are sent in both directions and how many of them can be missed before dropping the connection. As a rule of thumb, both intervals are set to 75 seconds and the wait count is set to 5.
So the device is properly connected to Device Cloud… but what would happen if your precious Ethernet cable is cut or your roaming device goes beyond its carrier coverage? Cloud Connector can attempt to reconnect after a connection is lost:
enable_reconnect if set to True, Cloud Connector will re-attempt to connect to Device Cloud after the connection is lost or there is a connection error.reconnect_time determines the time in seconds to wait before reattempting to connection to Device Cloud.The TCP connection can be configured to use the secure protocol and or use compression. Also, a password can be provided to verify the identity of a device. To learn more about how to configure the password in Device Cloud, please refer to the Device Cloud Programming Guide.
enable_secure_connection allows you to connect to Device Cloud using the secure protocol (SSL) or to establish a standard TCP connection.
 | A device establishes a TCP connection to Device Cloud over TCP ports:
Therefore these ports must be open for outbound traffic. |
enable_compression, optional data compression to reduce the amount of network traffic.authorization_type determines the type of authorization to use to connect to Device Cloud: none or basic password authorization.password the connection authorization password to be used if the authorization_type is set to basic.Once your device is properly identified and the connection configured, you can start writing code.
Connecting to Device Cloud requires an instance of the AbstractPlatformConnector class. This is an abstract class in the Cloud Connector core library and your platform specific implementation should include a subclass of it.
The example of Cloud Connector platform implementation given in this SDK, CloudConnector. It has several constructors to provide extra functionality to the application that will be explained in the following sections, but now we are using the no-argument constructor.
| Cloud Connector object instantiation |
import com.etherios.connector.emulator.CloudConnector; [...] // New Cloud Connector object CloudConnector connector = new CloudConnector(); |
Once everything is properly configured it is time to connect to Device Cloud. This is as easy as calling the start method of the Cloud Connector object. This method will open a secure or standard connection with the specified Device Cloud cluster.
| Connecting to Device Cloud |
[...] // New Cloud Connector object CloudConnector connector = ...; // Connect to Device Cloud connector.start(); [...] |
To disconnect your application from Device Cloud use the stop method of the Cloud Connector object. This method will immediately close the connection with Device Cloud freeing the allocated resources locally and remotely. This might be useful in some scenarios, such as a device that is going to sleep for a long time.
| Disconnecting from Device Cloud |
[...] // New Cloud Connector object CloudConnector connector = ...; [...] // Disconnect from Device Cloud connector.stop(); [...] |
Your application might want to be aware of the connection events that are taking place so it can process them and maybe execute a specific action.
Registering a listener allows the application to be notified when the connection process has started, when it is finally connected, or if at any time it is disconnected, or if a connection error occurs.
| Events listener registration |
[...] // New Cloud Connector object CloudConnector connector = new CloudConnector(); // Register the event listeners connector.registerEventsListener(new MyEventsListener()); // Connect to Device Cloud connector.start(); [...] |
This listener, MyEventsListener, implements the EventsListener interface which includes several methods to inform about different events, including connection events.
| EventListener implementation example, MyEventsListener |
import com.etherios.connector.core.events.ConnectionEvent;
import com.etherios.connector.core.events.EventsListener;
public class MyEventsListener implements EventsListener {
public void notifyConnectionEvent(ConnectionEvent event) {
}
[...]
}
|
The method notifyConnectionEvent is called to notify that a connection event occurred. It receives a ConnectionEvent and its type can be obtained using the getConnectionEventType method. Then it can be casted to the corresponding class depending on its type:
StartingConnectionEvent.ConnectedEvent.DisonnectedEvent.ConnectionErrorEvent. Get the connection error type using the method getConnectionErrorType of this object.| notifyConnectionEvent implementation example |
import com.etherios.connector.core.events.ConnectionEvent;
import com.etherios.connector.core.events.ConnectionEvent.ConnectionErrorEvent;
import com.etherios.connector.core.events.EventsListener;
[...]
public class MyEventsListener implements EventsListener {
[...]
public void notifyConnectionEvent(ConnectionEvent event) {
switch (event.getConnectionEventType()) {
case ConnectionEvent.CONNECTION_STARTING:
System.out.println(">>> Connecting to Device Cloud...");
// Handle starting connection event properly
[...]
break;
case ConnectionEvent.CONNECTION_CONNECTED:
System.out.println(">>> Connected to Device Cloud");
// Handle connection event properly
[...]
break;
case ConnectionEvent.CONNECTION_DISCONNECTED:
System.out.println(">>> Disconnected from Device Cloud");
// Handle disconnection event properly
[...]
break;
case ConnectionEvent.CONNECTION_ERROR:
System.out.println(">>> Error on connection with Device Cloud > "
+ event.getEventLogString());
handleConnectionError((ConnectionErrorEvent) event);
break;
default:
System.out.println("Unknown connection event type: "
+ event.getConnectionEventType());
// Handle unknown event properly
[...]
break;
}
}
private void handleConnectionError(ConnectionErrorEvent errorEvent) {
switch (errorEvent.getConnectionErrorType()) {
case ConnectionErrorEvent.ERROR_UNABLE_TO_CONNECT:
[...]
break;
case ConnectionErrorEvent.ERROR_CONNECTION_LOST:
[...]
break;
case ConnectionErrorEvent.ERROR_SERVER_UNAVAILABLE:
[...]
break;
case ConnectionErrorEvent.ERROR_BAD_VERSION:
[...]
break;
case ConnectionErrorEvent.ERROR_SERVER_OVERLOAD:
[...]
break;
case ConnectionErrorEvent.ERROR_WRONG_ID:
[...]
break;
case ConnectionErrorEvent.ERROR_NO_CONNECTION:
[...]
break;
case ConnectionErrorEvent.ERROR_SECURITY_FAILURE:
[...]
break;
case ConnectionErrorEvent.ERROR_CANNOT_RESOLVE_HOST:
[...]
break;
case ConnectionErrorEvent.ERROR_DESCRIPTOR_ERROR:
[...]
break;
case ConnectionErrorEvent.ERROR_DEVICE_ID_NOT_RECEIVED:
[...]
break;
case ConnectionErrorEvent.ERROR_INVALID_VENDOR_ID:
[...]
break;
case ConnectionErrorEvent.ERROR_INTERNET_NOT_AVAILABLE:
[...]
break;
default:
// Handle unknown error type properly
break;
}
}
[...]
}
|
To establish the connection with Device Cloud the following API permissions are required:
Depending on the connection type you are going to use, standard or secure (defined by the enable_secure_connection value in the configuration file) you will need also:
enable_secure_connection=False):enable_secure_connection=True):Once the Device Cloud application is running you can verify it is properly connected by entering in your Device Cloud account and selecting the Device Management tab. Your device should be listed in the table as connected with the following values:
hardware_name parameter of the connector_config.txt file.description parameter of the configuration file.firmware_version parameter.device_id_type parameter.
You can refer to any of the sample applications included in this SDK to review the implementation of the Device Cloud connection using Cloud Connector: