Access your data from the cloud with NetBurner and Xively

xively_netburner_logos

NOTE Nov, 2018: Xively is now part of Google Cloud IOT. This post may still be of interest but may have obsolete information or links that no longer work. See Google Cloud IoT for more information. NetBurner will be releasing a new tutorial and integration with google Clout IOT late 2018 into early 2019.

With NetBurner hardware, you already have the power to connect, collect and quantify your data. Now with Xively support, add the power of Xively’s cloud service and API to access your data anywhere and from any device. With Xively, connect to your data with C, Objective-C, Javascript, Python, Ruby and more! With this tutorial, learn how to send and receive data between NetBurner hardware and the Xively platform.

This is part one of a multi-part series of articles in exploration of the Xively platform and the libxively C API. Additional articles will be referenced here when they are posted.

What is Xively

Xively is cloud service solution that allows hardware and software to connect via a cloud access point. Need to create a phone application that speaks to your NANO54415? Use the Objective-C library to design the IOS application, then use the C library to write your hardware application. Adding a web access point? A Javascript library is available to accelerate the process.

Learn more about what is Xively and how it works at the Xively experience site.

Xively Prerequisites

To continue, create a Xively developers account at the Xively Developer signup page. With a developer account, you are granted free access to the Xively API, but are limited to a small number of devices. Read the Xively Develop and Deploy Tutorial and create a new device. Click on the new device to see the device feed page. Examine the API Keys section, and make note of the feed id (9 digit number) and the long Device key that grants read, update, create and delete rights. These will be needed when writing an application that utilizes the Xively API.

While on this page, click on “Add Channel” and call it uptime. This new channel will be used below when the example application broadcasts it’s uptime to Xively.

Install the NB-libxively library

Before an application can use the libxively API, you need to install and configure the NetBurner libxively library. This process involved downloading the library, building it with make, and then including it in any NBEclipse application.

To install the NB-libxively library, first ensure that you have Git installed on your system. This guide will focus on the command line installation, but if you prefer to work within a windows utility, install GitHub for Windows and follow the Github guides on cloning a repository.

  • Open a cmd window by clicking Start->Run… and then typing cmd
  • cd c:nburn to enter the NetBurner folder (default is c:nburn)
  • setenv.bat to set the local environment to build NetBurner products
  • mkdir library to create a new library folder
  • cd library to enter the new library directory
  • git clone https://github.com/NetBurner/nb-libxively
  • cd nb-libxively/src/libxively
  • make to build the library

Once the build is complete, find nb-libxively.a in the c:nburnbin directory. This is the library file that will need to be included in the application.

Include the nb-libxively library in any application

Adding the nb-libxively library to an application is the same process as adding any extra library to an application. First, the nb-libxively.a file is included in the dependency list. Second, the nb-libxively folder is included so that it is possible to add #include statements. Finally, rebuilding the application allows the new dependencies to be found.

  1. Include nb-libxively.a

Right click on the project and select Properties. Under C/C++ Build, select Settings. Change the Configuration to “All configurations”. Under GNU C/C++ Linker, select “Libraries” and add the nb-libxively.a library.

  1. Add the nb-libxively folder

Right click on the project and select Properties. Under C/C++ Build, select Settings. Change the Configuration to “All configurations”. Under GNU C and GNU C++ Compiler, select “Directories” and add “c:nburnlibrarynb-libxivelysrclibxively” folder. If the library was installed in an alternate location, select the alternate location instead.

  1. Rebuild the project

Click Project->Clean… and select the application to be rebuilt. Apply to initiate the rebuild process.

The application is now ready to use the nb-libxively library.

Sending data with Xively

Sending data to the cloud is accomplished with a few API calls. To accelerate this process, an example is included with the nb-libxively library that demonstrates this. Let’s examine this example’s API calls in more detail. Comments have been removed in this article, but can be viewed by examining the copy of this file in the nb-libxively/examples directory.

// #define API_KEY     "longstring"
// #define FEED_ID     123456789

Near the top of main.cpp, there are two define statements that need to be filled in the API key and Feed ID that were created Xively prerequisites section of this article. Uncomment these lines and change the values to the API Key and Feed ID provided by Xively.

extern "C" void UserMain(void * pd) {
    init();
    iprintf("Application startedn");

    OSSimpleTaskCreatewName(updateXively,MAIN_PRIO-1,"Xively");

    while (1) {
        OSTimeDly(TICKS_PER_SECOND);
    }
}

The UserMain section of this example should be fairly self-explanatory. The device is initialized, and a new task is started that will periodically send data to Xively. Beyond that, UserMain is just going to sit idle.

void updateXively(void *) {
    xi_context_t* xi_context = xi_create_context(XI_TCP, API_KEY, FEED_ID);
    while (1) {
        if (xi_context != 0) {
            xi_datapoint_t uptime;
            xi_set_value_i32(&uptime, Secs);
            uptime.timestamp.timestamp = 0;
            xi_datastream_update(xi_context, FEED_ID, "uptime", &uptime);
        }
        OSTimeDly(30*TICKS_PER_SECOND);
    }
    xi_delete_context(xi_context);
}
  1. xi_create_context() is called, which is required before sending data to the cloud server. This is where the API_KEY and FEED_ID are used. A context must be created for every feed that is accessed, either reading or writing. This uses a malloc call, so for ever context that is created, one should be deleted when it is done being used. The xi_delete_context() function will free the space that was malloc’d. This call is placed at the bottom of the task. In this example, it will never be called, as the thread never ends.
  2. This example updates a datapoint, so a datapoint is created, called uptime. The libxively library contains several helper functions, xi_set_value_i32() is one of these functions. It is used to set the unsigned value Secs to the datapoints. Secs is a NetBurner global that is the uptime of the unit, in seconds.
  3. Finally, xi_datastream_update() is called, which sends the datapoint to the server.

Once this application is running, if the device page is viewed at Xively’s developer page will begin updating the uptime channel every 30 seconds.

Okay, that was probably a lot to take in. Take some time and examine the xively.h header file located in the nb-libxively/src folder. This header documents that main public API C functions that are called to access Xively directly through your application.

Stay tuned for part two of the Xively + NetBurner API discussion. In the next installment, we will discuss receiving values from Xively. Then, everything will be put together to create a real world luminosity sensor that can be controlled via the web.

Share this post

Subscribe to our Newsletter

Get monthly updates from our Learn Blog with the latest in IoT and Embedded technology news, trends, tutorial and best practices. Or just opt in for product change notifications.

Leave a Reply
Click to access the login or register cheese