GroveStreams SmartThings - Quick Start
This tutorial will walk through the creation of a GroveStreams user account, an organization, and the configuration of a SmartThings Hub and sensor that uploads the open/closed status and temperature to GroveStreams whenever either changes.
The primary purpose of this example is to demonstrate a SmartThings SmartApp that uploads data to GroveStreams.
We used the following items for this example:
1. SmartThings Hub
2. SmartSense Open/Closed Sensor
3. A Router connected to the Internet with a free Ethernet port.
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:
The API Key, that the SmartThings SmartApp will need to send data to the GroveStreams organization, can now be retrieved. The API Key is needed later in the tutorial:
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.
Step 2: Create the GroveStreams SmartApp
What's a SmartApp?
A SmartApp is a script written in Groovy that runs in the SmartThings cloud. The script can be triggered by a SmartThings device and then perform an action such as instructing another device to perform an action (like turning on a light) or (as in our case) calling a web service to pass on information about the event.
A SmartApp is a script written in Groovy that runs in the SmartThings cloud. The script can be triggered by a SmartThings device and then perform an action such as instructing another device to perform an action (like turning on a light) or (as in our case) calling a web service to pass on information about the event.
Your SmartThings hub and devices are packaged with printed instructions on how to configure them so that the device is paired with the hub and the hub can communicate with the SmartThings cloud and the SmartThings mobile app. Please follow these instructions so that the SmartSense Open/Closed sensor status is correctly shown within the SmartThings mobile app. Online instructions on how to setup SmartThings can be found here.
When you setup your SmartThings Hub you will have created an account.
- Login to your SmartThings account here.
- Select the My SmartApps tab and click the New SmartApp button:
- Select the From Code tab so that the large text box is shown:
- Paste the following code into the large text box above and click the Create button:
How to Copy(Can't see the code below? It can also be found here: pastebin.com/1iKLsfpw)
Select all of the code below and copy it to the clipboard (Ctrl-c). Click in the box above and paste the code (Ctrl-v). Remove the first line "Data provided by Pastebin.com - Download Raw - See Original" from the top of the editor.
Or
Click the Download Raw link below, select all of the code and copy it to the clipboard (Ctrl-c). Click in the box above and paste the code (Ctrl-v).
- We will now publish the created app so that you can select it within
the SmartThings mobile app. Click the Save button first, then click the Publish
button and select For Me:
You Should See:
Step 3: Add and Configure the GroveStreams QuickStart SmartApp
Note that the app screen shots below are all for the Windows Phone version of the app. The Android and iPhone versions of the app look a little different but are functionally the same.- Open the email containing the key that you sent to yourself in Step 1 and copy it for pasting later.
- Launch the SmartThings mobile app on your smart phone and tap the Add button in the Dashboard:
- Select My Apps. You should see the GroveStreams QuickStart app listed. If you do
not, then try force closing the app and restarting it.
If this also fails, then try re-saving and publishing the app in the SmartThings web site.
- After selecting the app, you will be taken through some screens to configure it.
Tap Doors open/close and select the device.
Then do the same for Temperatures. Finally, paste the API key you
copied from your email earlier and tap Done.
If you want to change the SmartApp’s configuration you can do so by selecting My Apps in the dashboard and tapping the GroveStreams QuickStart cog:
- Within your GroveStreams organization:
- The notification button will indicate if you have any notifications. Some notifications report errors. Check for any notifications that may contain any upload errors.
- Select the Components folder.
- Click the Refresh button.
- Your new component will appear under the Components folder. Select and double-click a stream.
- The stream's latest measurements will appear within the Quick View panel. The Quick View panel will display No Data if no measurements have been uploaded.
- Stream Viewer. Explore a stream's historical measurements and its latest measurements. Select different cycles to zoom in or out.
Congratulations! You have successfully created a SmartThings SmartApp that uploads measurements into GroveStreams.
Click on the Dashboards tab to create dashboards and maps. Right click on the component and choose Edit Component to set your component's location, add stream units, create events with notifications, and change other properties. Keep exploring and learning!
Continue with the GroveStreams Temperature Example to learn more about how to make the most of your data with GroveStreams.
How it Works
When an attribute of the SmartSense Open/Closed Sensor (i.e. contact or temperature) changed, it sent an event to the SmartThings Hub. The hub relayed the event to the SmartThings cloud which looked for SmartApps with a registered event handler for the device and attribute. On finding the GroveStreams QuickStart app, it ran it while passing the event details to the relevant event handler. The SmartApp’s event handler formatted the data and sent it in the 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 name of the device (in this case Front Door). Component IDs must be unique throughout an organization.
- stream IDs: These are the IDs of the component streams to place the data into. Stream IDs only need to be unique within each component. The device’s attribute name is used, in this case contact and temperature.
- 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 is also optional. The compId is used for the name if compName is not supplied.
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 create their own component templates to avoid having to edit every component after it registers.
Troubleshooting
Watch for errors within the SmartApp Live Logging. Successful API calls to GroveStreams should return a status of: HTTP/1.1 200 OK. An error message should appear within the log 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
- Only changes from the device are sent, so they will not appear in the GroveStreams dashboard until an attribute, such as contact or temperature, has changed.
- Did you correctly copy and paste the API key?
- Have you checked your GroveStreams organization for any notifications?
- Is the SmartApp Live Logging reporting errors?
- Are the devices values being shown correctly within the SmartThings mobile app?
- Is the SmartThings Hub communicating with the internet? (A steady green LED should be lit on the hub).
- Is the first line in your 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.comNext Steps
The script provided in this example only supports contact and temperature attributes. The following script supports many more device attributes, however if you would like to log an attribute that is not included, you should be able to work out the code you would need to add by looking at the general pattern used and using this reference for all attributes. (A SmartThings account is required to view this).Another limitation of the above script is that it does nothing to try to prevent exceeding the GroveStreams one PUT per 10 seconds usage rule. The following script reduces the likelihood of this occurring by setting the “X-Forwarded-For” HTTP header to the id of the sensor device for each call to GroveStreams. This makes the rule apply to each sensor rather than the whole SmartApp.
(Can't see the code below? It can also be found here: pastebin.com/7FLP8Vyu)
Helpful Links
GroveStreams Temperature Example GroveStreams Help CenterGroveStreams Simple Feed PUT API
GroveStreams Forum
SmartThings Forums
SmartThings Help and Support
SmartThings Developer Documentation (requires a SmartThings account)
