Introduction: Sigfox Talking Plant

By t.co/bFLGx5vCGf

What is Sigfox Talking Plant?

It is a simple project based on Sigfox network to make a plant talk on Twitter.
The main goal is to demonstrate how to make an easy IoT prototype using Sigfox network.
You can see a demo at http://sigfox.louismoreau.eu

Which microcontrollers will be used?

In this tutorial, we will be using an Arduino UNO and an ATMEL EVK shield.
Other dev kits are available on Sigfox Partners Network.

How long does it take to make it?

From scratch, it took me 3 days to make the plant talk on Twitter. However, all the source code is available on Github. So, within an hour or two, you will be able to make it work.

Do I need any previous knowledge?

You don't need any previous knowledge although knowing Arduino and Javascript is a plus. The web app will be an AngularJS app and we will be using a NodeJS server.

Is it useful?

Good question! You can use this project to gather a community around the plant or just to remember your followers to water the plant. Feel free to share the way you have been using this project ;)

Who am I?

My name is Louis Moreau, I'm an intern at Sigfox. My mission is to create prototypes and PoC using Sigfox network. I want these projects to be fun and instructive. I want to show you how easy is it to develop the first steps of your ideas. I will try to make this tutorial as complete as I can. Do not hesitate to ask me for more details if needed : Github

In order to make this tutorial, I've been using myself few projects :

Step 1: Understand Sigfox

What is Sigfox?

Sigfox is a connectivity solution dedicated to the Internet of Things.
The operated network is currently operating in +15 countries, on every continent.
Focused on tiny messages (up to 12 bytes) & low energy consumption, it currently powers 7 million devices. Various Sigfox-compatible technical solutions are available, from different silicon vendors. This project uses a Arduino shield from Atmel (see below)

Step 2: Hardware Requirements

In this tutorial, we will be using :

  • an ATMEL EVK shield
  • an ARDUINO UNO
  • a USB cable (type A)
  • a 10 kΩ resistor
  • a photocell resistor
  • a moisture sensor
  • few male-to-male cables
  • a breadboard

What we need is to get the soil moisture, the luminosity and the temperature. The temperature sensor is already provided with the ATMEL shield, thus we only need to add the photocell resistor (to get the luminosity) and the moisture sensor.

Step 3: Hardware Connections

Step 4: Arduino Code Using (ATMEL Shield)

Install Arduino IDE:

You need to install the Arduino IDE : https://www.arduino.cc/en/Main/Software

Choose your OS, download it and install it.

Get the source code:

You can download the source code on Github : https://github.com/luisomoreau/sigfox_talking_plant_atmel

Basic understanding of Arduino programming :

Before starting each program, we start with two "base" functions: void setup() and void loop().

  • void setup() is executed in first. It is used to initialise the card.
  • void loop() is executed infinitely (as long as power is provided)

See more on arduino.cc

Our program:

Open the sigfox_talking_plant_atmel.ino file in Arduino IDE. You will see that both setup() and loop() functions are present. Two other functions are also present, sensorActivity() and sendValues().

Now, we need to define the input, the variables and the sleeping time:

At the beginning of the program, you will see :

  • #define TIMEINTERVALL 3600000; This is the time interval between each sensor values reading. 3600000 corresponds to an hour in milliseconds (60 min x 60 seconds x 1000)
  • #define photores A0; We define the pin A0 to be the input pin to read values from the photocell.
  • #define moisture A1; We define the pin A1 to be the input pin to read values from the moisture sensor.
  • unsigned long timer;
  • unsigned int lum;
  • unsigned int moist;

Let's have a deeper look into the functions:

  • setup():
    In this function, the card is initialised, we check that the shield is present, we activate it and we get the ID and the PAC number from the shield. Then we set it in its sleeping mode and initialize the timer.
  • loop():
    Two options are available to activate the sensorActivity function. You can either press the button or wait for the delay defined with the TIMEINTERVALL value.
  • sensorActivity():
    This function will be used to read the values from the sensors and then call the sendValues function. For the brightness and moisture sensors, they are not integrated with the shield library. Thus we need to use the analogRead function to get the input value.
    I used a map function to convert it in percentage and to calibrate the input.
    For the temperature, we use the library, thus, we need to activate the shield using SIGsh.SIGFOXon() and use SIGsh.readTemp() to get the temperature.
    Finally, we call the sendValues() function with the moisture, luminosity and temperature as parameters.
    In the provided code, the power is also included
  • sendValues():
    At first, we create a buffer to add the obtained values.
    As Sigfox use very small data, we need to optimise it. This is why we only take the lower byte of the integer values.
    Explanation: unsigned int's weight is 16 bits (2 bytes) on Atmega-based boards. Sigfox can send up to 12 bytes. As the values we get will be between 0 and 100, 1 byte is enough to store them.
    See more about integers weights here.
    Then we send the buffer and the length using the provided library (SIGsh.sendMessage)

Run the code:

Try now to compile the code using the check button on the upper-left corner and upload it using the button just next. (Don't forget to add the serial port is it not automatically detected: Tools > Serial Port > your arduino port).

Open the serial monitor and press the button. If everything works fine. You will get the status "OK" on your console.

Next step is to activate your card.

Step 5: Dev Kit Activation

To activate your dev kit, go to https://backend.sigfox.com/activate and choose your provider.

Depending on your location, pick your country and then fill the device's ID, the PAC number and your details.

Both ID and PAC number are written on your dev kit or your box.

Check your emails and log in. Your device will appear in your account. Click on its ID and go to messages to check if you received anything.

Step 6: Back End Using NodeJS

Before setting up the callbacks in the back end Sigfox, we need to set up our own server to receive the data.

In order to do that, we will be using NodeJS. In fact, we will be using LoopBack framework to make this even easier.

What is Loopback?

On their website it is said:

LoopBack is a highly-extensible, open-source Node.js framework.

You can:

  • Quickly create dynamic end-to-end REST APIs.
  • Connect devices and browsers to data and services.
  • Use Android, iOS, and AngularJS SDKs to easily create client apps. Add-on components for push, file management, 3rd-party login, and geolocation.
  • Use StrongLoop Arc to visually edit, deploy, and monitor LoopBack apps.StrongLoop API Gateway acts an intermediary between API consumers (clients) and API providers to externalise, secure, and manage APIs.
  • Runs on-premises or in the cloud

What you should remember is that you can create a REST API in few minutes :)

