Skip to content

Home

Jump to bottom
ATT-JBO edited this page Oct 28, 2014 · 62 revisions

Welcome to the gif_arduino wiki!

API

These pages describe the api structure.

  1. [Minimal] (Minimal API)
  2. [regular] (Regular API)

Usage

Some short descriptions on the main functionality of the libraries together with some sample code. Each topic also lists the API versions that are able to perform the described functionality.

Setting up the connection

No matter which version of the API you are using, setting up the connection with the IOT platform always has to be done. It is a little different for each API version, but there is always a common part that is valid for all.

Common

#include <Ethernet.h>					//for the pub/sub client
#include <PubSubClient.h>				//sends data to the IOT platform

EthernetClient ethClient;
void callback(char* topic, byte* payload, unsigned int length);
PubSubClient pubSub(mqttServer, 1883, callback, ethClient);

These statements should be put somewhere at the top of the sketch outside of any functions (they are includes & global decelerations).

The first 2 statements are includes for libraries that the script relies on. The Ethernet library provides basic tcp/ip communication. The PubSubClient library is used to provide 2 way pub-sub communication (mqtt). These includes need to be in your main script, otherwise the libraries are not correctly included in your sketch. Also, the pub-sub client has to be partly initiated in the main sketch (it can't be initiated from within the cloud library) - see further.

Next, the global ethernet object for the pub-sub client is declared. This is used by the mqtt library.

Finally, the mqtt callback is declared and the object is instantiated. The object uses the previously created ethernet object for it's communication. The 'mqttServer' parameter specifies the location of the server. this can be a dns name (char*) or an ip address (byte[]). After the 'mqttServer' parameter, the port is specified. Possible values are:

  • 1883: the default port number for mqtt.
  • 8883: the ssl enabled port number. ssl is not always supported on the arduino.

The callback is also used by the mqtt object. It's a function definition that has to be implemented further down in the code. This function is called every time that a value comes in from the cloud. See receiving data for more info.

for minimal

ATTDevice Device("deviceId", "clientId"); 

void setup()
{
  //set up your pins
  Serial.begin(9600);                // init serial link for debugging
  Device.Subscribe(mac, pubSub);     // setup receiving message from the iot platform (activate mqtt)
}

The first line creates the object that provides the connection to the cloud. It should also be placed somewhere at the top of your sketch, outside of any function (it's a global). The clientId & clientKey parameters (both are char*) can be found on the IOT website. They are assigned to you when you create your account.

[insert picture of website]

In the setup part of your sketch, after specifying the pinmode for your pins and optionally initializing the serial link, the connection with the IOT platform is prepared: the Ethernet library and the pub-sub client are started by calling 'Device.Subscribe'. The 'mac' parameter specifies the mac address of the arduino and the 'pubsub' parameter is the previously declared mqtt object. After calling this function, you are ready to send and receive values. You can't create any devices or assets with the minimal version of the library. These have to be created manually on the website.

for regular

ATTDevice Device("deviceId", "clientId", "clientKey");

void setup()
{
  //set up your pins
  Serial.begin(9600);                   // init serial link for debugging
  
  if(Device.Connect(mac, httpServer))	// connect the device with the IOT platform.
  {
    //create assets here
    Device.Subscribe(pubSub);	       // receive message from the iot platform (activate mqtt)
  }
  else 
    while(true);                                                               
}

As in the previous example, the first line creates the object that provides the connection to the cloud. It should also be placed somewhere at the top of your sketch, outside of any function (it's a global). The deviceId, clientId & clientKey parameters (all are char*) can be found on the IOT website. ClientId & clientKey are assigned to you when you create your account. The deviceId represents your arduino in the IOT platform and is created when you manually create the device in the IOT website.

[insert picture of device-create-website]

In the 'setup' part of your sketch, you initialize the connection with the IOT platform by calling 'Connect'. This expects the mac address of your ethernet card (byte[]) and the name of the HTTP server that it should use. If calling 'Connect' was successful, you can go ahead and create your assets dynamically. When this is done, the call to 'Device.Subscribe' will start the mqtt communication. It expects the pubsub object that you previously created.

Note that the setup will not succeed if the call to 'Device.Connect' failed. We don't want the script to do anything if we don't have a connection with the IOT platform. You could change this behavior if you like. Just make certain that you don't try to send any data to the IOT platform if there was no successful connection.

Creating assets

Available with the API versions:

  1. [regular] (Regular API)

With the regular version of the API, it is possible to dynamically create assets for your device. This procedure does use a fair amount of memory on the arduino, so it limits the number of assets that can be used on 1 device. If this is a problem, it's best to either use the minimal version of the library or switch to another arduino board that provides more resources like the arduino yun, mega or tre. Alternatively, you can also use an RPI and switch to the python library.

String sensorId = "1";			// uniquely identify this asset. Don't use spaces in the id.
String actuatorId = "2";

void setup()
{ 
  if(Device.Connect(mac, httpServer))
  {
    Device.AddAsset(sensorId, F("sensorName"), F("your sensor description"), false, F("int"));   
    Device.AddAsset(actuatorId, F("actuatorName"), F("your actuator description"), true, F("bool"));
    Device.Subscribe(pubSub);
  }
  else 
    while(true);						
}

In this example, we first define 2 global strings that represent the id's of the sensors and actuators that we will use to send and receive values to and from the IOT platform. These are strings and not char* so that we can easily use the actuatorId's later on when we receive values from the IOT platform. See Receving data for more info. The sensorId's are also strings so that we only need 1 function for adding assets to the platform (saves a little memory).

Make certain that you select id's for your assets (sensors and actuators) that are unique within your script. Usually, you start at '1' and increment for each asset.

To make the assets available in the IOT platform, you call 'Device.AddAsset'. This will either create the asset or update it. So every time you call this function, the asset information in the IOT platform will be updated. If you had manually changed the name, description or type information on the website, this will be lost. So it's best to change this information from within your script if you decide to dynamically manage the assets.

Using assets

Send data

Available with the API versions:

  1. [Minimal] (Minimal API)
  2. [regular] (Regular API)
  3. [gateway] (Gateway API)

receive data

Available with the API versions:

  1. [Minimal] (Minimal API)
  2. [regular] (Regular API)
Clone this wiki locally