GroveStreams Temperature Tutorial

This tutorial walks through:

1. Modeling a temperature component with a temperature stream and a voltage stream.
   
2. Exploring the temperature stream.
   
3. Creating a dashboard.
   
4. Detecting events and sending notifications.
   

This tutorial follows the GroveStreams Electric Imp Feed PUT example which demonstrates how to upload temperature and voltage readings into GroveStreams. Although this tutorial follows the Electric Imp example, it can be used for any device that uploads data into GroveStreams.

1. Modeling a Temperature Component and Streams

The Electric Imp Example demonstrates how to push data into GroveStreams from an Electric Imp device. That example has data arrive into a default component with default streams. Creating components and streams with default settings will not be acceptable for most use cases. The GroveStreams Feed PUT APIs provide many ways to automatically create and set component and stream attributes the first time data is uploaded. The most common technique is to model a Component Template and then include its ID with every Feed PUT API call. That's the technique we'll use for this example.

A component template can be modeled complete with streams and events and be used to create many components with the same features. A component template's ID can be included as part of a Feed PUT call and when it is, it tells GroveStreams to create a component based on the template if the component does not already exist.

Creating the Temperature Component Template
We will first create a component template with each stream associated with a Rollup Calendar and Units. GroveStreams created some units when the organization was created, but we need to create one more: a Voltage unit.


Log into your GroveStreams account, select your organization, and select the Tools tab on the left.



Create the Volt unit:

1. Select the Units pane, right click within the Units folder and choose New Unit. Fill in the fields with the settings above.
   
2. Click Save.
   

Create the Component Template:

1. Select the Component Templates folder, right click on a folder and choose New - New Component Template. Select General Properties
   
2. Enter a name for the template. It can be any name.
   
3. Enter an ID. The ID will be used as part of the Feed PUT.
   

Create the Temperature Stream:

1. Select Streams, right click and choose Add - Stream - Stream. Select the General Properties
   
2. Enter a name for the stream. It can be any name.
   
3. Enter temperature for the ID. The ID will be used as part of the Feed PUT.
   
4. Select float data type.
   
5. Select the Fahrenheit unit.
   

Create the Voltage Stream:

1. Select Streams, right click and choose Add - Stream - Stream. Select the General Properties
   
2. Enter a name for the stream. It can be any name.
   
3. Enter voltage for the ID. The ID will be used as part of the Feed PUT.
   
4. Select float data type.
   
5. Select the Voltage unit that was created above.
   
6. Click Save to save the new template.
   

Include the Template ID In the Feed PUT

Your organization will already contain a component with default streams if the Electric Imp Example has been run earlier. That component needs to be deleted so that a new component, based on the new template, will be created.

Delete the old component along with all of its stream data:

1. Click the Observation Studio toolbar button.
   
2. Expand the Components folder.
   
3. If an old component exists, right click on it and choose Delete.
   

Modify the Electric Imp (or other device) Feed PUT URL to include the template ID:

1. Open the Electric Imp IDE and un-comment the line that includes the template id.
   
2. Click Build and Run.
   

A new component, based on the template, will be created when the first Feed PUT arrives:

1. A System notification will arrive stating that a new component was created.
   
2. Select the Components folder.
   
3. Click Refresh.
   
4. The new component will be listed. Select it.
   
5. The new component's streams will be listed within Quick View along with their latest values.
   

2. Exploring the Temperature Stream

Explore the temperature stream:

1. Double click the temperature stream to open Stream Viewer and minimize the Quick Viewer located at the bottom.
   
2. Click the Refresh button to view the latest samples.
   
3. View different Rollup Calendar Cycle intervals.
   
4. View a different range of samples.
   
5. Use the page buttons to navigate to the beginning or end of the stream or to page forward or backward in time.
   
6. Click Compare to include other streams within the graph or drag and drop other streams onto the grid.
   
7. Click Save to save any sample value changes. Click the RSS feeds button to subscribe to this stream feed. Click Export to export the stream data as a delimited text file.
   
