Return to Blog Home

Sensor Location with Helium, GeoJSON, and Timeseries

Over the course of building Helium, we’ve done a lot of investigation around how to structure our APIs and make them useful for developers in the context of the Internet of Things. In thinking through the various use cases of our platform (including hardware) and speaking to customers, it became apparent that tying location data back to sensors comes up often with a certain class of customers. So we made the Helium API extremely flexible such that it can accommodate location data like GPS coordinates. Not only is it built to store data from Helium-powered sensors, but it can ingest and expose virtually any JSON timeseries data. Recently, a customer of ours built an application that made great use of the the Helium API and location data so we wanted to share one aspect of their application design.

The Customer Problem

The customer deploys sensors to brick and mortar retail locations such that one Element Access Point can cover the entire location. (Elements create the wireless network for Helium-powered sensors and handle bi-directional, encrypted communications between these sensors and the Helium Cloud.) The Element in this scenario is at a fixed location and never moves.

Each brick and mortar location has one to 10 sensors reporting data at any given time. And the customer needs to know where, geographically, these sensors are when sending and receiving data. The one complication is that some of the sensors might be on the move. For example, if a container is shipped to a specific retail location, it might arrive with temperature and humidity sensors inside. Conversely, containers can leave a location and end up connecting to a different Element when they are in transit or arrive at new retail location.

The solution is to store each Element’s known location data - specifically GPS coordinates - as part of its metadata. We can then examine the relationship between a given sensor and its connected Element to derive the location of the sensor when transmitting. Ultimately this data and these relationships can then be used quite easily when building applications on top of this data. Let’s walk through a simplified example of this using the Helium API, cURL, some live sensor data, and Helium Commander.

The Helium API and GeoJSON

First, we’ll need to take a look at our Elements that are deployed. We can do this using Helium Commander, the Helium CLI.

$ helium element list

+----------+------------------+---------+-----------------------------+--------------------+
| ID       | MAC              | SENSORS | SEEN                        | NAME               |
+----------+------------------+---------+-----------------------------+--------------------+
| 6e7dd238 | 6081f9fffe000351 | 1       | 2016-11-22T22:18:22.180049Z | Store 1 - Element  |
| 900125df | 6081f9fffe00034b | 0       |                             | Store 17 - Element |
+----------+------------------+---------+-----------------------------+--------------------+

Great. We care about the location of Store 1 - Element so let’s use this one. The next step is to add Store 1's known GPS coordinates to the Element’s metadata. PATCH’ing an Element’s metadata allows users to add arbitrary JSON to it. Storing location data would be just one example of how to make use of the metadata object the API exposes. The uses are endless.

GeoJSON is a JSON-based format for encoding geographic structures. Since the Helium API is made to ingest and expose JSON timeseries data to users, we can use this format storing GPS coordinates. And perhaps the greatest benefit of using GeoJSON is that the format will make it easy to build things like maps on top of this data.

Here’s the GPS data, based on the GeoJSON format, that we’ll be adding to the metadata object:

{
    "data": {
        "attributes" : {
            "coordinates": [
                42.067037,
                -72.676929
            ]
        },
        "id": "6e7dd238-8baa-422c-a44a-577ed93ee514",
        "type": "metadata"
    }
}

Note that we need to include the id of the Element we’re updating. Now let’s write it via cURl and read it back to see the full metadata object of Store 1 - Element.

$ curl -X PATCH -H 'Content-Type: application/json' -d @gps.json \
https://api.helium.com/v1/element/6e7dd238-8baa-422c-a44a-577ed93ee514/metadata \ 
-H "Authorization:HELIUMAPIKEY"
$ curl -X GET https://api.helium.com/v1/element/6e7dd238-8baa-422c-a44a-577ed93ee514/metadata \
-H "Authorization:HELIUMAPIKEY" | python -m json.tool

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   124  100   124    0     0     98      0  0:00:01  0:00:01 --:--:--    98
{
    "data": {
        "attributes": {
            "coordinates": [
                42.067037,
                -72.676929
            ]
        },
        "id": "6e7dd238-8baa-422c-a44a-577ed93ee514",
        "type": "metadata"
    }
}

Excellent. So we can now pull Store-1 Element’s metadata to get its coordinates. Now we automatically know that any sensors connected to this Element can be found at the same latitude and longitude. Let’s take a look at what sensors are connected to it. (Commander is using the GET element/:id/sensor API for this.)

$ helium element sensor 6e7dd238

+----------+------------------+------+-----------------------------+-------------------------+
| ID       | MAC              | TYPE | SEEN                        | NAME                    |
+----------+------------------+------+-----------------------------+-------------------------+
| c26d2010 | 6081f9fffe000781 |      | 2016-11-23T00:36:19.610602Z | Asset-459 Environmental |
+----------+------------------+------+-----------------------------+-------------------------+

So, because we know Asset-459 Environmental is connected to Store 1 Element, we know its location.

What’s Next?

This example showcases a way to use the Helium API to store and access important contextual data about location. Physical sensors form only the beginning of any successful IoT deployment. As more requirements are added to a given application, make sure you’re using a platform that allows for flexibility when storing various flavors of data, that enables you and your developers to build meaningful relationships between data, and that allows you to get that information out to your end application in a seamless manner. We’re working with customers every day to ensure that Helium can grow with them and their use cases. What are you building?

Want to Learn More About Helium? Talk to us!

  • If you’re interested in finding out more about Helium, visit www.helium.com for an overview of our products.

  • Development kits and all necessary hardware to start building connected products can be purchased at store.helium.com.

  • Join our Slack community at chat.helium.com and speak directly to the Helium team as well as other Helium developers.

  • If you’d like to discuss an upcoming project with us, let us know and we’ll get in touch soon.