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 Events via Cloud Connectors

Overview


A Cloud Connector provides a resilient method to push Event data from specific Streams (e.g., from assets connected to Octave edge devices) to external cloud systems. Octave currently supports two types of Cloud Connectors:

  • HTTP Cloud Connector: allows you to send data to an external endpoint using REST requests. Here, you specify HTTP connection parameters and Octave will re-push Events if there is a brief outage on the external REST endpoint.
  • Azure IoT Hub Gateway Connector: works similarly to an HTTP Cloud Connector and it pushes Octave Events to Azure IoT Hub as "Device-to-Cloud Messages" (telemetry). As only authenticated devices can push data to IoT Hub, this connector handles the SAS Token authentication for each device.

Cloud Connectors are similar to Cloud Actions, in that they have a source Stream of Events to be processed and can define a JavaScript function to transform Events. Unlike Cloud Actions, Cloud Connectors publish their result to specified service end points. This target service can be either statically defined or dynamically specified via an optional routing script.

Cloud Connector Dashboard Overview

The Cloud Connector creation screen (accessed via Cloud > Connectors in the Octave Dashboard) has the following features:

  1. Source Stream or Tag: specifies the source of the Events that the Cloud Connector should handle.
  2. Service: specifies the type of target to configure the Cloud Connector for (e.g., HTTP, Azure IoT Hub, etc.). Depending on the type selected, the configuration tabs (4) and fields will vary.
  3. Enabled Toggle: enables or disables the Cloud Connector.
  4. Service-specific Tabs: provides various configuration fields specific to the Service (2) selected.
  5. Console: displays information about the Cloud Connector such as when and how it was updated, any errors that occurred when configuring it, etc. This can be used when diagnosing and debugging the Cloud Connector.

Creating an HTTP Cloud Connector

Follow the steps below to create an HTTP Cloud Connector in the Octave Dashboard:

  1. Navigate to Cloud > Connectors.
  2. Click Add Cloud Connector.
  3. Select the HTTP Cloud Connector type. The New cloud connector editing screen appears.

📘

Note

You can change your Cloud Connector type when configuring it.

  1. Select or start typing a name in the Source Stream or tag dropdown. This will be the source of Events. Set Source stream or tag to Stream to use the data values from a Stream in Octave. If the field is set to Tag, the data values will come from the tagged device's Stream (a device stream field will appear, allowing you to select the stream).
  2. Configure the type of REST request on the Request tab and specify a URL. Setting URL type to Static (the default) allows you to enter a static URL. Setting URL type to Dynamic displays a code editor in which you can programmatically create a dynamic URL based on an Event.

For example, the following code shows how the location of an Event could be included as a query parameter of the URL:

function (event){
    return "https://myserver.com/data?" + event.tags.location;  
}
  1. Click the Authentication tab, select the type of authentication used by the external system, and populate the authentication-specific fields. Note that for the Octave authentication type, you can find your username and master token by navigating to the Master Token tab near the bottom left corner of the Octave Dashboard.
  2. Click the Body tab and specify the type of content to return. Setting Content data to Event object (the default) will send the entire Event as a JSON object to the external system. Setting Content data to String returned from custom function displays a code editor in which you can programmatically customize what Event data you'd like to send to the external system.

For example, the following code shows how a new Event can be sent to the external system that contains only the region and sensor information from the original source Event:

function (event) {
   return {
       "region": event.tags.region,
       "value": event.elems.sensor
   }
}
  1. Click the Headers tab and verify or configure the header settings for the HTTP request.

Authorization and Content-type header entries will appear on the Headers tab if they were configured on the previous tabs. Modifying the values on the Headers tab, will cause the corresponding fields on the previous tabs to be updated as well.

Additional headers can also be added here (e.g., content-coding).

  1. Click the Response tab.

The Success status codes and Ignored error status codes define the HTTP success and error response codes that the Cloud Connector expects to receive. If none of the specified codes are returned, Octave will resend the Cloud Connector Event up to three times. After three unsuccessful retries, the Cloud Connector will become disabled. You can re-enable the Cloud Connector by setting the Enabled checkbox and re-saving the Cloud Connector.

  1. Click Save to save the Cloud Connector. The Cloud Connector is now live. Note that you can enable or disable the Cloud Connector at any time by toggling the Enabled checkbox and re-saving the Cloud Connector.

Creating an Azure IoT Hub Cloud Connector

Follow the steps below to create an HTTP Cloud Connector in the Octave Dashboard:

  1. Navigate to Cloud > Connectors.
  2. Click Add Cloud Connector.
  3. Select the Azure IoT Hub Cloud Connector type. The New cloud connector editing screen appears.

📘

Note

As the IoT Hub connector is "cloud-to-cloud", it uses one unique authentication key for all devices. Data however, appears as coming from each individual device on the IoT Hub side.

For the Octave IoT Hub Connector to report device data to your IoT Hub instance:

  • the devices need to be declared in your IoT Hub
  • the device "IoT Hub ID" must be assigned each Octave devices' "Azure IoT Hub" Custom ID
  1. Select or start typing a name in the Source Stream or tag dropdown. This will be the source of Events. Set Source stream or tag to Stream to use the data values from a Stream in Octave. If the field is set to Tag, the data values will come from the tagged device's Stream (a device stream field will appear, allowing you to select the stream).
  2. Click the Properties tab and enter :
  • your Azure IoT Hub name,
  • the "Shared access key" of your IoT Hub and the related policy name (by default it points to the "device" policy). Any policy configured with "Device connect" can be used. Go to your Azure Portal to manage your IoT Hub and its Shared Access policies.
  1. Click the Body tab and specify the type of content to return. Setting Content data to Event object (the default) will send the entire Event as a JSON object to the external system. Setting Content data to String returned from custom function displays a code editor in which you can programmatically customize what Event data you'd like to send to the external system.

For example, the following code shows how a new Event can be sent to the external system that contains only the region and sensor information from the original source Event:

function (event) {
   return {
       "region": event.tags.region,
       "value": event.elems.sensor
   }
}
  1. Click Save to save the Cloud Connector. The Cloud Connector is now live. Note that you can enable or disable the Cloud Connector at any time by toggling the Enabled checkbox and re-saving the Cloud Connector.

Once the IoT Hub Cloud Connector is created, make sure that your IoT Hub Device IDs are assigned to each of your Octave devices.

Assigning Your IoT Hub Device ID to an Octave Device

After you have created your Cloud Connector you must add the "Iot Hub device ID" to your Octave device(s). You can find this ID in your Azure Portal interface, where you manage/declare your IoT Hub devices in Azure.

Follow the steps below to add the "Iot Hub device ID" to your Octave device(s):

  1. Navigate to Device >> Details.
  2. Locate the Custom IDs field and click the edit icon.
  3. Enter your Iot Hub device ID.
  4. Click Set.

Creating a Cloud Connector via the Octave REST API

You can also programmatically create and manage cloud connectors using Octave's Cloud REST API . For more information see:

Updated about a month ago

Pushing Events via Cloud Connectors


Suggested Edits are limited on API Reference Pages

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