8. Click the location icon to view the component's location during a sample time.
   
9. Click Chart Type to switch chart types.
   
10. Use the stream navigator to navigate the current selection of samples or drag your mouse within the graph ,while the left mouse button is down, to zoom in.
    

Viewing Rollup Calendar Cycle statistics:

1. Select the Hours cycle. Select the minimum and maximum cycle statistics for the Hours cycle:
   
2. 
   
   1. Click Data Points.
   2. Select Min and Max.
   3. Click OK.
3. Hourly minimum and maximum statistics and when each occurred for each hour are now displayed. Note the start and end time of each hour interval. The start datetime is inclusive. The end datetime is exclusive.
   
4. Hourly minimum and maximums within a graph.
   

Viewing a Rollup Calendar Cycle gap statistics:

1. Select the Hours cycle. Select Gap Intvls for the Hours cycle:
   
2. 
   
   1. Click Data Points.
   2. Select only Gap Intvls.
   3. Click OK.
3. The number of gaps for each hour.
   
4. The number of gaps graphed.
   

3. Creating a Dashboard

Create a new dashboard:

1. Select the Dashboards navigation tab.
   
2. Select the Content folder, right click and choose New - Dashboard.
   
3. Click Add Content.
   
4. Click the Line Chart widget button to add a line chart widget to the new dashboard.
   
5. Click the Table View widget button to add a table view widget to the new dashboard.
   
6. Select the Steel Series tab:
   
7. 
   
   1. Click the Radial Gauge widget button to add a radial gauge widget to the new dashboard.
   2. Click Done to close the widget selection window.

Add streams to the new widgets:

1. Select the Components navigation tab.
   
2. Drag and drop the temperature stream three times onto the line graph widget.
   
3. Drag and drop the temperature stream one time onto the radial gauge widget.
   
4. Drag and drop the temperature stream one time onto the table view widget.
   
5. Drag and drop the voltage stream one time onto the table view widget.
   

Edit the Line Graph widget:

1. Click the line graph widget cog icon and select Settings.
   
2. Enter a Widget Title. It can be any title.
   
3. Enter 20 seconds for the Polling. This is how often the widget will automatically refresh itself. Setting Polling to zero indicates no polling. Widget Polling will add to your GroveStreams monthly transaction costs. A smaller polling value will result in higher transaction costs (whenever a dashboard is left open for long periods).
   
4. Select a 20 Second Data Point Cycle. This configures the graph with vertical time tics representing 20 seconds. 20 seconds matches the stream sample frequency. You may have to create a 20 second Cycle. If so, click the New button within the Cycle selection window. The graph will now display 2,000 seconds of samples since 100 samples, each 20 seconds each, will be displayed (100 * 20 = 2,000 seconds).
   

Three data series, each a stream, were added when the temperature stream was dragged and dropped onto the line graph widget threes times. Next we'll configure two of the series to report the Daily High and Daily Low of the current day along with the current temperature. Edit the line graph data series:

1. Select the Data tab.
   
2. Change each Display Name to the values above.
   
3. Change the Cycle to the values above for rows two and three.
   
4. Change the Statistic to the values above for rows two and three.
   
5. Deselect Connect Gaps for all rows above. Not connecting gaps will allow gaps to be visible within our line graph.
   
6. Click OK to close the line widget configuration window.
   

GroveStreams calculates the daily high and low as data arrives. The daily high and low being graphed will change as they change throughout the day.



Edit the Radial Gauge widget:

1. Click the radial gauge widget cog icon and select Settings.
   
2. Enter a Widget Title. It can be any title.
   
3. Enter 20 seconds for the Polling. This is how often the widget will automatically refresh itself. Setting Polling to zero indicates no polling.
   

1. Select the Data tab.
   
2. Select the Days cycle for Measured Min/Max Cycle. This will cause the daily high and low temperature markers to appear within the radial gauge. These markers will change as the daily high and low change throughout the day.
   
