GroveStreams Electric Imp - Thermocouple
This tutorial will walk through the creation of a GroveStreams user account, an organization, and the configuration of an Electric Imp device that uploads temperature and voltage readings into GroveStreams every 20 seconds.
The primary purpose of this example is to demonstrate an Electric Imp Agent that uploads data into GroveStreams. Many of our users, especially businesses, use Electric Imp, but they initially struggled with designing their Electric Imp Agent to upload data into GroveStreams.
Electric Imp makes it easy to configure and manage devices where Wi-Fi is available. Electric Imp provides an SD card that has computational, Wi-Fi, and storage capabilities. Many manufacturers build simple boards that are Electric Imp compatible. I won't list them here - just search for them...
Here are the basic steps for configuring an Electric Imp device to upload samples into GroveStreams (more detailed steps are below):
- Go to Electric Imp
and create a user account.
- Install the Electric Imp Mobile App onto your smart phone
and enter your Electric Imp user name and password. Select your
local Wi-Fi connection and enter the Wi-Fi password.
- Plug your Electric Imp card into a board and power the
board.
- "Blink
Up": Hold the Electric Imp card to your smart phone screen for
several seconds. The Electric Imp SD card has a light sensor in
the end. I'm guessing this transfers your Electric Imp account
identifier, security tokens, and your local Wi-Fi credentials to
the Electric Imp SD card. Your board has successfully connected to
the Electric Imp cloud when the SD card flashes green several
times.
- Go to your Electric Imp account and select your device. You can now enter two sets of code (the programming language is Squirrel). One set of code is the Device code. This code will be uploaded to your device from the Electric Imp cloud. The other set of code is the Agent code. The Agent code runs in the Electric Imp cloud and processes data coming from the device. It's within the Agent code where the GroveStreams logic resides.
At first glance, this seems like a lot of steps to get up and running, but the process is faster after the first Imp.
There's a lot of innovation with Electric Imp, but I believe the best part is the ability to manage all of the device code within their cloud. This concept makes it very easy to update and enhance device code remotely. They also did an excellent job designing a command framework. There are a lot of Electric Imp demos on the web. What we want to do with this example is focus on the Electric Imp Agent code where data is passed into GroveStreams.
Be sure to continue with the GroveStreams Temperature Example after this one to learn more about how to make the most of your Electric Imp data with GroveStreams.
Step 1: Create a Free GroveStreams User Account and Organization
Open a browser and navigate to the GroveStreams registration page and sign up.
Log into GroveStreams after creating your free user account.
You will be prompted to create an organization. Select Yes.
What's an Organization?
An organization is a Workspace, typically representing a home, business, or organization. Each organization has its own set of components, streams, dashboards, maps, and other items. An organization allows you to control user and device access to the organization. You are automatically the "owner" and given full access rights when you create an organization. Other users may invite you to their organizations with rights they give you. All of the organizations, you "own" or are a member of, will appear in your GroveStreams start page (the first page that appears when you sign in).
An organization is a Workspace, typically representing a home, business, or organization. Each organization has its own set of components, streams, dashboards, maps, and other items. An organization allows you to control user and device access to the organization. You are automatically the "owner" and given full access rights when you create an organization. Other users may invite you to their organizations with rights they give you. All of the organizations, you "own" or are a member of, will appear in your GroveStreams start page (the first page that appears when you sign in).
- Enter a name for the new organization. It can be any name.
- Click Create Organization.
- Enter your new organization by clicking on its name.
Step 2: Breadboard the Circuit and Setup Your Electric Imp Account
OK, this is where we're going to refer you to an example that explains everything that you need to buy and what to do for this step: https://learn.adafruit.com/connecting-the-max31855-thermocouple-amplifier-breakout-to-an-electric-impDo everything in the example linked above. We will replace the Electric Imp Device and Agent code in the next steps.
Your circuit should look something like this (with a power supply - we used a USB cable):
Step 3: Modify the Electric Imp Device and Agent Code
1. Start your Electric Imp device.
2. Log into your Electric Imp account.
The code below will be used in the next steps:
How to Copy
Select all of the code below and copy it to the clipboard (Ctrl-c). Paste the code into the Electric Imp Agent (Ctrl-v). Remove the first line "Data provided by Pastebin.com - Download Raw - See Original" from the Agent.
Or
Click the Download Raw link below, select all of the code and copy it to the clipboard (Ctrl-c). Paste the code into the Agent (Ctrl-v).
Select all of the code below and copy it to the clipboard (Ctrl-c). Paste the code into the Electric Imp Agent (Ctrl-v). Remove the first line "Data provided by Pastebin.com - Download Raw - See Original" from the Agent.
Or
Click the Download Raw link below, select all of the code and copy it to the clipboard (Ctrl-c). Paste the code into the Agent (Ctrl-v).
Agent Code:
(Can't see the code below? It can also be found here: pastebin.com/L5WZxFVQ)
Device Code:
(Can't see the code below? It can also be found here: pastebin.com/Hga3Cfen)
Next, you will need to edit the API_KEY variable within the GroveStreams Settings section of the Agent code:
3. Find your GroveStreams Secret API key for your organization:
To find your Secret API Key:
1. Select the Admin - API Keys menu option and choose the Feed Put API Key (with auto-registration rights) key
2. Click View Secret Key
3. Select and copy the API Secret Key to the clipboard (Ctrl-c) when you are ready to paste it below.
1. Select your Electric Imp Active Model and Device
2. Modify the code:
a. Copy and paste the Agent and Device code above
into the Electric Imp IDE (replace any existing code).
b. Replace the API_KEY variable in your Agent with the value you found in step 3 above.
3. Click the Check button to look for syntax errors.b. Replace the API_KEY variable in your Agent with the value you found in step 3 above.
4. Click the Build and Run button.
5. Monitor the device logs pane for any errors. An output similar to what you see above will indicate a successful upload to GroveStreams.
5. Within your GroveStreams organization:
1. The notification button will indicate if you have any notifications. Some notifications report errors. Check for any notifications that may contain any upload errors.
2. Select the Components folder.
3. Click the Refresh button.
4. Your new component will appear under the Components folder.
5. Select a Stream.
6. Your latest measurements will appear within the Quick View panel. The Quick View panel will display No Data if no measurements have been uploaded.
Congratulations! You have successfully created an Electric Imp Agent that uploads measurements into GroveStreams.
Double click a stream to explore or edit historical values. Click on the Dashboards tab to create dashboards and maps. Keep exploring and learning!
Continue with the GroveStreams Temperature Example to learn more about how to make the most of your Electric Imp data with GroveStreams.
How it Works
When the Electric Imp device "Blinked Up", it copied your Electric Imp account identifier, security tokens, and your Wi-Fi settings to the Electric Imp SD card.When you clicked Build and Run within the Electric Imp cloud IDE, it downloaded the Device code to the device. Each time the device wakes up (as directed by the imp.wakeup(20, readChip189); line of device code), it makes calls to the Electric Imp cloud where your Agent code is run. The Agent code passes the data into GroveStreams via an HTTP call to the GroveStreams cloud.
The data sent to GroveStreams, as URL parameters, must include several keys so that GroveStreams knows where to store the data being sent:
- api_key: This is your secret API key and is sent with every request. It tells GroveStreams which organization the data will be inserted into and ensures the caller has the proper rights to make the call.
- compId: This is the ID of a component within your GroveStreams organization that contains the stream that the data will go into. This example uses the Electric Imp's MAC address for the ID. Component IDs must be unique throughout an organization.
- stream IDs (TEMP_STREAM_ID and VOLTAGE_STREAM_ID): These are the IDs of the component streams to place the data into. Stream IDs only need to be unique within each component.
- compTmplId: This is the ID of the component template to use when creating a new component when one does not exist. This is an optional part of the URL. A default component with default streams will be created if it were not included.
- compName: This is the name for the new component.
This example was made simple by allowing GroveStreams to create a default component with default streams. Users can view or modify existing component definitions by right clicking on them and selecting Edit Component. Users can also modify or create their own component templates and organization blueprints.
Troubleshooting
Watch for errors within the Electric Imp Device Logs pane. Successful API calls to GroveStreams should return a status of: HTTP/1.1 200 OK. An error message should appear within the Electric Imp Device Logs pane if the call fails.If the call made it to a GroveStreams server, but an error still occurred, a GroveStreams system notification will be created that contains the error. While in the GroveStreams organization's Observation Studio, click on the Notifications button located in the top toolbar (It looks like an envelope) and select the System tab. Click Refresh to list new notifications.
Any parameter that is part of the URL within the Agent needs to be URL encoded. This should only become an issue if you have given any parameters a value with reserved URL characters (such as spaces or commas). There are many free URL encoders on-line that you can use to encode your URL or URL parameters such as freeformatter.com.
Ensure you are not using the same API Secret Key for different organizations. API Secret Keys are only associated with the organization they have been created within and can only be used for that organization.
Troubleshooting Checklist
- Did you remember to change the Agents API_KEY value?
- Have you checked your GroveStreams organization for any notifications?
- Is the Electric Imp Device Logs pane reporting errors?
- Does your Electric Imp card blink green after you "Blink Up"?
- Does your Electric Imp have power? Ensure the Electric Imp flashes LED lights during startup.
- Is the first line in your Agent or Device code "Data provided by Pastebin.com - Download Raw - See Original"? If so, delete it. It was automatically added by pastebin when you did a Ctrl-c and Ctrl-v while copying the code.
- Still can't figure out what's wrong? Delete your GroveStreams organization, start over, and follow the instructions carefully. Sometimes it's easier and faster to start over than to try and figure out what step was missed or performed incorrectly.
Still having problems or you wish to modify the solution and are not sure what to do?
Post a question on our forum or send us an email and we'll do our best to help you out: support@grovestreams.comHelpful Links
GroveStreams Temperature Example - Continues Electric Imp Example GroveStreams Help CenterGroveStreams Simple Feed PUT API
GroveStreams Forum
Electric Imp Forums
Electric Imp Docs
