Exosite -- Standard C Libraries
 All Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Exosite Libraries Index

Table of Contents

Introduction

The Exosite standard C libraries provide a common interface for applications connecting to the Exosite cloud. It is intended to lower the barrier of developing Exosite enabled applications written in C or C++. This would typically be embedded platforms, but there are premade PALs written for Windows and Posix operating systems as well. Once you have created a PAL for your specific platform, you can use Exosite as your cloud platform in as little as two lines of code!

exosite_init("myVendor","myModel");
exosite_write("temperature=82",strlen("temperature=82"));

The Exosite libraries are platform agnostic, but will require the implementation of a platform abstraction layer(PAL). This PAL will be responsible for communicating with the hardware. An example PAL can be found in the exosite_PAL.* files.

You can read the PAL Creation page for more detailed information in developing the PAL,

These libraries assume that the hardware has a modem available to it that can open/close a socket as well as read/write from that socket

Architecture

The Exosite C Library contains the library code, which is hardware independent, as well as a PAL which is required to port the library between different platforms. Below is a high level diagram of how application code, device hardware, library code and Exosite interact.

component_diagram.png

There are two main components to the Exosite C-libs.

  1. exosite-lib
  2. exosite-pal

exosite-lib

exosite-lib consists to the exosite.c and exosite.h files. These files contain the logic used to communicate with the Exosite One Platform. These files should never need any modification from the end user.

exosite-pal

exosite-pal serves as an interface between an individual devices hardware and the exosite-lib code. These files (exosite_pal.c exosite_pal.h )will need modification (PAL Creation page) for creating PALs for different hardware platforms.

Getting Started

The Exosite C Libraries assume that your device has the ability to open a socket and send/receive data on that socket. The library is limited to a single Exosite connection at a time.

In order to use the Exosite libraries on your hardware, you will need to create the PAL. The easiest way to do this is to go through the template exosite_pal.c and fill in the functions. The purpose of each function is well documented and should provide all the information required to write your own hardware specific code.

Use of Non-volatile Memory (NVM)

The PAL will require at least one piece of data to be stored in (NVM). This is the devices CIK. It is given to the device when it provisions itself with the Exosite platform.

Communicating With Exosite

At the beginning of your application code, you must call the exosite_init(). The exosite_init() function initializes some things in local memory and then attempts to activate your device with Exosite. Be sure to check for the return codes and make sure you receive a EXO_STATE_INIT_COMPLETE response. If not, the rest of your calls to Exosite won't be successful.

After exosite_init has successfully completed, you can now read and write to Exosite datasources using the exosite_read() and exosite_write() functions.

Example Exosite Write:

EXOSITE_DEVICE_ACTIVATION_STATE activation_results;
activation_results = exosite_init(vendorStr, modelStr);
if (activation_results == EXO_STATE_INIT_COMPLETE)
{
char * dataToWrite = "greetings=Hello";
exosite_write(dataToWrite, strlen(dataToWrite));
}

Example Exosite Read:

EXOSITE_DEVICE_ACTIVATION_STATE activation_results;
activation_results = exosite_init(vendorStr, modelStr);
if (activation_results == EXO_STATE_INIT_COMPLETE)
{
char readBuffer[BUF_LENGTH];
uint16_t retLen;
exosite_readSingle("myAlias", readBuffer, BUF_LENGTH, retLen);
// If the call is successful, the string within readBuffer will contain
// the latest value of the "myALias" datasource.
}

Error Handling

The exosite library and exosite pal allow errorcodes from every hardware call to bubble up to the application code. However, it is up to the developer to return these calls from the PAL as well as check them in their application.

Misc. Info

Coding Style

Various coding styles are enforced for the Exosite C library. These are enforced by using a tool called uncrustify. The configuration file for uncrustify (uncrustify.cfg) is included with this release.

Testing

Code is checked to compile with GCC 4.7.2 on Debian 7 as well MSVC using Visual Studio 2012.

Unit tests are ran using the Google Test framework.

Diagramming

Diagrams in this documentation are generated with PlantUML