This tutorial will show you how to quickly get started with a basic "Hello World!" SIB integration with a sensemetrics Thread.

If you would prefer to view video introductions instead, we have published a couple of videos of basic SIB integrations: Demo Video and Demo Video 2 and Demo Video 3

Goals:

• Create a new device integration and add an instance of that device to your Thread
• Publish and execute code (a single log statement) on a sensemetrics Thread and get the response "Hello World!" back in real-time
• Familiarize yourself with the IDE in the browser
• Familiarize yourself with the YAML editor in the browser

Pre-Requisites:

• A sensemetrics Thread that is powered on and actively communicating with the sensemetrics platform

Step 1

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

 

Step 2

Add a sensemetrics Thread to your account using the connect code on the back of the unit.  See the section "Adding a Thread" in the article here for more details.

Before proceeding with the remainder of the tutorial, ensure your sensemetrics Thread is green and actively communicating.

 

Step 3

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

• ID - enter in a unique identifier e.g. "DEVICE_username" where username is your username
• Name - enter in a friendly display name e.g. "My First Device Integration"
• Manufacturer - enter in a fictional company or device manufacturer name e.g "Google"

Skip all remaining fields and click Submit at the bottom.  You will now be taken to a tabular view of all device integrations that you have access to and you should be able to see the integration you just created in the table.

 

Step 4

Click the row in the table that represents the device integration you just created.  You are now in the Modify Device Integration form that allows you to change various details about your device integration.  This is also the place where you can add code to specify how to communicate with your device and obtain observations.

Scroll to the bottom of the form and select the YAML tab in the Code Hooks section.  The YAML text you see in the editor window represents the entire definition of your device integration in a single file.

Place your cursor in the editor at the bottom on the last empty line with no indentation.

Open the templating system menu on the right of the editor by clicking Control Templates to show the canned UI control templates available.  Templating is a quick way to insert YAML snippets that can represent UI controls or even code.

Click the first template button controls-array which initializes an empty array of controls.  You should see that a short YAML snippet is automatically inserted where your cursor is e.g.

controls:

Click the second template button thread-device which inserts two UI controls specific to a device that connects to a sensemetrics Thread and includes the following:

1. connectCodeInput - UI control for representing the connect code of your Thread
2. formSelect - UI control (aka a dropdown) for choosing the physical port a device instance is connected to on the Thread

The final relevant YAML added to the editor after clicking those 2 template buttons should look like this:

controls:
- id: connectCodeInput
  modelPath: props.NODE_ID
  layout: first-column
  requiredForCreation: true
  config:
    label: Thread Connect Code
  restrictions:
    disabled: true
- id: formSelect
  modelPath: props.EXTERNAL_PORT
  layout: first-column
  requiredForCreation: true
  config:
    label: Thread Device Port
    options:
    - label: 1
      value: 1
    - label: 2
      value: 2
  restrictions:
    disabled: true

Click Submit at the bottom to save your changes to your device integration.  A subsequent tutorial will describe what each of these YAML fields means.

*Note: Please include "minThreadVersion: 0.0.0" with no indentation at the end of the YAML, otherwise submission would not be successful. 

 

Step 5

Navigate to Connectivity and locate your Thread that you added in Step 2 in the left pane.

Click the + symbol to add a device instance to your Thread.

Enter in the ID you used in Step 3 to locate your device integration e.g. "DEVICE_username" where username is your username.  

Select the entry that appears in the auto-completion suggestion dropdown that represents your device integration.  You should now see the additional two UI controls that you added in Step 4 representing the Thread connect code and device port.

Select port 1 under the Thread Device Port UI control.

Click Next.  The sensemetrics platform will now attempt to communicate with a physical device plugged into port 1 of your Thread but it will not know how since we have not added any intelligence to this device integration yet.  You will be taken to the main device config form for the device you just added and it will show the default UI controls for your device instance.

 

Step 6

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

Scroll to the Code Hooks section and click the magnifying glass directly to the right of the Test Device text input.  Use this modal to select the device instance you just created in Step 5.  This is the device instance you will be executing your first code hook against.

Scroll to the bottom of the form and select the isDeviceAccessible tab in the Code Hooks section.  This code hook represents the intelligence to determine whether or not a device is communicating or not (i.e. accessible or not).  Put simply, it is asking the question "Is your device accessible?" and it expects the implemented code hook to answer it.  In sensemetrics, a device shows up as green if it is accessible and red if it is not accessible.  Normally, there would be some sort of attempted communication with the device and analysis of the response to determine accessibility.  For the purposes of this tutorial, however, we will simply hardcode this to return the boolean value true, which results in a green icon in the sensemetrics Connectivity tab.

Replace the text "Starting isDeviceAccessible..." with "Hello World!" in the editor and add the line return true.  The resulting JavaScript code should look like this:

function isDeviceAccessible(device) {
  log.info("Hello World!")
  return true 
}

Click the Test button directly below the editor which results in the following:

• Saves the device integration definition to the sensemetrics platform
• Transmits the device integration definition to all Threads with device instances that match this device integration type
• Executes the code in the isDeviceAccessible code hook against the Test Device selected
• Displays the associated code hook log output in the window directly below the Test button

After a few seconds, you should see a window appear that shows the log output with the text "Hello World!" and a current timestamp.

Congratulations, you just wrote your first code hook snippet that was instantaneously transmitted to a Thread and executed directly on a Thread!  You also were able to see the relevant log output of your code streamed back to you in real-time.  Furthermore, because you returned the boolean value true in the isDeviceAccessible code hook, the device instance in the Connectivity tab shows up as green.

 

Exploring Further

You are at a point now where you are actively communicating with a Thread and you can orchestrate it however you wish.  You can try the following explorative activities to get a better feel for the SIB:

• Try changing the text in the log statement and clicking Test to see your changes reflected back to you in the logs that stream back.
• Try returning false instead of true to see the icon for your device turn red instead of green
• Try adding another log statement
• Try printing out the unique instance ID of your device using the argument passed into the code hook and compare that to the device ID that shows up in the main device config form page e.g.

log.info("Device ID is: " + device.id)

• Try bringing up the auto-completion feature of the IDE editor by placing your cursor in the editor and entering on your keyboard option-spacebar
• Try adding more UI controls to the YAML using the templating system and seeing them show up in the main device config form page.

Next Steps

• Continue with the next tutorial (Tutorial: Posting an Observation) that shows how you can add a sensor integration and post a single observation that can be graphed and alerted on.
• View the video here that shows how to integrate an RST Digital Tilt Logger using SIB from scratch
• Review sample device and sensor integrations in our public Github repo here.
• Review the SIB References article which list out the following:
  • SIB Integration API methods
  • SIB REST API
  • Integration YAML fields and their description
  • UI Controls and their fields and description
  • Available Metrics, Units, and Icons
  • Algorithm Integration API Methods