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.

Sending and receiving key-value pairs

ACA provides APIs for sending and receiving key-value pairs to set the values of attributes (keys) in the cloud and in the device. The sending and receiving of these properties can be used in different threads, enabling a host application to get values from the cloud at the same time as it sends valies (in a separate thread). In addition to sending and receiving a single attribute, there are APIs for using a multi-attribute format. This enables the host application to minimize the number of messages it must send and receive, increasing system performance.

Using binary interfaces and cloud parsers

ACA provides a set of APIs that enable the host application to send and receive binary data. In conjunction with Cloud Parsers these APIs can be used to process most of the device logic in the cloud. Cloud Parsers are application-specific.

Getting the time from the cloud

ACA provides an API to obtain the UTC time from the cloud. The application can adjust the time for local time and daylight savings accordingly. Arrayent provides sample code for doing this in the USA (note that different geographies have different daylight savings rules).

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.

Broadcom WICED

The following combination of hardware and software is supported:

  • SDK: WICED SDK 2.4.1Note that WICED SDK 3.x.x is not supported.
  • Hardware: WICED module BCM943362WCD4
  • OS: FreeRTOS
  • Network stack: LwIP
  • Build tools: WICED OpenOCD

Modules: Several companies have built modules using the WICED chipset. These provide FCC certification and peace-of-mind when designing the WiFi connectivity in the embedded device. ACA should work on all of these modules. Some of the companies known to have available modules include:

  • Cybertan
  • Murata
  • MxChip
  • USI
  • LS Research
  • Inventek

Marvell Smart Energy

The following combination of hardware and software is supported:

  • SDK: Marvell WMSDK 2.11.87 or higher
  • Hardware: Marvell 88MC200
  • OS: FreeRTOS
  • Build tools: gcc

Modules: Several companies have built modules using the Marvell chipset. These provide FCC certification and peace-of-mind when designing the Wi-Fi connectivity in the embedded device. ACA should work on all of these modules. Some of the companies known to have available modules include: * Azurewave * Mitsumi

Texas Instruments SimpleLink Wi-Fi CC3200

The following combination of hardware and software is supported:

  • SDK: SimpleLink SDK 1.0
  • Hardware: CC3200-LAUNCHXL
  • OS: TI-RTOS
  • Build tools: IAR

Modules: Texas Instruments offers a module based on the CC3200 that provides FCC certification and peace-of-mind when designing the Wi-Fi connectivity in the embedded device.

RaLink

The following combination of hardware and software is supported:

  • SDK: Ralink SDK
  • Hardware: Ralink RT5350
  • OS: Linux
  • Build tools: gcc

Raspberry Pi

ACA is available on Raspberry Pi (BCM2835), Raspbian Operating system. The Raspberry Pi provides a simple hardware and software option for rapid prototyping and low volume applications.