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 Build > 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.
  6. Simulator: allows you to test and debug an HTTP Cloud Connector using existing Events or writing your Event as input.

Creating an HTTP Cloud Connector

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

  1. Navigate to Build > 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 information, you can find your username and master token on the user screen in 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 static headers can also be added here (e.g., content-coding).

You can also optionally enable the Dynamic Headers checkbox which allows you to programmatically add headers dynamically based on the incoming Event. For example, the following screenshot shows how to dynamically add a header and populate it with location data from the Event:

  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.

Testing and Debugging an HTTP Cloud Connector Using the Simulator

The Simulator tab allows you to create one or more simulations to test or debug your HTTP Cloud Connector using existing Events or writing your own test Events as input. Doing so allows you try different inputs, write custom code (e.g., to display debugging information), and to see both the complete request and response.

Follow the steps below to simulate an HTTP Cloud Connector:

  1. Create or edit an existing HTTP Cloud Connector.
  2. On the HTTP Cloud Connector screen, click the Simulator tab.
  3. Configure your first input Event by clicking the edit button:
  1. Configure the Event using one of the following methods:
  • Write the JSON for a custom Event in the Input Event field; or
  • Locate an Event in the list and click the copy button to copy the Event's JSON to the Input Event field. Note that you can optionally modify the copied content as well.
  1. Click Set to use the Event for simulation and to close the popup:
  1. (Optional) Navigate to the Body tab, ensure String returned from custom function is selected, and add/modify the code to control what information the simulation will generate. For example, you could add the statement console.log(event.elems) to display the fields of the Event object.
  2. Click Run to invoke the simulation with the configured Event.

The output is shown below the Event. Console output is indicated by the icon with three lines and the complete request is indicated by the arrow icon; both can be expanded to display additional detail:

📘

Note

You can optionally repeat Step 3 and onwards to configure multiple simulations.

Creating an Azure IoT Hub Cloud Connector

Follow the steps below to create an Azure IoT Hub Cloud Connector in the Octave Dashboard:

  1. Navigate to Build > 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

A global Shared Access Policy, enabling "Device connect" must be enabled on your IoT Hub. That Shared access policy must be provided in the IoT Hub Connector settings

  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" and "Policy Name" of your IoT Hub's Shared access 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 to retrieve these credentials.
  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 the Headers tab and verify or configure the header settings for the HTTP request. Additional static headers can also be added here (e.g., content-coding).

You can also optionally enable the Dynamic Headers checkbox which allows you to programmatically add headers (e.g., Azure IoT Application Properties) dynamically based on the incoming Event. For example, the following screenshot shows how to dynamically add two Application Properties and populate them with location data from the Event:

  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 Build > 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 2 months 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.