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:
-
sigfox-iot-ubidots: Adapter for integrating Sigfox devices with the easy and friendly Ubidots IoT platform -
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.