Using the Datonis C SDK

Datonis Documentation Home > Build your connected Thing > Using Datonis C SDK

Download SDK Binaries

You can download the Aliot-SDK-Examples zip file from github. Extract the zip file in your local directory and go inside c folder. Folder linux contains a sample.c and sample_bulk_send.c file.

• Configure Datonis Gateway
• Create Thing object
• Register your Thing (Optional Step)
• Sending Data
  • Sending data in bulk
  • Sending data in compressed manner
• Sending Heartbeat
• Sending Alerts
• Instruction Handler (Bi-directional communication)
• Execute sample code

Aliots (ALtizon Internet Of Things) agents are embedded agents sitting at an endpoint that stream data to Datonis. To understand how an Aliot Agent works, we will be walking through the sample agent file in detail. Firstly we require following files to be imported in your sample code.

Import

#include "aliotgateway.h"
#include "aliotutil.h"
#include <stdio.h>
#include <stdlib.h>

Configure Datonis Gateway

You will then need to configure the agent to send data securely to Datonis. The following lines of code achieve this. Since the Aliot agent can act as a gateway for multiple Things, the SDK provides a gateway object that can hold the information about multiple Things.

The initialize function takes access_key, secret_key as parameter. Add the access_key and secret_key obtained by downloading the key-pair in the initialize function.

Try to connect to Datonis, if are unable to connect verify your access_key and secret_key.

Gateway Configuration

initialize("<access_key>", "<secret_key>");
int response = 0;
response = connect_datonis();
if (response != ERR_OK) {
    fprintf(stderr, "Failed to connect to Datonis!\n");
    exit(1);
}

Create Thing object

After the device is able to connect to Datonis, create object of thing struct by adding thing details of the things whose data you want to send. Things detail include thing_key, thing_name and thing_description. If you wish to use MQTT/MQTTS protocol add instruction handler if you require instruction execution support else set last parameter to NULL.

Add Thing Details

struct thing t;
create_thing(&t, "<thing_key>", "<thing_name>", "<thing_description>", execute_instruction);

Register your Thing (Optional Step)

Try to register your Thing, if registration is successfully continue further else verify your thing_key from Datonis portal.

Register your Thing

response = register_thing(&t);
if (response != ERR_OK) {
    fprintf(stderr, "Failed to Register Thing. Response Code: %d, Error: %s\n", response, get_error_code_message(response));
    exit(1);
} else {
    printf("Successfully Registered thing with Datonis!\n");
}

Sending Data

Create a hash like char array of data as metric name and metric value. In our example, metric name is 'temperature' and 'humidity' and its corresponding value. If you want to send waypoint data (data related to location of Thing) create a array like char array named waypoint and insert latitude and longitude information.

transmit_thing_data function basically takes 3 parameters, thing object, data hash and waypoint array. The thing object created previously is a mandatory parameter while you wish to whose what data you want to send and set rest parameters to NULL. Your can choose to send timestamp, default it will send current time.

Sending Data

char data[500];
char waypoint[50];

sprintf(data, "{\"temperature\":%ld,\"humidity\":%ld}", <temperature_value>, <humidity_value>);
sprintf(waypoint, "[%d,%d]", <latitude>, <longitude>);
response = transmit_thing_data(&t, buf, waypoint);

Sending data in bulk

---

Datonis allows you to accumulate data packets and send them in bulk, this can save network bandwidth and reduce number of connections to Datonis. To send data packet in bulk execute build/output/samples/sample_bulk_send_http or build/output/samples/sample_bulk_send_mqtt.

Sending data in compressed manner

---

Datonis also allows you to send data packet in compressed way. The function in the following snippet send compressed data only if packet size is large enough to be compressed.

Sending Compressed Data

response = transmit_compressed_thing_data(&t, buf, waypoint);

Sending Heartbeat

You can also send heartbeat messages to Datonis. These messages does not send any data but assures Datonis that your Thing is still connected.

Sending heartbeat

int response = transmit_thing_heartbeat(t);
if (response != ERR_OK) {
    fprintf(stderr, "Failed to send thing heartbeat. %d, Error: %s\n", response, get_error_code_message(response));
} else {
    printf("Heartbeat Response: %d\n", response);
}

Sending Alerts

Things can also send alerts to Datonis, which is not an event data but data send during abnormal situation such as a thermometer reporting reading that are out of permissible range. The alert function takes thing object, alert level as integer, alert message as string and alert_data as hash like char array. Alert message can be any user defined message which states the cause of alert.

Alert level can only be of four types:

1. Info : value = 0
2. Warning : value= 1
3. Error : value = 2
4. Critical : value = 3

Alert data has to be a hash representing a key and value pair.

Sending Alerts

int response = transmit_thing_alert(t, <alert_level>, <alert_message>, "{\"foo\":\"bar\"}");
if (response != ERR_OK) {
    fprintf(stderr, "Failed to send alert to datonis. Code: %d, Error: %s\n", response, get_error_code_message(response));
} else {
    printf("Successfully sent an alert to datonis with level: %d, message: %s\n", level, msg);
}

Instruction Handler (Bi-directional communication)

When using the MQTT/MQTTS protocols for communication, agents can not only send events to the Datonis platform, but also receive instructions from the platform. These instructions can be interpreted by the agent to perform necessary actions. E.g. Shutting down a machine/device attached to an agent, calibrating a thing based on the errors in its readings etc. The following snippet handles an instruction sent by the Datonis platform and sends back an acknowledgement.

Instruction Handler

void execute_instruction(char * thing_key, char * alert_key, char *instruction) {
    transmit_instruction_feedback(alert_key, 1, "A demo warning to show feedback", "{\"foo\":\"bar\"}");
}

Execute sample code

Once your sample file is ready compile it along with Aliot C SDK along with the help of following make command. This creates 4 executable files sample_http, sample_bulk_send_http, sample_mqtt and sample_bulk_send_mqtt in build/output/samples/ folder. You can choose how to send your data and execute that particular file. E.g. sending data via http protocol.

Compile

make clean install
./build/output/samples/sample_http