Make trash smart again! Or: How to integrate SIGFOX data from a smart waste container to the com2m IoT-Platform

SIGFOX is known for building up and operating a Low Power Wide Area Network (LPWAN), suitable for connecting sensors to the internet. In our previous blog posts we showed how to code firmware for different types of Sigfox transceivers and development boards. Now it’s time to connect the data stream to a nice backend. Enter com2m, a germany-based company, and their IoT Platform. Let’s go!


In two of our recent blogposts we have been looking at SIGFOX and to program embedded devices to send data packets using SIGFOX transceiver hardware:


These posts dealt with the low-level details of getting transceiver modules to connect to the SIGFOX platform. What’s still missing is the further processing of data; SIGFOX as a network operator offers a great backend for routing of data, but not for in-depth analytics or even end user dashboards. So we’re turning to a more read-world, yet prototyping-compatible example.

A lot of IoT ideas revolve around making everyday things and objects smart. That is, having them emit data about themselves. We would like to achieve that for waste containers. These containers typically have a larger capacity and needs emptying in regular intervals. Sometimes however, it might run full earlier, so it would be good to know and for example plan your routes based on that. Sometimes, perhaps its position could change, so we want to know where it’s located.

As usual for IoT projects, we made a prototype for a smart waste container together with our partner com2m. Meet our Smart Waste Container :)

Image 1: TrashFox Prototype with a toy trash container

Image 1: TrashFox Prototype with a toy trash container

This post is about how we built this. But first some words about the abbreviations from above:

LPWAN? Sigfox!

SIGFOX is a french company and the builder and operator of a wireless, cellular LPWAN for the Internet of Things. It can be used to connect small low-power devices to it and have these devices transfer sensor data to a backend. It utilizes radio frequencies within the ISM radio band, which is 868MHz in Europe and 902MHz in the United States. The data that a device can transfer is very limited, at least compared to other protocols that we're used to work with every day. A SigFox device may sent up to 140 uplink messages (meaning from device to backend) per day, which is about one message every 10 minutes. Furthermore, a message may contain up to 12 Bytes. Yes, that is not really much, but enough for a large number of IoT sensor use cases where you'd measure things from the environment (i.e. like soil moisture for agricultural use cases) and transport this small value to your backend application.

If you’re interested in how to shovel small data packets around, you might want to take a look at a com2m blogpost about JSON and byte payloads.

In today’s post, we’re using SIGFOX to transport a single value - the fill level of our waste container. Furthermore, we’re going to see how SIGFOX is able to enrich our own data with GPS coordinates, so we get to know where the waste container is currently located.

But first let’s see how we build the smart container.

“Embedded”

This is the parts list:

The transceiver module from LPWAN ships with an antenna and cabling. Depending on your choice of embedded board, and choosing grove kit or not, you might need additional cabling or base shields. You can see all pieces here:

Image 2: „Cables and wireless“: Sigfox module and sensor connected to an ESP8266

Image 2: „Cables and wireless“: Sigfox module and sensor connected to an ESP8266

The ultrasonic sensor is mounted through the small yellow part on top, so the folding cover wouldn't manipulate anything about the sensor data.

Image 3: ultrasound sensor

Image 3: ultrasound sensor

Image 4: More cabling (backside view)

Image 4: More cabling (backside view)

LPWANs transceiver has a simple UART-Interface and needs 4 pins to connect: 3V, GND, TX (goes to D7) and RX (goes to D8). The ultrasonic sensor needs 5V (!), GND and has 2 digital lines. One needs to be set by the ESP to indicate that we want to measure the distances (“trigger”, connect to D6), one line echoes back in a frequency corresponding to the ultrasound level it measures (connect to D5). This frequency needs to be understood by our firmware.

Firmware

Talking about firmware, we’ve chosen the Arduino Framework for simplicity reasons. The code is available in our github repository: https://github.com/thingforward/trashfox This description of the SIGFOX part within the sketch is similar to what we’ve described in this post https://www.thingforward.io/techblog/2017-11-23-trying-out-sigfox-using-low-cost-maker-hardware.html

$ git clone https://github.com/thingforward/trashfox.git
$ cd trashfox/embedded/

There is a platformio.ini, so if you’re using www.platformio.org it’s very easy to build the firmware:

$ pio run -t upload
$ pio device monitor

Image 5: PlatformIO as the development enviroment

Image 5: PlatformIO as the development enviroment

That is sufficient for the ESP8266. If you’re using a different development board, make sure to edit platformio.ini and put in your board and platform there.

SigFox Network - Data Forwarding

Once our board is powered and firmware is flashed, it starts to measure the fill level and transmit it via SIGFOX once every ten minutes. What happens with our data at SIGFOX? The registration and device claiming process is described here https://www.thingforward.io/techblog/2017-10-18-getting-started-with-sigfox-and-platformio.html So here we’re focusing on configuring the data forwarding part. At https://backend.sigfox.com/ select your device and make sure you receive data from it. Within the left menu, click “CALLBACKS” and see the page of registered callbacks. For our use case we need two of them:

Image 6: SIGFOX device callbacks overview

Image 6: SIGFOX device callbacks overview

The DATA callback will forward fill level data as-is to our data processing engine:

