Embedded Datasheet

Introduction

The Arrayent Connect Agent (ACA) is a software library used in devices that connect to the Arrayent IoT platform. Its functionality can be divided into the following areas:

• Establishing a secure connection with the IoT Platform in the cloud
• Maintaining the connection with the IoT Platform
• Securely sending and receiving attributes to and from the device representation in the cloud

ACA is delivered to customers with documentation and sample application code to accelerate the integration process into the customer’s embedded application.

Establishing a secure connection

In order for ACA to establish a secure connection with the IoT Platform the host application must configure the ACA instance in the device and ask for the connection establishment. The following ACA APIs are used to accomplish this:

• ArrayentConfigure()
• ArrayentInit()

In ArrayentConfigure() the host application provides device credentials and IoT platform information. The ACA attempts to connect to the specified platform, using the specified device credentials. The device credentials are most commonly stored in non-volatile memory. The credentials are issued by Arrayent and written into the device during manufacturing. A single device can connect to the IoT Platform with a set of credentials. The connection will not be successful if these credentials were not provisioned on the IoT platform. The name of the IoT platform is in the form of a URL and therefore requires a DNS for converting it to an IP address. This is done internally by ACA. The host application attempts to connect to the cloud by calling ArrayentInit(). After that the following chain of events occurs:

• the ACA finds the IP address of the IoT platform
• the ACA sends a secure login request
• the IoT platform attempts to authenticate the ACA via the device credentials that the host application gave to the ACA

Before attempting to send or receive any data, the host application must wait until a particular flag in the ACA status is updated that indicates the connection and login have been successful. This flag, called arrayent_net_status_t.connected_to_server is read by the host application by calling ArrayentNetStatus().

Maintaining a connection

Once the device is connected to the IoT platform it must maintain its connection. ACA does this using a heartbeat mechanism. A short message, called a heartbeat, is sent to the IoT platform every 59 seconds to indicate that the device is still on and wishes to maintain its connection. Maintaining a connection is important for end-to-end responsiveness as there is no need to establish a secure connection each time the device wants to update the cloud or vice-versa. It also provides immediate knowledge about the online/offline status of a device. The cloud will consider a device offline if it does not receive a heartbeat for a period of 2 minutes or more. There is no need for the host application to make any API calls to maintain a connection. That said, the host application must be aware of the status of the connection, as lack of connection may result in the inability for the device to send or receive messages from the cloud.

Securely sending and receiving data

ACA securely sends and receive different types of data to and from the cloud. This is done securely with 128-bit AES encryption. The APIs are fully documented in the reference guide. The details below are an overview only.

OTA firmware download support

Over-The-Air downloads of host application firmware images is external to the ACA. The host application developer is responsible for implementing OTA firmware download support for the host application. The recommended implementation is to define a Device Attribute that signifies that a new firmware image is available. When the attribute is sent to the host application, the value of the attribute contains a URL. The host application retrieves the new firmware image from that URL. The host application should then proceed to verify that image is valid and then update its firmware accordingly.

Supported Platforms

ACA is supported on multiple platforms by design and can be rapidly ported to new platforms according to customer demand. The sections below outline the currently supported platforms.