Skip to content

Framework for building Sigfox server on Amazon Web Services

Notifications You must be signed in to change notification settings

UnaBiz/sigfox-aws

Repository files navigation

sigfox-aws is a software framework for building a Sigfox server with Amazon Web Service Lambda Functions and AWS IoT MQTT message queues:

  • Modular: Process Sigfox messages in modular steps using simple Node.js (JavaScript) functions and AWS IoT Rules.

  • Extensible: Allows new Sigfox message processing modules and rules to be added on the fly without disrupting or restarting all modules.

  • Robust: The processing modules are implemented as separate AWS Lambda Functions, so one module crashing will not affect others. AWS IoT MQTT message queues are used to pass the Sigfox messages reliably between processing modules.

Read about the sigfox-gcloud architecture here, which is very similar to sigfox-aws: How To Build Your Sigfox Server

We have aligned the Google Cloud (sigfox-gcloud) and AWS (sigfox-aws) frameworks so that any sigfox-gcloud module will work on sigfox-aws and vice versa. The common code for both frameworks has been refactored into sigfox-iot-cloud

Other sigfox-aws modules available:

  1. sigfox-iot-ubidots: Adapter for integrating Sigfox devices with the easy and friendly Ubidots IoT platform

  2. sigfox-iot-data: Adapter for writing Sigfox messages into SQL databases like MySQL, Postgres, MSSQL, MariaDB and Oracle

Integration with AWS IoT

sigfox-aws is seamlessly integrated with AWS IoT and AWS Lambda Functions. Sigfox devices are represented as AWS IoT Things and can be used with AWS IoT Rules.

AWS IoT Things

The sigfox-aws framework automatically creates an AWS IoT Thing for each Sigfox device ID that it discovers through the received Sigfox messages.

AWS IoT Thing Shadow

The Thing Shadow contains the last received Sigfox message and any decoded values from that message.

AWS IoT MQTT Queues

Messages received from Sigfox are added to the AWS IoT MQTT queue sigfox/received before processing.

After decoding the message, it is delivered to the MQTT queue sigfox/devices/<deviceID>. In the example below, the values tmp, hmd and alt were decoded from the data field in the Sigfox message (by the Lambda Function decodeStructuredMessage).

AWS IoT Rules

AWS IoT Rules may listen to the MQTT queue sigfox/devices/<deviceID> to process decoded Sigfox messages by device ID. To send a notification when the temperature sensor value (tmp) exceeds 30, write a rule like this:

The action for the rule could trigger an AWS SNS Email/SMS notification, or a Lambda Function, etc.

Installing the sigfox-aws server

Instructions for installing the sigfox-aws Lambda Functions and AWS IoT Rules may be found here:

https://github.com/UnaBiz/sigfox-aws/blob/master/sigfoxCallback/index.js

https://github.com/UnaBiz/sigfox-aws/blob/master/routeMessage/index.js

https://github.com/UnaBiz/sigfox-aws/blob/master/decodeStructuredMessage/index.js

https://github.com/UnaBiz/sigfox-aws/blob/master/processIoTLogs/index.js

Installing AWS Lambda dependencies automatically with AutoInstall

sigfox-aws uses a script called AutoInstall that allows you to use require(...) for NPM modules in AWS Lambda Functions, without preinstalling or bundling the dependencies in advance. This is meant to replicate the auto NPM install feature in Google Cloud Functions.

The AWS Lambda Function only needs to call AutoInstall with a list NPM modules to be installed.
Upon starting the AWS Lambda Function, AutoInstall will install the NPM modules into /tmp/node_modules. After installing the modules, AutoInstall launches a copy of the current Lambda Function script, by copying it to /tmp/index.js. The Lambda Function may then use the installed modules.

This is not as fast as preinstalling and bundling the dependencies, but it's easier to maintain and faster to prototype. The first call to the AWS Lambda Function is slower (about 20 seconds for sigfoxCallback) because AutoInstall needs to load the dependencies. But subsequent calls will be faster (generally under 1 second) because the dependencies will be reused from /tmp/node_modules until AWS spawns another instance of the Lambda Function.

The AutoInstall script is located at:

https://github.com/UnaBiz/sigfox-iot-cloud/blob/master/autoinstall.js

Standard AutoInstall template with sample usage:

https://github.com/UnaBiz/sigfox-iot-cloud/blob/master/test/test-autoinstall.js

Monitoring the sigfox-aws server

AWS CloudWatch may be used to view the log messages from the Lambda Functions.

AWS X-Ray is supported for tracing Sigfox messages as they are processed via AWS IoT Rules, MQTT Queues and Lambda Functions.

The X-Ray Service Map visualises the flow of Sigfox messages from/to AWS IoT Rules, MQTT Queues and Lambda Functions:

The X-Ray Trace shows the detailed processing of Sigfox messages by AWS IoT Rules, MQTT Queues and Lambda Functions (to filter by devce ID, select User from the filter box):

Clicking a row in the X-Ray Trace shows the Sigfox message in the Annotations Tab. More details are available in the Metadata Tab.

Creating a Sigfox message processing module

Look at aggregateSensorData for a sample Sigfox message processing module that was created with the sigfox-aws framework. This AWS Lambda Function adds up the last 10 values of the tmp (temperature) sensor and injects a new sensor value named tmpsum

https://github.com/UnaBiz/sigfox-aws/blob/master/aggregateSensorData/index.js

sigfox-iot-ubidots adapter for Ubidots

The sigfox-iot-ubidots adapter is an AWS Lambda Function (developed with the sigfox-aws framework) that integrates with Ubidots to provide a comprehensive IoT platform for Sigfox.

With Ubidots and sigfox-iot-ubidots, you may easily visualise sensor data from your Sigfox devices and monitor for alerts. To perform custom processing of your Sigfox device messages before passing to Ubidots, you may write a Google Cloud Function with the sigfox-aws framework.

sigfox-iot-ubidots also lets you to visualise in real-time the Sigfox Geolocation data from your Sigfox devices, or other kinds of GPS tracking data. For details, check out:

https://www.npmjs.com/package/sigfox-iot-ubidots

https://unabiz.github.io/unashield/ubidots

(Note: sigfox-gcloud-ubidots has been merged and renamed as sigfox-iot-ubidots)

sigfox-iot-data adapter for databases

The sigfox-iot-data adapter is an AWS Lambda Function (developed with the sigfox-aws framework) that writes decoded Sigfox messages into many types of SQL databases including MySQL, Postgres, MSSQL, MariaDB and Oracle. For details, check out:

https://www.npmjs.com/package/sigfox-iot-data

(Note: sigfox-gcloud-data has been merged and renamed as sigfox-iot-data)

Other implementations of AWS IoT integration with Sigfox

Sigfox provides an official connector for AWS IoT:

https://aws.amazon.com/fr/blogs/iot/connect-your-devices-to-aws-iot-using-the-sigfox-network/

The official connector for AWS IoT is suitable for simple integration scenarios with fixed Sigfox message formats. The message will be decoded by Sigfox before executing any AWS IoT Rules.

sigfox-aws allows for complex integration scenarios with multiple message formats per device type. AWS Lambda Functions may be built with the sigfox-aws framework to perform custom processing of Sigfox messages. The sigfox-aws adapters for Ubidots and SQL Databases were built with sigfox-aws.

sigfox-aws also supports AWS X-Ray for easier tracing and troubleshooting of Sigfox message processing.

About

Framework for building Sigfox server on Amazon Web Services

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published