Home
Who doesn’t love a good cell-connected board? I sure do. And the Particle Electron gives me a whole lot more reason to love it than just having a cellular connection. It looks cool. It’s tiny. It has a TON of pins, including PWMs. It comes with a battery and easy plug-in connector. It has the headers pre-soldered on. It comes with a SIM card. It comes with a data plan.
Need I say more?
In this project, I’ll go over how to setup your Particle Electron, attach a GPS module, and stream GPS data to a web-connected dashboard. For a mere $112 and about an hour, you can have a portable, streaming GPS that’s reliable, rechargeable, and reprogrammable over-the-air.
Project level: Beginner (with soldering skills)
Approximate time to complete: Less than an hour
Practicality: Extreme. A portable streaming GPS is always useful.
In this step-by-step tutorial, you will:
- Setup your Electron and connect it to the Cloud
- Attach and read from the GPS
- Stream data from the Electron to a web service using Webhooks
- Build a map dashboard that you can access from your browser
-
Part 1. Equipment
![particleelectronsupplies]()
Here is a list of all the equipment that we will be using in this tutorial with links to where you can purchase each item. There’s not much! The Particle Electron kit includes everything you need to use it – even pre-soldered headers!
- Particle Electron 3G Kit (https://store.particle.io/?utm_source=homesite&utm_medium=Nav&utm_campaign=TopMenu#electron-3g-americas)
- Adafruit Ultimate GPS Breakout (https://www.adafruit.com/products/746)
- Female-Female Tie Lines (https://www.adafruit.com/products/266)
Part 2. Setting up the Electron
![particlebox]()
If you haven’t already been playing around with the Particle Electron, we’ll cover how to go from unboxing to programming the Electron in this section.
Get excited because the whole experience is pretty cool and pain free.
Part 2. Unboxing your Electron
![particleunboxing]()
The entire Electron unboxing experience was definitely one of the best I’ve ever gone through. From the cool and convenient plastic case to the fact that they include everything that you need to get started, I was excited before I even plugged anything in.
In your kit you’ll find a lithium battery, micro-USB to USB cable, a bag of LEDs and resistors for your first circuit project, and, most importantly, a SIM card in addition to the Electron itself.
The Electron comes stuck into a breadboard with clever piece of paper that tells you how to set up a circuit using a photoresistor and LED by just sticking holes in the paper where it tells you.
An insert in the box directs you to particle.io/start – head on over and we’ll get started with connecting the Electron to the Particle cloud.
Part 2. Connecting to the Particle Cloud
When you get to particle.io/start, you’ll be told to select the device you have. Choose the “Electron” in the middle.
You’ll be taken to the Particle docs, which are very extensive and useful. For the time being though, you just want to find the link that says SETUP MY ELECTRON. Follow that link to a page that will ask you to sign up for a Particle account. You need to do this so that you can associate your device with the Particle cloud and activate your SIM card.
![particlesetup]()
Once you’ve created an account, select “SETUP AN ELECTRON W/SIM CARD” and click next. You’ll see a page that says “Let’s setup your Electron!” Just click next again.
You’ll be prompted to enter your SIM card ICCID. This can be found on both the SIM card and the business card-sized piece of plastic it came attached to.
Now it’s time to actually plug stuff in! Follow the nicely illustrated steps on the next page (you’ll have to remove the Electron from the breadboard to get the SIM card in).
![]()
Note: You need to have the battery plugged in whenever you connect the Electron to your computer via USB to program it. This is also how you charge the battery!
Once you plug the Electron into your laptop via the USB cable, lights will start flashing. Once there is a single “breathing” cyan LED, you’ll know that the board is connected to the Particle cloud!
You should now be taken to the Particle dashboard, where you will be asked to setup a payment method for Particle’s cellular data plan.
This is worth talking about a little because 1. This is one of the cheapest data plans I’ve ever seen and 2. This is designed for tiny IoT devices sending tiny data packets.
First off, let me reiterate “cheap”. I went into AT&T to get a SIM card for another project and not only would they only sell me a 30 GB plan (which is way more data than I could ever use with an IoT device), the 30 GB expired in a month and cost me $60. You read that right. $60 for data that would expire.
Particle’s data plan costs $2.99/month for a base 1 MB. And for each extra MB, it’s only $0.99.
1 MB may not seem like a lot, but when your device is just sending small strings of text 1 MB will get you pretty far. In fact, I only used 0.25 MB for both testing and running this project, and I had the GPS streaming for about an hour!
Getting the Electron would almost be worth it just to get your hands on the Particle SIM card and data plan. I never plan on using a different SIM card for an IoT project ever again.
You can read more about Particle’s data plan here.
Now that we’re all powered on and connected, let’s take a look at programming the Electron.
Part 2. Using the Particle IDE
Particle has its very own web-based IDE called Particle Build. The IDE is useful because you can access a whole host of libraries, compile in the cloud, and (this will be important later) download your code as a “firmware.bin” file. You can read Particle’s docs on Build here.
You can also update your device’s firmware over-the-air once you’ve connected your device to your Particle Build account. For cost reasons, we won’t be doing this with the Electron, but it would be very useful for a WiFi board like the Photon.
Now, go to build.particle.io and create an account. This is separate from your Particle account. If you want to connect your device (which isn’t exactly necessary since we won’t be updating over-the-air, but I still liked doing it just in case), make sure your electron is connected to the cloud (breathing cyan), click on the devices icon, click “Add New Device”, and enter your device number.
![particlebuilddevices]()
Now go back to the code section (the “<>” icon). It’s time to run our first app!
You’ll notice that underneath the part where you can start your own code, there is a list of examples. Select #1 – Blink an LED:
![particleblinkled]()
If you’ve ever messed with Arduino before, this code style will look familiar – hello C. This example will blink an onboard LED on the Electron. It will also blink an LED connected to D0, but we’re not going to mess with that.
Lesson #1 about uploading code to your Electron: DON’T DO IT THROUGH THE CLOUD. While you can do this, it will get expensive fast on the Particle data plan. They’re very good about warning you whenever you might be trying to send a large amount of data.
To get around this, we need to use Particle’s CLI and a Serial USB connection. So plug your board into your computer if you haven’t already, and open your terminal. You can follow Particle’s super detailed instructions here, but I’m going to go over the gist of it.
- Make sure you have node.js installed (you probably do)
- Install the CLI by entering this into the command line:
npm install -g particle-cliparticle login
You should be prompted for your Particle username and password – be sure to use the ones for your dashboard and not for Particle Build!
Alrighty, now go back to the Particle Build window and make sure you hit the big blue “Use This App” button underneath “Blink an LED”.
To flash our Electron over Serial we need to download the firmware.bin file from the Build IDE. To do this, click on the folder icon to save:
![particlebuildsave]()
Where you save the file needs to be somewhere you can navigate to inside of the terminal. I’m lazy and just saved it in my home directory since that’s where my terminal defaults to anywho.
Now to flash over serial!
Your Electron needs to be in listening mode, which can be achieved by holding the MODE button (clearly labelled on the Electron) down for 3 seconds until the LED begins blinking blue, as demonstrated by this beautiful illustration from Particle:
![particlelisteningmode]()
Go to the command line and make sure you’re in the same folder you saved firmware.bin to. Now enter:
particle flash --serial firmware.binYou’ll see a message reminding you to put your device in listening mode. Since it already is, just hit Enter.
If you see the message “Flash success!”, congratulations! You just flashed your Electron! You should notice a new LED on the board is now blinking.
Part 3. Adding the GPS
Now for the fun stuff. This is the part where you’re going to need that GPS breakout board with headers soldered on. Just make sure you’re not soldering like this chick:
(Shutterstock watermark left on because I hope nobody purchases this)
Part 3. Circuit Setup
![]()
Once you’ve got your GPS board all ready to go, we can connect it to the Electron (make sure the Electron is unplugged from both the battery and your computer):
- Using female-female tie lines, connect the GPS’s TX port to the Electron’s RX
- Using female-female tie lines, connect the GPS’s RX port to the Electron’s TX
- Connect the GPS’s VIN port to the Electron’s 3.3V
- Connect the GPS’s GND to the Electron’s GND
Now you can reconnect the battery and reconnect the Electron to your computer. If the power and ground are wired up correctly, you should see a red light on the GPS start blinking.
Part 3. Testing the GPS
With the GPS all hooked up, we can move on to testing it!
This part is super easy – just head on over to the Library section of Particle Build and type “gps” in the search box toward the bottom. Click on the TinyGPS++ library:
![particlebuildlibrary]()
Under the “Files:” section, select the third file, “Fullexample.ino” and then click “Use This Example”. You will be taken to the file (so you can edit it), and it will now be included in your “Apps”.
Before we can run this, we need to change a few lines.
- Comment out (with a //) line 2:
#include <SoftwareSerial.h> - Comment out line 8:
static const int RXPin = 4, TXPin = 3; - Change the baud rate on line 9 from
4800to9600 - Comment out line 15:
SoftwareSerial ss(RXPin, TXPin); - Change line 20 from
ss.begin(GPSBaud);toSerial1.begin(GPSBaud); - Inside of the smartDelay function on line 86, change
while (ss.available())towhile (Serial1.available()) - Change line 87 from
gps.encode(ss.read());togps.encode(Serial1.read());
If you’d rather just copy-paste, you can use editedFullExample.ino.
You will also need a way to read the Serial output of the GPS. You can do this with most IDEs (like the Arduino one). I chose to use Atom, or rather, Particle’s IDE based on Github’s Atom project. Like I said, doesn’t really matter, but if you don’t have a way to monitor serial already, just go ahead and download/install Particle Dev.
Now, go to your edited FullExample.ino and click on the folder icon to save the script, put your Electron in listening mode, and enter this in the command line:
particle flash --serial firmware.binHit enter, wait for the lights on the Electron to stop going crazy, and head over to your serial monitor of choice. The script is set to 115200 baud, so be sure you’re serial monitor is set to that.
You should start see something similar to this printing:
![screen shot 2016-04-28 at 8 57 51 pm]()
If you’re using Adafruit’s GPS module, it actually had a status fix LED. If the red LED is blinking faster than once every 15 seconds, then it doesn’t have a fix yet, and you’ll just see a bunch of asterisks printing.
Once your GPS gets a fix and you see coordinates printing out, you’re ready to move on!
Part 4. Streaming to Initial State
![screen shot 2016-04-27 at 4 24 20 pm]()
Now for the fun part – where we make good use of that SIM card and send our data somewhere we can access from anywhere.
We are going to use Particle’s webhooks to send data to Initial State. Then we’ll set that data up on a pretty, real-time map!
Part 4. Initial State
We want to stream all of our GPS data to a cloud service and have that service turn our data into a nice dashboard that we can access from our laptop or mobile device. Our data needs a destination. We will use Initial State as that destination.
Step 1: Register for Initial State Account
Go to https://app.initialstate.com/#/register/ and create a new account.
Step 2: Install the ISStreamer
Install the Initial State Python module onto your Pi:
At a command prompt (don’t forget to SSH into your Pi first), run the following command:
$ cd /home/pi/ $ \curl -sSL https://get.initialstate.com/python -o - | sudo bashSecurity Note: The above command has some important anatomy that the user should be aware of. 1) There is a preceding
\beforecurl. This is important to ensure no alias ofcurlgets run if one was created. This helps mitigate risk of the command doing more than intended. 2) The command is a piped command, so when running, you are piping the output of a script that is being retrieved fromhttps://get.initialstate.com/pythoninto the commandsudo bash. This is done to simplify installation, however, it should be noted thathttpsis important here for helping ensure no man-in-the-middle manipulation of the install script, especially since the script is being run with elevated privileges. This is a common way to simplify install and setup, but if you are a little more weary there are some slightly less convenient alternatives: you can break the command out into two steps and investigate the bash script being downloaded from the curl command yourself to insure it’s fidelity OR you can follow the pip instructions, you just wont get an automatically generated example script.Step 3: Make some Automagic
After Step 2 you will see something similar to the following output to the screen:
pi@raspberrypi ~ $ \curl -sSL https://get.initialstate.com/python -o - | sudo bash Password: Beginning ISStreamer Python Easy Installation! This may take a couple minutes to install, grab some coffee :) But don't forget to come back, I'll have questions later! Found easy_install: setuptools 1.1.6 Found pip: pip 1.5.6 from /Library/Python/2.7/site-packages/pip-1.5.6- py2.7.egg (python 2.7) pip major version: 1 pip minor version: 5 ISStreamer found, updating... Requirement already up-to-date: ISStreamer in /Library/Python/2.7/site-packages Cleaning up... Do you want automagically get an example script? [y/N](the output may be different and take longer if you have never installed the Initial State Python streaming module before)
When prompted to automatically get an example script, type y. This will create a test script that we can run to ensure that we can stream data to Initial State from our Pi. You will be prompted:
Where do you want to save the example? [default: ./is_example.py]:You can either type a custom local path or hit enter to accept the default.
You will be prompted for your username and password that you just created when you registered your Initial State account. Enter both and the installation will complete.
Step 4: Access Keys
Let’s take a look at the example script that was created.
$ nano is_example.pyOn line 15, you will see a line that starts with
streamer = Streamer(bucket_ .... This lines creates a new data bucket named “Python Stream Example” and is associated with your account. This association happens because of theaccess_key=”...”parameter on that same line. That long series of letters and numbers is your Initial State account access key. If you go to your Initial State account in your web browser, click on your username in the top right, then go to “my account”, you will find that same access key at the bottom of the page under “Streaming Access Keys”.![Access Keys]()
Every time you create a data stream, that access key will direct that data stream to your account (so don’t share your key with anyone).
Step 5: Run the Example
Run the test script to make sure we can create a data stream to your Initial State account. Run the following:
$ python is_example.pyStep 6: Profit
Go back to your Initial State account in your web browser. A new data bucket called “Python Stream Example” should have shown up on the left in your log shelf (you may have to refresh the page). Click on this bucket and then click on the Waves icon to view the test data.
![Example Stream Screenshot]()
You will want to step through the Waves tutorial to familiarize yourself with how to use this data visualization tool. Next, view the data in Tiles to see this same data in dashboard form.
![Example Stream Screenshot]()
You are now ready to start streaming real data from your Particle Electron!
Part 4. Using Particles Webhooks
Now for an easy way to tell the Electron where to send our data. Back in the day, you had to use Particle’s CLI to create webhooks, too, but now they’ve built it into their Dashboard!
Go to your Particle Dashboard and navigate to the Integrations section.
![screen shot 2016-04-19 at 11 29 02 am]()
Select “New Integration” and then “Webhook”.
![screen shot 2016-04-19 at 11 29 19 am]()
Now we need to actually build the webhook. The Event Name is what you call inside of your script to use the webhook – I set mine to “sendgps”. The URL is what address we want our request to go to. To send to Initial State, it needs to be “https://groker.initialstate.com/api/events“. Select “POST” from the Request Type dropdown, and whatever you decided to call your Electron from the Devicedropdown.
Click on “Advanced Settings” to reveal more settings.
![screen shot 2016-04-19 at 11 30 24 am]()
Move down to the next section and leave “None” checked underneath Send Custom Data. This is the part where we structure our data to match the format accepted by the Initial State API. Create a parameter called “key” and set it equal to whatever you want your GPS data to be called (this will be the signal name within Initial State). Since I’m only streaming longitude + latitude, I set it to “Coordinates”. Create a second parameter called “value” and set it equal to “{{SPARK_EVENT_VALUE}}”. This will pass whatever value is in our webhook call inside of the script to the JSON that the webhook creates.
![screen shot 2016-04-19 at 11 31 26 am]()
Skip HTTP Basic Auth and go to HTTP Headers. Create the first one as “Content-Type” equal to “application/json”. The second one is “X-IS-AccessKey” equal to your Initial State access key foundhere. Third is “X-IS-BucketKey”. This value determines your Bucket Key, which is the hidden reference for this specific data set. I set mine equal to “electronstream”. Finally, create “Accept-Version” equal to “0.0.2”.
![screen shot 2016-04-19 at 11 32 58 am]()
Scroll down to the very bottom and make sure that under Include Default Data “No” is checked and under Enforce SSL “Yes” is checked. Create the webhook!
![screen shot 2016-04-19 at 11 33 15 am]()
You should see a success message and your new webhook!
![screen shot 2016-05-01 at 10 40 03 pm]()
If you click on it, it should look like this:
![screen shot 2016-04-19 at 11 34 15 am]()
Now let’s give it a try!
Part 4. The Code
Grab the sketch called electrongps.ino from the repo.
This sketch is just adapted from the FullExample inside of the TinyGPS++ library. Webhook calling happens on Line 93 after doing some formatting of the latitude and longitude.
You shouldn’t need to edit anything in this script unless you want to change the one minute between readings (line 96) or you named your webhook something different than “sendgps” (line 93).
Save as firmware.bin, put your Electron in listening mode, and run
particle flash --serial firmware.binin the terminal.Note: The TinyGPS library does something weird when there isn’t valid location data that makes it very difficult to keep it from reporting the coordinates 0.00000,0.00000. Because those coordinates are valid, they mess up the first point on the map in the dashboard. This can be filtered out using the timeline, but if anyone figures out how to keep it from streaming altogether, let me know!
Part 4. Your Personal Dashboard
Head over to Initial State. In order to expose the events that we’ve sent, we need to create a bucket that is associated with the Bucket Key we used for our webhook.
Click on the +cloud icon at the top of the Bucket Shelf on the left. Name your bucket whatever you’d like to see it as and check the “Configure Endpoint Keys” box to reveal the Bucket Key option. Change the randomly generated Bucket Key to the same one you used in the webhook (“electronstream” if you copied me). Then click the Create button at the bottom of the shelf.
![triggersetup1]()
You should see your streaming Particle events start popping up! The tile should automatically know that it’s location data and default to a map!
Here is a dashboard showing my trips to work and the dentist on the same map:
![screen shot 2016-04-27 at 4 24 20 pm]()
You can read more about how to configure, resize, rename, move, plot multiple signals, and morehere.
Wasn’t that easy? And the Electron has a battery and everything! I didn’t even use a quarter of my 1 MB streaming these two trips (which was about an hour of travel time).
