Sigfox Texting with SiPy

Introduction

Imagine if you were lost in the middle of nowhere and needed some help? Or more simply, if you had no phone network coverage and needed to send an important message?

Well, Sigfox allows you to send a small message to a contact of your choice by using a third-party texting API. In this tutorial, we will use Twilio.

Here is a quick video presentation:

Below is a diagram showing how the system works:

Let's get started!

1. Hardware Requirements

• A SiPy board (+ an expansion board used for flashing)

• An Android phone with Bluetooth (BLE supported)

2. Installation

Clone the repo:

git clone https://github.com/AntoinedeChassey/SiPy_BLE_texting.git

SiPy

• Activate your SiPy on the Sigfox Backend (you can follow this tutorial)

• Flash the SiPy with the firmware located in this folder: SiPy_BLE_texting/SiPy (you can use the Pymakr Plugin, I strongly recommend to read this guide)

Twilio

• Sign up for free here

• Add new numbers in the "Verified Caller IDs" (phone numbers of the contacts you wish to send messages)

• Take note of your generated Twilio Phone Number, ACCOUNT SID and Auth TOKEN.

EvenNode

• Sign up for free here

• Log in EvenNode and create a Node.js free plan

• Make sure to set the MongoDB password

• Now go in the "Environment vars" section (https://admin.evennode.com/a/d/<YOUR_APP_NAME>/environment-vars) and set the following variables:

SECRET
DB_URI
accountSid
authToken
numberFrom

• Once done, make sure you are in the API folder in order to ONLY push the web app to Evennode and not the whole repository previously cloned:

 cd SiPy_BLE_texting/API

• Follow the Git deployment guide: https://www.evennode.com/docs/git-deployment

• You may have to wait 1 or 2 minutes for the app to start-up

• Check if it runs correctly, you can debug with the "app logs":

https://admin.evennode.com/......./logs

• Create one or two contacts in order to fill the DB (use valid phone numbers, same as the ones you entered on Twilio).

But how does the API work?

Briefly, the Node.js web application has the following endpoints configured (you can have a look in SiPy_BLE_texting\API\app\routes.js).

The two main ones are in red.

/messages/createSigfox is called from the Sigfox Backend in order to store the incoming message from the SiPy and send it by SMS with Twilio.

function processCreateSigfox(req, res) { 
   // validate information 
   req.checkBody('device', 'Device is required.').notEmpty(); 
   req.checkBody('time', 'Time is required.').notEmpty(); 
   req.checkBody('data', 'Data is required.').notEmpty(); 
   // if there are errors, redirect and save errors to flash 
   const errors = req.validationErrors(); 
   if (errors) { 
       return res.send('Data format not respected'); 
   } 
   console.log('Adding in DB: ' + JSON.stringify(req.body)); 
   // create a new message 
   const message = new Message({ 
       device: req.body.device, 
       time: req.body.time * 1000, // Sigfox Backend returns Epoch Time in seconds, we have to * 1000 to convert to millis 
       contactId: parseInt(req.body.data.slice(0, 2), 16), // only keep the fist two bytes 
       content: decodeURIComponent(escape(hexToASCII(req.body.data.slice(2)))) // decode the HEX message (11 bytes) 
   }); 
   // save message 
   message.save(function (err) { 
       if (err) 
           throw err; 
       contactsController.getContactByMessageId(message.contactId, function (err, contact) { 
           if (contact) 
               Twilio.sendTwilio(message, contact.phone, function(err, result) { 
                   if (result === undefined){ 
                       console.log('But could not send message with Twilio, please verify the phone number is correct and verified on <a href="https://www.twilio.com/" target="_blank">Twilio</a>.'); 
                       res.sendStatus(401); 
                   } else { 
                       console.log('Successfully sent message with Twilio!'); 
                       res.sendStatus(201); 
                   } 
               }); 
           else { 
               console.error('Could not send message because contact was not found with ContactId: ' + message.contactId); 
               // redirect to the newly created message 
               res.sendStatus(404); 
           } 
       }); 
   }); 
} 

The above function that checks the body is not empty and decodes the data sent from the SiPy.

• The first byte (unsigned: from 0 to 255, which equals 2^8 - 1) represents the "contactId" (-> we can store 256 different contacts).

• The eleven remaining bytes (chars) represent the "message" content.

The sendTwilio function is detailed below with the use of this package:

sendTwilio: function (newMessage, numberTo, callback) { 
       twilioClient.messages.create({ 
           body: newMessage.content, 
           to: numberTo,    // Text this number 
           from: numberFrom // From a valid Twilio number 
       }, callback); 
   } 
function showContactsAndroid(req, res) { 
   // get all contacts 
   Contact.find({}, function (err, contacts) { 
       if (err) { 
           res.status(404); 
           res.send('Contacts not found!'); 
       } 
       // return JSON data 
       res.send(JSON.stringify(contacts)); 
   }); 
}

We now have to configure the Sigfox Backend callback to tell our message where to go!

/contactsAndroid is called from the Android application to retrieve the contacts stored in the Mongo database (they are then stored in the Android SQLite DB so you can access the contact list without Internet).

Sigfox Backend Callback

• Log in here

• Go to https://backend.sigfox.com/devicetype/list, click left on your device row and select "Edit"

• Now go to the "CALLBACKS" section on the left, select "new" on the top right, select "Custom Callback"

• Url pattern: http://<EvenNode_URL>/messages/createSigfox

• Use HTTP Method: POST

• Content Type: application/json

• Body: { "device" : "{device}", "time" : "{time}", "data" : "{data}" }

• Select "OK" to validate.

Android

• Download the apk file from https://github.com/AntoinedeChassey/SiPy_BLE_texting/raw/master/Android/BLE_to_SiPy.apk (or find it in SiPy_BLE_texting/Android/BLE_to_SiPy.apk).

• Click on it and select "install" (you might have to authorize unsigned apps to be installed on your device).

3. Usage

• Launch the Android app and connect to your SiPy after authorizing Bluetooth.

• Press the + button to select a contact

• At first boot, you need to update the local SQLite database with the contacts you created online (on the EvenNode Node.js app), you will be prompted to do so.

• Enter the name of your Node.js app (the part after http:// and before .evennode.com ).

• Validate, you should now see the same contacts you created online!

• Pick one, enter some text and send!

• Wait 5 seconds and go back to your Node.js app, in the "Messages" section

• You should now see the message you just sent with BLE.

• If your contact recipient has a valid phone number activated on Twilio, he should have received the text message by SMS!

Sorry this project is a bit complicated due to all the different technologies used.

Above all, it is to show what you could do with SIGFOX and BLE, thanks to SiPy!

Have fun!

Antoine de Chassey