In this tutorial, we will show how you can create a sensor and post an observation to it so that it can be used in graphs, data tables, reports, and alerts.

Observations are the fundamental data point that drive the majority of the capabilities of the sensemetrics platform.  See the Concepts article for more information on observations and sensors.

Goals:

• Create a sensor integration that represents a list of metric and unit pairs
• Post an observation for the sensor using the SIB Integrations API in the "poll" code hook

Pre-Requisites:

• This tutorial assumes you have gone thru the Getting Started tutorial and you have a connected Thread with a custom SIB device integration present

Step 1

Login to the sensemetrics web-app at https://workspace.sensemetrics.com

Step 2

Navigate to Integrations --> Sensors and click the button "Add Sensor Integration".  You will be presented with a form.  Fill out the fields as shown below:

• ID - enter in a unique identifier e.g. "SENSOR_username" where username is your username
• Name - enter in a friendly display name e.g. "My First Sensor"
• Metrics - enter in a comma-separated list of metrics e.g. "f,T" for frequency and temperature.  For a full list of available built-in metrics see here
• Units - enter in a comma-separated list of units e.g. "Hz,C" for hertz and celsius which are the SI units associated with the metrics frequency and temperature, respectively.  For a full list of available built-in units see here

A sensor in sensemetrics has an associated set of metric and unit pairs that it collects observations for.  In the above example, our sensor is collecting frequency and temperature (which is actually common for many vibrating-wire type sensors).  Frequency and temperature are collected in SI (the international system of units) units of hertz and Celsius, respectively.

Click Submit to save your sensor integration.  You will now be taken to a tabular view of all sensor integrations that you have access to and you should be able to see the integration you just created in the table.

Step 3

Navigate to Integrations --> Devices and click the row that represents your device integration.  This should be the same device integration you created in the Getting Started tutorial.

Scroll to the Sensors section and check the checkbox for the sensor integration you created in the previous step.  Accept the default mount point of "fixed" which means you have a fixed sensor in the device that is not variable in size or dependent on any property.

Click Submit to save your device integration.

Step 4

Navigate to Integrations --> Devices and click the row that represents your device integration.

Scroll to the bottom of the form and select the poll tab in the Code Hooks section.

Edit the text in the editor to look like the following:

function poll(device) {
  log.info("Starting poll...")
  var sensorId = api.getSensorByIntegrationId("SENSOR_username")
  api.postObservations(sensorId, 100.0, 23.0)
}

Let's walk thru what this 5-line snippet of code is doing line-by-line:

1. line 1 is simply the function signature in JavaScript which states that the function is named "poll" and it's receiving the device object as an argument.  This is the code hook we are adding intelligence for or implementing.  We are telling the sensemetrics platform how to obtain an observation from this device.  The "poll" code hook is called on a schedule based on the desired sampling frequency of the device and can also be triggered immediately by a user thru the sensemetrics UI.
2. line 2 is using the implied log object to print a info-level log statement that signifies that we are entering the function
3. line 3 is using the implied api object and the built-in convenience method getSensorByIntegrationId to get the unique sensor id for the sensor instance associated with this device instance.  The argument passed to this method is the same sensor integration id you used to create the sensor integration in Step 2 of this tutorial.  The result is stored in a variable named sensorId.
4. line 4 uses the implied api object to post an observation with the current timestamp to the given sensor instance represented by the sensorId with a hardcoded value of 100.0 for frequency in hertz and 23.0 for temperature in celsius.  These values correlate with the metrics and units we defined for this sensor in Step 2 of this tutorial.  Normally, these values would be obtained using a byte array or string command that is sent to the device and analyzing the response.  For the purposes of this basic tutorial, however, we will simply hardcode the values here.
5. line 5 is the closing bracket for the function

Click Submit to save your device integration.

Step 5

Navigate to Connectivity and locate your device instance.  You should see a new sensor instance expandable underneath your device instance.  This sensor instance is a representation of the sensor integration you created in Step 2 of this tutorial.

Select the checkbox for your sensor and click the "Trigger sensor immediately" icon to initiate an immediate reading.  Behind the scenes, this will actually call the "poll" function you implemented in the previous step.

If you see a new observation show up for your sensor, then congratulations, you have just posted your first observation using the SIB!  You can now utilize all the normal features of the sensemetrics platform associated with sensors and observations, such as graphing, data tables, alerts, and reports, to name a few.

Exploring Further

You are now at a point where you can post observations for a sensor associated with a device.  You can try the following explorative activities to get a better feel for the SIB:

• Try replacing the hardcoded values of 100.0 and 23.0 with a random value using the scripting language's built-in random methods.
• Try adding another sensor to your device and posting another observation with different metrics and units.
• Try creating an alert for your sensor, triggering a reading that reports an observation that meets the alert criteria threshold, and acknowledging the alert