Open Gurus Let's Try

Device Cloud is a device management platform and data service that allows you to connect any device to any application, anywhere. As a public cloud service,

it is designed to provide easy integration between devices and the Device Cloud by Etherios to facilitate real-time network management and rapid M2M application development. It is simple to integrate client software, Web applications or mobile applications to Device Cloud, using Etherios Cloud Connector and open source APIs.

Device Cloud securityThe Etherios Cloud Security Office fiercely protects the confidentiality, integrity and availability of the Device Cloud service. With over 175 different security controls in place that take into account security frameworks including ISO27002’s ISMS, NERC’s critical infrastructure protection (CIP)

Etherios Cloud Connector allows you to seamlessly connect any M2M device to Device Cloud by Etherios.

Get to Know the Etherios Cloud Connector

guidance, the payment card industry’s PCI-DSS v2, the Cloud Security Alliance’s (CSA) Cloud Controls Matrix, as well as relevant HIPAA and NIST standards, Device Cloud customers are assured that there is no safer place for their data.

Etherios Cloud Connector Etherios Cloud Connector is a software development package that is ANSI X3.159-1989 (ANSI C89) and ISO/IEC 9899:1999 (ANSI C99) compliant and enables devices to exchange information with Device Cloud over theInternet, securely.

The devices could range from Arduino boards and Freescale or Intel chips, to PIC or STM microcontrollers, a Raspberry Pi microcomputer or a smartphone.

Etherios Cloud Connector enables application-to-device data interaction (messaging), application and

88 | May 2014 | OPEN SOURCE FOR yOU | www.OpenSourceForU.com

Open GurusLet's Try

device data storage and remote management of devices. Using Etherios Cloud Connector, you can easily develop cloud-based applications for connected devices that quickly scale from dozens, to hundreds or even millions of endpoints.

Prerequisites for Etherios Cloud ConnectorEtherios Cloud Connector can run on any device that has a minimum of 2.5 kB of RAM and 32 kB of Flash memory. A unique feature of the Etherios Cloud Connector is that it is OS independent, which means you don’t need an OS running on your device to connect to Device Cloud by Etherios.

FeaturesBy integrating Etherios Cloud Connector into your device, you instantly enable the power of Device Cloud device management capabilities and application enablement features for your device: � Send data to Device Cloud � Receive data from Device Cloud � Enable remote control of devices via the Device Cloud

platform, including:• Firmware updates• Software downloads• Configuration edits • Access to file systems• Reboot devices

Communicating with your deviceTo manage your device remotely, log in to your Device Cloud account and navigate to the Device Management tab. Alternatively, you can communicate with your device programmatically by using Device Cloud Web Services.