3. Change the Threshold and Title String values. The threshold setting is used to flash a red LED light on the gauge whenever the threshold is exceeded. You may also enable an audio alarm when the threshold is exceeded - just enable the Play Alarm feature.
   
4. Click OK to close the radial gauge configuration window.
   

Congratulations! You have created a new dashboard:

1. Click the Save button to save the changes that have been made.
   
2. Explore other dashboard options and capabilities.
   
3. Widgets can be dragged and dropped to new positions.
   
4. Click OK to close the radial gauge configuration window.
   

4. Detecting Events and Sending Notifications

Both Start and Stop Action Packages listed need to be configured to send notifications to you. Each Action Package contains a set of actions to perform when an event starts or stops. Your organization already contains two pre-configured action packages. Edit each Action Package:

1. Select the Tools tab on the left. Edit each Event Action Package listed by double clicking one at a time.
   
2. Edit each Action listed by double clicking one at a time.
   
3. Click To org. users... and select yourself for the Email.
   
4. Click OK to close the configuration window. Do the same for the User Notification action.
   
5. Click Save to save the changes for the Action Package.
   
6. Navigate back to Observation Studio after all notifications have been configured.
   

Action packages are designed to be reused accross an organization with many components. Each notification message can be custom configured with variables. The notification message is assembled dynamically as an event starts or stops using the variables. See the Message Variables button located at the bottom of each Action editor to see a list of template variables that can be used within each action.


Create a Latency Event that will trigger when data for the temperature stream has not been uploaded for at least 60 seconds:

1. Select the Components navigator tab.
   
2. Right click on the component and select Edit Component.
   
3. Right click on the Events folder and select New - Event - Latency Event.
   
4. Give the event a Name. It can be any name.
   
5. Set Apply to Stream to temperature.
   
6. Set the Start and Stop Trigger Action Packages to the ones above.
   
7. Set the Update Latency to 60 seconds.
   

An email and a GroveStreams notification will be sent whenever the temperature stream is not updated within one minute. Latency events are a good way to monitor the connectivity of your device to GroveStreams.


Create an Value Event that will trigger when a value is less than 40 or greater than 90 degrees:

1. Right click on the Events folder and select New - Event - Value Event.
   
2. Give the event a Name. It can be any name.
   
3. Set Apply to Stream to temperature.
   
4. Set the Start and Stop Trigger Action Packages to the ones above.
   
5. Set the Validation Expression to value < 40 || value > 90.
   
6. Click Save to save the changes to the component.
   

The component events are now active and being monitored by GroveStreams. GroveStreams will check for the latency event every few seconds. The value event will be checked for as stream data arrives.

Trigger the value event: Take the temperature probe and force the temperature to increase to above 90 degrees. This can be done by holding the probe between two fingers.


Viewing Active Events:

1. The event button will list the number of active events (INFO, WARN, CRITICAL). Click the button to view Active Events.
   
2. Event action package user notifications will also appear as events start or stop.
   
3. Events typically end on their own and are automatically removed from the Active Events list. But sometimes events need to be ended manually. Select one or more active events and click Delete to remove an active event manually without triggering the stop action package.
   

1. Double click a component's Event group to bring up the active events for a single component.
   
2. Change several event filters to restrict which events are listed.
   
3. Click the Event Location icon to see where the component was when the event started.
   

Active events will also be displayed within maps and dashboard map widgets:

1. Click the Dashboards navigation tab.
   
2. Double click the World map to open it.
   
3. See the location of your components and any active events. Hover over an event to see its details.
   

As each event ends (i.e. the temperature moves back into its normal range) its Stop Action Package will be executed. The above is a user notification that pops up when the event ended.

Helpful Links

GroveStreams Electric Imp Feed PUT example
GroveStreams Help Center
GroveStreams Simple Feed PUT API
GroveStreams Forum
Electric Imp Forums
Electric Imp Docs