Production Ready IoT with MongoDB Stitch and Electric Imp: Part 1
It's that time of year again! This post is part of our
Road to AWS re:Invent 2017
blog series.
See all posts here.
Introduction
We’ve been tinkering with hardware a lot at MongoDB lately, and with this has come a lot of trial and error and first hand learnings about how hard building real IoT is.
While sending a message or getting a light to blink is easy, the jump between that and building something production ready can be daunting.
Really, what makes IoT hard is:
Building, testing, and modifying hardware (especially if you’re only used to software)
Establishing and maintaining a secure and scalable connection to the cloud in real-world environments
Standing up a full backend to process, persist, and analyze IoT data
Integrating all the other services you use without writing a lot of boring integration code
Making sure all aspects of the application are robust and secure
Even though MongoDB is the best database for IoT, there’s still a lot more to getting your project off the ground. We’ve found the following to be a killer combination to getting your end-to-end deployment running smoothly:
Electric Imp – Flexible development boards with pre-integrated software, a polished IDE, and managed, secure cloud connectivity.
MongoDB Stitch – A full backend as a service with integrations with your favorite services and built-in JavaScript functions.
MongoDB Atlas – The best database for persisting and analyzing your IoT data.
In the following tutorial we’re going to put all these together:
Use an
impExplorer™ Developer Kit
and the Electric Imp platform to read the temperature and send it to Stitch.
Stitch combines the temperature readings with more general weather data from Dark Sky, stores it in Atlas, and protects your data with field-level access rules.
Stitch also integrates with Twilio so you can retrieve temperature data from the database via text.
Getting Started with your Electric Imp Device
For this tutorial you will need to pick up Electric Imp’s
impExplorer™ Developer Kit
. This is what you will use to read the temperature and send it to our backend. Before you get set up, you’ll need to make an account for Electric Imp’s
IDE
and download the Electric Imp app (on an
iOS
or
Android
phone). Your account is where the device code will live, and you’ll use the app to link your device to your account.
Setting up your imp
To start, unpack your impExplorer. It should include a board, a card (a WiFi IoT module), and a USB power cord. Start by inserting the card into the board and powering it on by attaching the provided cable to your board and then plugging it into a USB port on your computer or a USB wall adaptor. If you are having trouble or want more information, see the
impExplorer guide
.
After you power on your board, use the Electric Imp app to ‘BlinkUp’ your board. This connects it to the internet and assigns it to your account so that you can deploy code to it. If you wait too long to configure your board – you know this when the card’s LED stops flashing – simply restart it and try again.
If you have issues blinking up your impExplorer you can check out
Electric Imp’s troubleshooting guide
.
Deploying the Code
Now that you’ve got your device blinked up, you’ll want to build out your device code quickly. Electric Imp actually breaks down the code into two components:
Device code
reads inputs from the sensors on the impExplorer
Agent code
ensures that the device communicates reliably and securely with the internet.
We’ve provided code that covers both the device and agent code for the impExplorer. You can find them with our other
Github samples
.
Once you have downloaded the code, sign into the Electric Imp
IDE
. From there you’ll need to do the following:
Create a model and link your Device
: After signing in, the impExplorer device should appear under devices as an unassigned device.
Create a model by going to Models and clicking the +.
Assign your device to the new model (and rename your device if you choose).
Create a model and link your Device
: After signing in, the impExplorer device should appear under devices as an unassigned device.
Create a model by going to Models and clicking the +.
Assign your device to the new model (and rename your device if you choose).
If you have any issues with the above process, see the
tour of the Imp IDE
.
Can’t wait for hardware and don’t mind cheating a little bit? We’ve got a
node script
that fakes its place of the demo. But it’s so much more fun with the
actual device
!
Connecting your Device to Stitch
Now you have a device that can measure and send the temperature, but nowhere to send it to. Luckily, with MongoDB Stitch you can quickly setup an entire backend.
Getting Started with Atlas
To start, if you don’t already have a MongoDB Atlas account then you’ll want to register for
an account and create an Atlas cluster
.
Create your Stitch Application
Once you have Atlas up and running, you can create a Stitch app to cover our backend connections and logic. To create an app, you can click on “Stitch Apps” on the left hand nav of the UI and then click “Create New Application” or follow the more in depth instructions on how to
create a MongoDB Stitch app
.
With Stitch, all of your data is protected by default, so you’ll have to do the following to grant your device the ability to write through Stitch:
Create an API Key so the device authenticate to your Stitch application
Put Rules in place such that devices can read/write data properly
Create a function for the device to execute when it wants to write data
Setting up Authentication
To start, we’re going to enable API key authentication in the application. To do this:
First go to the Stitch UI
From there click on ‘Authentication’ in the left hand menu
Find ‘API Keys’ under ‘Providers’ and click ‘Edit’
Enable API Key authentication, and then create an API key (the name doesn’t matter).
Note
: You can only view a key once, so if you lose this key you’ll have to generate a new one.
After you create and copy the key, go back to the Electric Imp IDE and add your App ID (found on the Stitch ‘Getting Started’ or ‘Clients’ page) and you API key to the code as shown below.
Note
: In order to fully roll out this code you will need to ‘Build’ it by clicking the ‘Build’ button at the top of the IDE, and you may need to restart your device as well.
Now your device will be able to make authenticated requests to Stitch. However, you will still need to create rules and a Stitch Function to get everything working properly.
Creating Rules
One important thing to note with Stitch is that even when you’re authenticated, all access to your data and services is off by default. In order to access anything you must use Stitch’s rules to enable access.
Therefore, in order for our function that writes to Stitch to work properly, you will need to set a Write rule for the namespace. In order to do this:
Click on your MongoDB Atlas cluster under ‘Atlas Clusters’ on the left-hand menu.
In the ‘Rules’ tab, click ‘New’ to add a new collection to your rules, and enter ‘Imp’ for the database and the ‘TempData’ for the collection.
Click the created collection to edit the following details:
Click the ‘Filter’ tab and delete the existing ‘Filter’
Select ‘Top-Level Document’ to adjust the rules for the namespace as a whole
Set the write rule to {}
Delete the read rule entirely, leaving an empty box.
By doing this, you enable the device (and only the device) to write data and prevent all reads to the data by devices.
Creating a Stitch Function for Writing
Now that your device has a user and permissions associated with it, it’s time to define the function that it will use to write to the database.
Check out the code in the ‘Imp_Write.js’ file. This contains the JavaScript function that the ImpExplorer is calling in its agent code. With Functions, this code can be hosted and executed by Stitch. To add it to your application:
In the Stitch UI, click ‘Functions’ on the lefthand menu
Click ‘New Function’
In the ‘Settings’ tab, set your Function Name to “Imp_Write” and your ‘Can Evaluate’ rule to {}.
Go to the ‘Function Editor’ tab and paste the code from Imp_Write.js into the editor. Then click the save icon on the upper left-hand corner of the Editor.
Now that you’ve got the basic write functionality set up, let’s look at how Stitch’s built-in services and functions can help broaden the scope of your app.
Building out your Backend
In this section we’ll show you how you can integrate with Dark Sky to use its public weather API to incorporate additional data and with Twilio to search our data via text message.
Additional Weather data with Dark Sky
One of Dark Sky’s many services is providing a public API that serves real-time weather data. Here, you will use this service to pair real-time weather data with our device’s temperature and humidity readings as they are loaded.
If you don’t have a Dark Sky account you can register for one
here
. Once you register, you’ll need to copy down your API key as you will incorporate it into Stitch shortly.
To start, you will set up two values in Stitch. You can hard code things like this in your functions, but using Values is prefered as it makes them accessible for reuse.
In the Stitch UI, go to ‘Values’ found on the left-hand menu
Create two new values, clicking ‘Save’ after each is set up:
DeviceLocation: Enter the longitude/latitude of where your device is located in the form "40.757,-73.987" – example for Times Square in New York City.
DarkSkyKey: Enter the API key that you received from Dark Sky.
Next, create a HTTP service to make the actual Dark Sky request. To do this:
In the Stitch UI, click ‘Services’, then click ‘HTTP’, and name your service ‘darksky’ before creating
After creation, click into the ‘Rules’ tab, and then click ‘New’. The name of this rule does not matter.
To create a rule that enables GET requests, click on the ‘GET’ action and set this rule to {}.
Since the code that you will be using to call the Dark Sky API is already in in the Imp_Write Function, all you need to do now is uncomment the lines that call Dark Sky. They should be the only commented out lines containing code. Now, when your impExplorer loads data Stitch will automatically combine it with data from the Dark Sky API.
Searching your Data with Twilio
Now let’s take a look at serving your data. Since you are using MongoDB Atlas behind the scenes you can always connect to your database and query it directly. However, today we’ll also show you how you can query your database via Twilio + Stitch.
If you don’t have a Twilio account and an SMS-enabled phone number, you can
learn more and create one here
.
Once you have your Twilio account set up, keep your Account SID and Auth Token handy, as you will use them to configure your Twilio service. To do this:
Go to the Stitch UI and click on ‘Services’
Click ‘Twilio’, assign the service the name ‘twilio’, and then add your SID and Token.
Once your Twilio service is configured, set up a rule that enables Stitch to send text messages. To do this:
Click into the ‘Rules’ tab of your Twilio service
Click ‘New Rules’, assign it any name that you like, and then click ‘Add Rule’
Now click into the rule and click the ‘send’ to enable it.
You will also need to store your Twilio phone number as a Value named ‘TwilioPhone’ in Stitch. To do this:
In the Stitch UI, Navigate to ‘Values’ using the left-hand menu.
Click ‘New’ value and add your Twilio number in the form “+15558675309” before clicking ‘Save’.
After that is taken care of you are going to set up an incoming webhook that will parse a text message from Twilio, use it to search the database, and then send a return text message with weather information for a specific time. This code is contained in the twilio_webhook.js file.
To add this code to Stitch:
In the Stitch UI, navigate to your Twilio service
Under the ‘Incoming Webhooks’ tab click ‘+ Add Incoming Webhook’
Under the ‘settings’ tab assign your webhook a name (exact naming is not important) and enable ‘Respond with Result’ by clicking on it
Then, in the Function Editor, paste the code from the twilio_find.js file and click the save icon in the upper left-hand corner.
Before moving on, copy down the ‘Webhook URL’ under the ‘Settings’ tab. You’ll need to add this to Twilio in our final step.
Now that the webhook is set up in Stitch, make sure that Twilio will call it correctly. In order to do this:
Go to your
Twilio Console
and navigate to ‘Phone Numbers’ using the left-hand menu.
Click the number that you are using for this demo, then go to the ‘Messaging’ section at the bottom of the page.
Make sure that ‘Configure With’ is set to ‘Webhooks,...’ and that when ‘A Message Comes In’ is configured to execute your Twilio webhook by selecting ‘Webhook’ and pasting your Webhook URL.
Save any changes before navigating away.
Now Twilio will only be able to access data via the webhook that it is assigned, meaning that it doesn’t change how secure your app is.
Test everything out!
Now that you’ve got everything up and running, try querying your data via Twilio by sending a message to your Twilio number in one of the following formats:
Send “Temp” or “Temp Now” to get the current temperature.
Or search for a specific time by sending “Temp [Time]” where [Time] is in the format “YYYY-MM-DDThh:mm” (ex. “Temp 2017-11-27T11:20”)
Summary
Both MongoDB Stitch and Electric Imp offer you a big leg up when getting your IoT project off the ground. Now that you’ve gone through the basics with Stitch and Electric Imp, you can move onto some of our other projects like building a
real-time dashboard
or build your next great idea.
As always, we’re interested to hear about what you’re building. Please continue the conversation by commenting on this post or send me a note at
drew.dipalma@mongodb.com
to share what you’re working on!
November 28, 2017