Source code:

You can download directly the source code on Github

Install Loopback using npm:

$ npm install -g strongloop

Create your app:

$ slc loopback

[?] What's the name of your application? sigfox-talking-plant-backend
create hello-world/ info change the working directory to hello-world I'm all done. Running npm install for you to install the required dependencies. ...

Run the visual interface and create the models:

$ slc arc

Then go to the composer and add a new model "device". Fill the properties as shown in the picture. Repeat this to create the message (and randomTwit models eventually if you wish to customise the twits).

Now, you can run the server by clicking on the "play" button on the upper-right corner.

Note that I changed the port to be 3001 on my computer because my port 3000 is busy.

Go to http://localhost:3000/explorer/ to see your API end points.

You can also run the application from a terminal by typing:

$ node .

Store your data in a database:

If you want to store the data somewhere, you can add a datasource. Loopback framework support MySQL, PostgreSQL, MongoDB and many others. Right now, your data will be loose if you stop the server or restart it.

You even can decide to store the data in a json file. To do so,on the project's root, go to /server/datasource.json and copy this :

{"db": { "name": "db", "connector": "memory", "file": "mydata.json" }}

Create Twitter app:

Go to https://apps.twitter.com/ and create an app.
Go to Keys and Access Tokens to get your credentials.

Sending twits:

Install twitter node module :

$ npm install twitter

Go to /common/models/message.js to configure twits to be sent when a new message is created.

Replace the code by the following :

var Twitter = require('twitter');
module.exports = function(Message) {
//Use the environment variables in production var client = new Twitter({
consumer_key: process.env.TWITTER_CONSUMER_KEY,
consumer_secret: process.env.TWITTER_CONSUMER_SECRET,
access_token_key: process.env.TWITTER_ACCESS_TOKEN_KEY,
access_token_secret: process.env.TWITTER_ACCESS_TOKEN_SECRET, });

//Available methods :
// client.get(path, params, callback);
// client.post(path, params, callback);
// client.stream(path, params, callback);

Message.afterRemote('create', function (ctx, message, next){ console.log('> testing afterRemote function'); console.log('time : '+message.time); console.log('device id : '+message.device); console.log('data : '+message.data);

client.post('statuses/update', {status: "Hello, the temperature is "+message.temp+" °C, the ground moisture is "+message.hum+" % and the brightness is "+message.lum+" %}, function(error, tweet, response){
if(error) console.log(error);
console.log(tweet); // Tweet body.
console.log(response); // Raw response object. });
next(); }); };

You can publish your app on Heroku to test it!

Step 7: Create a Callback in Sigfox Backend

Now that our server is in place, we need to configure to callbacks in Sigfox Backend.

Sigfox offers a callback service: every time a message is received by the network, we set up the way we want it to be forwarded to our application server. URL, content-type, request body, ...

Log in your sigfox backend account and go to "Device Type", then click on card's name.
On the menu at the right, you will be able to see at the bottom "callbacks".
Click on "New" (upper-right corner) and then "Custom callback".

You will see a form with various options, set them as:

  • Type: Data / Uplink
  • Channel: Url
  • Send duplicate: leave uncheck
  • Custom payload config: temp::uint:8 humidity::uint:8 lum::uint:8 voltage::uint:16
  • Url pattern: http://your-url:your-port/api/messages
  • Use HTTP method: POST
  • Send SNI: Leave uncheck
  • Headers: Leave blank
  • Content type: application/json
  • Body:

{

"device" : "{device}",
"data" : "{data}",
"temp" : {customData#temp},
"hum": {customData#humidity},
"lum": {customData#lum},
"voltage": {customData#voltage}
}

To validate, click on OK.

Step 8: Create the Frontend App

Requirements:

  • NodeJS (with NPM)
  • Bower
  • Gulp

Installation:

  • Clone the repository:
    $ git clone https://github.com/luisomoreau/sigfox_projects_angular.git
  • Install the NodeJS dependencies:
    $ npm install.
  • Install the Bower dependencies:
    $ bower install.
  • Run the gulp build task:
    $ gulp build.
  • Run the gulp default task:
    $ gulp.
    This will build any changes made automatically, and also run a live reload server on http://localhost:8888.
    Ensure your preferred web server points towards the dist directory.

Development:

Continue developing the dashboard further by editing the src directory. With the gulp command, any file changes made will automatically be compiled into the specific location within the dist directory.

Modules & Packages:

By default, project includes ui.bootstrap, ui.router and ngCookies.

If you'd like to include any additional modules/packages not included with this project, add them to your bower.json file and then update the src/index.html file, to include them in the minified distribution output.

Configure your own base URL:

Go to /src/js/services/http-service.js and change the base URL

Run the app:

To run the app just run in a terminal:

$ gulp

Step 9: Go Further

Yeah, you made it!!

From now on, the possibilities and endless.
Feel free to modify, adapt, share and let me know what you did with the project.

We haven't discussed about the random tweets options because that might be a bit beyond the scope of this tutorial. The idea I had was to let people add their custom messages using tags to make the tweets more friendly.

Thank you for your attention :)

I will be glad to answer your questions (Twitter or Github)