Image 7: SIGFOX callback data configuration

Image 7: SIGFOX callback data configuration

Note the field “custom payload config”: This follows SIGFOX’ syntax of interpreting bytes from the devices. In short, it creates a variable called “val”, which is a 32bit integer in little-endian format. A complete list of data type is available at the help button at the right.

The second callback is a GEOLOCation callback:

Image 8: SIGFOX geolocation callback

Image 8: SIGFOX geolocation callback

It forwards latitude and longitude together with station number and RSSI or our intermediate. You can find the code for this intermediate service in the same github repository from above, it’s a python script under server. This is necessary because com2m’s platform is of course secured with a login mechanism and authorization tokens, which cannot be directly processed by sigfox.

So we’re doing this and routing DATA and GEOLOC callbacks to the com2m platform while bringing them in proper API shape at the same time.

com2m

com2m is a startup from the heart of the Ruhr area and is specialized in providing and implementing IoT cloud solutions. With the lightweight and flexible IoT platform, com2m is a real alternative to some of the big players in the IoT market, especially when it comes to implement individualized IoT solutions and if you have your own ideas on where and how to operate your solution.

To start implementing your own IoT solution, you can use the com2m developer center (developer.com2m.de) where you get access to the documentation, description of basic concepts, getting started and so on. But even more important: you get access to a cloud instance of the platform to start your own development based on the provided interfaces.

Configuring the com2m IoT platform to receive data

The IoT solution we want to build needs to receive data of the TrashFox using Sigfox. Thus, we first have to make sure that the data is forwarded to the com2m platform. To do this, we need to follow these steps:

  • Register as a developer in the com2m Developer Center https://developer.com2m.de
  • Log in to the com2m developer dashboard https://cloud.com2m.de/login
  • Create an new Item
  • Configure the Sigfox Callbacks with the parameters to push the data for the new item
  • Test the data forwarding from Sigfox to the com2m IoT Platform

You will see the pushed data directly on the developer dashboard

To make sure that data points are received, you can use the Data Explorer in the platform UI. Simply add a new chart, enter the device ID and datapoint name and plot a chart, for example to visualize the filling level of the TrashFox.

The following screenshot shows the configured trashfox sensor within the developer dashboard:

Image 9: com2m developer dashboard

Image 9: com2m developer dashboard

Dashboard Magic

Image 10: The TrashFox Dashboard

Image 10: The TrashFox Dashboard at https://cloud.com2m.de/trashfox

After we have assured that the TrashFox data is forwarded and stored in the IoT platform, we can now start to implement our own custom Trash Dashboard.

We use Angular to implement the Dashboard. We won´t explain in detail how to implement an Angular application. There are several very good tutorials out there which do a pretty good job of explaining Angular application programming. The dashboard should show the current capacity and some other Sigfox related data like the signal strength and station. For the UI components we can use an Angular version of the Bootstrap component library.

The com2m IoT platform provides an easy to use REST API. The REST API supports OAuth 2.0 authentication. Nevertheless, we want to provide the dashboard as a public application without a need for login. Therefore we can directly obtain an access token via a public read only user, which is specifically configured for the dashboard application.

By sending the OAuth 2.0 access token as an authentication header the application is now authorized to access the REST API. The platform is based on multiple microservices, where each service serves a dedicated use case. In order to receive the current Sigfox data we use the time series service, which stores the values.

When calling the URL [https://cloud.com2m.de/api/time-series-service/data-points/values/98e45e91-86f6-4f0b-92a1-a68d877f7c59/latest ](https://cloud.com2m.de/api/time-series-service/data-points/values/98e45e91-86f6-4f0b-92a1-a68d877f7c59/latest ) with the appropriate authentication header, we get the latest values of the trashfox sensor. You can easily try it with a tool like Postman, which supports REST requests and OAuth 2.0 authentication. Our Angular Dashboard component can easily display those values with the help of simple HTML template.

As the whole IoT platform is operated as Docker containers, we will finally build a Docker image for the Angular Dashboard and run it on the server. We can use an nginx base image for this purpose. All we have to do is to copy the compiled angular application and nginx configuration into the image:

FROM nginx
RUN rm /etc/nginx/conf.d/*
COPY nginx/webui.conf /etc/nginx/conf.d
COPY dist /var/www
EXPOSE 80

The configuration is defined as followed:

server {
  listen 80;
  server_name localhost;
  root /var/www/;

  location / {
        root /var/www/;
        try_files $uri $uri/ /index.html =404;
        break;
   }
}

The image can be built an executed with:

$ docker build . -t trashfox-dashboard:snapshot
$ docker run rashfox-dashboard:snapshot

The Trashfox dashboard can be found at https://cloud.com2m.de/trashfox, whereas the full source code is provided at the com2m github repository.

Conclusion

You have seen how to implement a full IoT use case including hardware, connectivity, an IoT platform and a specific dashboard. Of course, you would have to implement a more advanced dashboard for a productive application where you would not just monitor one waste container, but maybe several thousands. You could also implement many fancy features using the captured data; like route optimization based on optimization factors like time and budget. Nevertheless, we showed that this use case can easily be prototyped and especially that SigFox is a really interesting technology providing several advantages over classic GSM communication.