Simple Device Tutorial

This page will walk you through creating and passing data through your first device using the OpenChirp web portal. In this example, we create a coffee machine that has a temperature sensor, a temperature set point and a pump for water. You will see how to create a sensor with associated MQTT end-point, define transducers, define and execute commands and visualize the output. It is important to remember that everything the web portal is doing is using the REST API that is easily accessible to programs and scripts.

Overview

1. WebPortal Overview
2. PubSub Interface
3. Export Time Series Data from Command line

WebPortal Overview

1. Log into OpenChirp using your Google ID (step 1)
2. Create a Device (steps 2-6)
3. Add Transducers (steps 7-9)
4. Add Commands (steps 10-13)
5. Linking Services (steps 13-15)
6. Execute Commands (step 16)
7. Visualize Stored Data (steps 17-18)
8. Generate a Device Token (step 19)

Detailed Steps

1. Log into OpenChirp using your Google ID

   

2. Click on your user name in the upper right corner

   

3. Click on "My Devices"

   

4. Click on "New Device" to create a new device instance

   

5. Type in a name ("coffee machine") for your device and click "Add Device"

   

6. The OpenChirp Portal create a device with the following MQTT End-Point.

   

7. Click over to the "Transducer" tab to add a sensor to your device. Enter a name ("temperature") and units ("Celsius") followed by the "+" symbol to add the transducer.

   

8. Next add an actuator ("temperature set point") by enabling the actuation tab followed by the "+".

   

9. Add multiple sensors and actuators that define your device.

   

10. Next click on the "Commands" tab to add commands to your device. These are short cuts that can be used to launch common actuations.

    

11. Enter a name ("Hot") for the command along with a value ("86") and actuator followed by the "+"

    

12. Enter a number of other commands as needed. You will want at least two different values for one actuator (name="Cold",value="22") to see the value change for this demonstration.

    

13. Next we need to add a service to store the data. Services can also do things like link your device or gateway to a LoRa Network. Click on the "Service" tab and then the "Link Service" button

    

14. Select the Time Series Database and note that each service shows the permissions needed for your device.

    

15. You will see the service linked like below

    

16. Next, go back to the "Commands" tab and run a few commands. Make sure to wait a few seconds between each click since the events are timestamped at a 1 second granularity by default. Make sure to run at least one actuator across a variety of levels so that you make a visible change that can be view on a graph. When running these commands, you can also see the values getting published over MQTT (described in more detail below).

    

17. Click on the "Visualize" tab and then click and drag around any small part of data. By default the graph loads the last 24 hours of data. You can double click on a graph to zoom out.

    

18. Once zoomed in, you should see a time series of the actuations.

    

19. The "Security" tab has a variety of properties that can be used to control who or what has access to the device. The "Generate Token" tab will create a Device Token that you can use to access this device end-point (only) over MQTT. You can also generate a User Token that can access all of your devices over MQTT.

PubSub Interface

1. Generate Device Token
2. Access MQTT Feed
3. Publish/Subscribe from the command line

For more information on how to do these, please refer to the PubSub Overview page.

Export Time Series Data from Command line

You can use the REST interface to request time series data from transducers. Below is an example for exporting all time series data from a transducer using the command line curl tool:

curl -u ID:TOKEN -H "Content-Type: text/csv" https://api.openchirp.io/apiv1/device/DEVICE_ID/transducer/TRANSDUCER_NAME

where ID is either a user ID (someone@gmail.com), device or service ID and TOKEN is the associated token. User tokens can be generated from the profile page and device tokens from the device's security tab. DEVICE_ID / TRANSDUCER_NAME are the ID/name of the target device and transducer.

Checkout https://github.com/OpenChirp/docs/wiki/time-series-database for more detail.