Device Cloud Web Services requests are used to send data from a remote application (written in Java, Python, Ruby, Perl and C#) to Device Cloud, which then communicates with the device. This allows for bi-directional M2M communication.

Source code structureThe Etherios Cloud Connector source code is divided intotwo partitions. � Private partition: The private partition includes the

sources that implement the Etherios Cloud Connector public API.

� Public Application Framework: The Public Application Framework includes a set of sample applications used for demonstration purposes.It also has a HTML help system plus pre-written

platform files for Linux, which facilitate easy integration onto devices running any Linux OS, i.e., even a Linux PC.

You can download Etherios Cloud Connector for free from http://www.etherios. com/products/devicecloud/connector/

embedded. Extract it and you will see the following contents:

connector/docs > API reference manual

connector/private ->The protocol core

connector/public -> Application framework

connector/tools -> Tools for generating configuration files

The threading modelEtherios Cloud Connector can be deployed in a multi-threaded or round robin control loop environment.

In multi-threaded environments that include pre-emptive threading, Etherios Cloud Connector can be implemented as a separate standalone thread by calling connector_run(). This is a blocking call that only returns due to a major system failure.

Alternatively, when threading is unavailable, e.g., in devices without an OS, typically in a round robin control loop or fixed state machine, Etherios Cloud Connector can be implemented using the non-blocking connector_step() call within the round robin control loop.

Etherios Cloud Connector execution guidelinesHere we will try to run Etherios Cloud Connector on a PC running Linux. Similarly, you can port to any device with or without an OS.

Go to /connector/public/step/platformsYou need to create a folder for your custom platform here.

If you have a Linux platform, then go to /connector/public/ step/platforms/linux

Here you can see platform specifics like:

os.c -> OS routines like app_os_malloc(), app_os_free(), app_

os_get_system_time(), app_os_reboot() which defines how to do

malloc and get system time on your platform.

For Linux, these are already defined, so open config.c and go to app_get_mac_addr()

#define MAC_ADDR_LENGTH 6

static uint8_t const device_mac_addr[MAC_ADDR_LENGTH] =

{0x00, 0x00, 0x00, 0x00, 0x00, 0x00};

static connector_callback_status_t app_get_mac_

addr(connector_config_pointer_data_t * const config_mac)

{

#error “Specify device MAC address for LAN connection”

ASSERT(config_mac->bytes_required == MAC_ADDR_LENGTH);

config_mac->data = (uint8_t *)device_mac_addr;

return connector_callback_continue;

}

This callback defines how to get the MAC address of your device, and for testing you may hardcode MAC and rewrite it as follows:

#define MAC_ADDR_LENGTH 6

www.OpenSourceForU.com | OPEN SOURCE FOR yOU | May 2014 | 89

Open Gurus Let's Try

90 | May 2014 | OPEN SOURCE FOR yOU | www.OpenSourceForU.com www.OpenSourceForU.com | OPEN SOURCE FOR yOU | May 2014 | 91

static uint8_t const device_mac_addr[MAC_ADDR_LENGTH] =

{0x00, 0x0C, 0x29, 0x32, 0xDA, 0x9B};

static connector_callback_status_t app_get_mac_

addr(connector_config_pointer_data_t * const config_mac)

{

//#error “Specify device MAC address for LAN connection”

ASSERT(config_mac->bytes_required == MAC_ADDR_LENGTH);

config_mac->data = (uint8_t *)device_mac_addr;

return connector_callback_continue;

}

Now go to /connector/public/step/samples/connect_ to_device_cloud /. Here we will define how to connect to Device Cloud.

To connect, you need to create a free Device Cloud Developer account. Go to http://www.etherios.com/products/devicecloud/ developerzone. You can connect up to five devices with a Developer Edition account. When registering, choose the cloud instance appropriate for you, either Device Cloud US (login.etherios.com) or Device Europe (login.etherios.co.uk). When you log in you’ll see a dashboard (Figure 1) with a single window for managing

all your devices.In Device Cloud, a device is identified using

a Device ID, which is a globally unique 16-octet value identifier, normally generated out of IMEI or MAC addresses.

To access a device from Device Cloud, we need to add the device using MAC/IMEI to Device Cloud. Once added, Device Cloud will generate a Device ID.

You need one more identifier to get Etherios Cloud Connector to connect to Device Cloud, e.g., a VendorID, which can be found in My Account (Figure 3).

Vendor ID won’t be available by default. You need to click Generate/Provision Vendor ID to get a unique Vendor ID for the account.

Now go to /connector/public/step/samples/connect_ to_device_cloud / connector_config.h and make the following changes:

#define ENABLE_COMPILE_TIME_DATA_PASSING

#define ENV_LINUX

#define CONNECTOR_CLOUD_URL login.etherios.com

or

#define CONNECTOR_CLOUD_URL login.etherios.co.uk

#define CONNECTOR_VENDOR_ID 0x04000026

Save and build the application as follows:

athomas@ubuntu:~/connector/public/step/samples/

connect_to_ device_cloud$ make clean all

The above command will create a binary file which can be executed now:

athomas@ubuntu:~/connector/public/step/samples/connect_to_

device_cloud$ ./connector

Start Cloud Connector for Embedded

Cloud Connector v2.2.0.1

dns_resolve_name: ip address = [83.138.155.65]

app_tcp_connect: fd 3

app_network_tcp_open: connected to login.etherios.co.uk

Send MT Version

Receive Mt version

Send keepalive params

Rx keepalive parameter = 60

Tx keepalive parameter = 90

Wait Count parameter = 5

Send protocol version

Receive protocol version

Send identity verification

Sending Device ID = 00 00 00 00 00 00 00 00 00 0C 29 FF FF

32 DA 9B

Figure 1: Device management

Figure 2: Adding devices to Device Cloud

Figure 3: My Account

Open GurusLet's Try

90 | May 2014 | OPEN SOURCE FOR yOU | www.OpenSourceForU.com www.OpenSourceForU.com | OPEN SOURCE FOR yOU | May 2014 | 91

Send Device Cloud url = login.etherios.co.uk

Send vendor id = 0x04000026

Send device type = Linux Cloud Connector Sample

Connection Control: send redirect_report

Connection Control: send connection report

get_ip_address: Looking for current device IP

address: found

[2] entries

get_ip_address: 1: Interface name [lo] IP Address

[127.0.0.1]

get_ip_address: 2: Interface name [eth0] IP

Address

[192.168.5.128]

Send device IP address = C0 A8 05 80

Sending MAC address = 00 0C 29 32 DA 9B

Send complete

connector_tcp_communication_started

tcp_rx_keepalive_process: time to send Rx

keepalive

You can see Etherios Cloud Connector reporting the MAC/VendorID/IP address of the device to the cloud instance.

Now if you check Device Cloud, you can see that the device is connected (Figure 4).

If you right-click on the device, you can see its properties and execute management tasks, such as rebooting the device (Figure 5). If you want to reboot the Linux machine, then re-run Etherios Cloud Connector with root privileges.

#sudo ./connector

Now if you try to reboot from Device Cloud, your Linux PC will be rebooted. We have now successfully connected a Linux PC to Device Cloud.

Next you can add features to Etherios Cloud Connector one at a time, as follows: � Data points: This is used to upload device

statistics periodically, like temperature, CPU speed, etc.

� Device requests: You can send messages to the device from Device Cloud or from an end application.

� File system: The device’s file system will be available in Device Cloud.

� Firmware download: This is for upgrading firmware on the device.

� Remote configuration: This is to configure the device in a remote location via Device Cloud.

� Send data: This is to upload files from the device to Device Cloud; from there your application can download them at any time. Once your device is connected to Device Cloud using

Figure 4: Device connection status

Figure 5: Device properties

Figure 6: API explorer

By: Bob ThomasThe author is an embedded open source enthusiast who works at Digi International, with expertise in Etherios Cloud Connector integration. You can reach him at Bob.thomas@digi.com

Etherios Cloud Connector, you can talk to your device from any application around the world using the Web Services APIs provided in Device Cloud.

Device Cloud allows you to generate source code for the type of execution you want to do, which makes a developer’s job easy.