The Octave Developer Hub

Welcome to the Octave developer hub. You'll find comprehensive guides and documentation to help you start working with Octave as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Pushing Data from Octave to IoT Central

This topic describes how to integrate Octave with Microsoft Azure IoT Central to report Sensor data to your IoT Central application or control your asset from IoT Central.

Setting Up IoT Central and Device Bridge

  1. Create your IoT Central instance in the Azure Portal.

  2. Deploy the "device bridge" from the Azure portal, to enable connections from Octave:

Install "device bridge", enable it, and retrieve the function URL as indicated in the dedicated tutorial provided here.

📘

Note:

The IoT Central application mentioned in step 2 above, is the IoT central web application, which differs from the management of your IoT Central service in the Azure portal.

To retrieve the URL to that application, navigate to your IoT Central service instance in Azure portal > Overview > IoT Central application URL.

The function URL you retrieve will look like https://iotc-abcdefghijlk.azurewebsites.net/api/IoTCIntegration?code=xxxxxxxxxxxxxxxx==

This is the URL that will be used to POST data to IoT Central in your Octave Cloud Action as described below.

Using a Cloud Action in Octave to POST Data to IoT Central

Your Cloud Action performs the following:

  • takes Events coming from a given Stream or a group of device Streams using Tag-based Cloud Actions.
  • retrieves the deviceId and measurements/data to be sent to IoT Central.
  • formats the payload in the data structure expected by IoT Central.
  • performs an HTTP.post to IoT central.

As you can see, there is only one URL to post data to IoT Central , and the only device-specific field is the deviceId in the payload.

To initially check that data goes through when you POST data with your Cloud Action:

  • check the logs of the Device Bridge in the Azure console.
  • run a report showing what is returned by Octave.http.post to a Stream ("/mycompany/iotcentral_post_results/:reports" as shown in the example code below:
function(event) {

// retrieve device ID

var deviceId = event.path.split("/")[3];

// fill-in your payload

// payload must follow the format below for IoT Central

var ICpayload = {  
"device": {  
"deviceId": deviceId},  
"measurements": {  
  "sensorA": event.elems.sensorA.value,  
  "sensorB": event.elems.sensorB.value}  
};

var icpostBody = JSON.stringify(ICpayload);  
var icpostHeaders = {'Content-Type': 'application/json'};

  
var icresult = Octave.Http.post('https://iotc-fnmgepx3vq5ir7e.azurewebsites.net/api/IoTCIntegration?code=wwanxxxxxxxxx', icpostHeaders, icpostBody)

  
return {  "/mycompany/iotcentral_post_results": [icresult]};

}

🚧

Create Streams Before you Return Anything to Them in a Cloud Action

Before running the above Cloud Action, you have to create the "/mycompany/iotcentral_post_results" Stream using the Octave UI or the API.

Allowing Devices in the IoT Central Application

For device data to be received on the IoT Central application side:

  • a device template, describing the telemetry JSON structure that is pushed from the devices must first be created (at least once for your category of device).
  • any device which starts sending data will first appear as being not associated to a template. IoT Central will only start collecting its data once you have associated it to a device template.

1. Create a device template:

Navigate to Device templates and follow the process. Note that the IoT Central UI evolves over time so the steps below might have changed, but things are usually pretty straightforward.

  • Select "New", Select IoT Device

  • Do not click Gateway device

  • Create a template and enter a device template Name

  • Then, either create a Custom device or use import a .json template. Usually you go for Custom to set up your own device (list of sensors and properties). A sample .json template is provided below.

  • You must create at least one Interface

  • Add Interface

  • Custom

  • Add capability: this is where you map the data reported by your device to Telemetry data names:

  • Display Name: choose a user friendly name, for instance "Sensor A data"

  • Name: this must exactly match the name of the field as present in the device "measurement" payload reported from the device, and the case must match as well. Here, your Sensor A in the Cloud Action code seen before is: "sensorA" as the payload coming from the device is formatted as: { "measurements": {"sensorA": event.elems.sensorA.value}.

  • Add as many telemetry values as you need

  • then save the Interface

  • and in the top bar: "Publish" your device template. Whenever you make a change later on, you need to publish it again for changes to occur.

You can use this file to import a device template that has three Sensors (temperature, light, and pressure). You can use it for a mangOH Red or mangOH Yellow for instance, provided that the reported Sensor names under "measurements" are: "light", "pressure", and "temperature".

{
  "@id": "urn:octaveNamIotc:MangoHRed_42d:1",
  "@type": "CapabilityModel",
  "implements": [
    {
      "@id": "urn:octaveNamIotc:MangoHRed_42d:p1ws_jan9:1",
      "@type": "InterfaceInstance",
      "displayName": {
        "en": "Interface"
      },
      "name": "MangoHRed_35t",
      "schema": {
        "@id": "urn:octaveNamIotc:MangoHRed_35t:1",
        "@type": "Interface",
        "displayName": {
          "en": "Interface"
        },
        "contents": [
          {
            "@id": "urn:octaveNamIotc:MangoHRed_35t:light:1",
            "@type": "Telemetry",
            "displayName": {
              "en": "Light"
            },
            "name": "light",
            "schema": "double"
          },
          {
            "@id": "urn:octaveNamIotc:MangoHRed_35t:temperature:1",
            "@type": "Telemetry",
            "displayName": {
              "en": "Temperature"
            },
            "name": "temperature",
            "schema": "double"
          },
          {
            "@id": "urn:octaveNamIotc:MangoHRed_35t:pressure:1",
            "@type": "Telemetry",
            "displayName": {
              "en": "Pressure"
            },
            "name": "pressure",
            "schema": "double"
          }
        ]
      }
    }
  ],
  "displayName": {
    "en": "MangoH Red"
  },
  "@context": [
    "http://azureiot.com/v1/contexts/IoTModel.json"
  ]
}

2. Associate a device to an existing template:


As seen in the screen capture below, a device has no assigned device Template:

Select that device and click Migrate to associate it to an existing Device template:

3. View Device Telemetry

There are three main ways to access to device Telemetry:

  • Create a standard device View as part of the "device Template". By doing this, when you browse into your Device in IOTC, you have access to the View of your device (the device dashboard displays details for one device). In order to create/update the device View, navigate to the device Template, edit it, and publish it.

  • Create a Dashboard: navigate to "Dashboards" and create or edit a dashboard. When you create a dashboard, it can be made public (i.e., only the the IOTC App) or private (i.e., only you have access).

  • Show Analytics: this is non pre-formatted access to all stored telemetry data. Select a device group, the Telemetry values, rules (count, average, ...) and split (none, per device Id, ....) to create graphs.

Device View:

Dashboard:

Analytics:

Updated 10 days ago

Pushing Data from Octave to IoT Central


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.