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

Events and Streams

Streams are a collection of Events, each of which describes something that occurred from some source (e.g., a command value that was sent to an Octave edge device, a value that was read from an asset etc.).

There are several different sources that can create Events in Streams. One source is an Octave edge device with an Observations or Edge Action set to route data to Cloud Immediately or Store and Forward. Events can also be created directly in Streams from a Cloud Action, the Octave user interface, via a REST API call, or from within a periodic Task.

In the case of an Observation, the Stream will be created automatically as soon as the Observation is created.

Event JSON Structure

When new Events arrive in the cloud from the device, Octave stores them in a Stream as JSON documents and adds additional metadata. The elems field contains the data related to the Event, while metadata consists of extra fields that describe the Event including both the time at the edge, as well as the time received in the cloud are stored. Having both of these times available for each event is important for more sophisticated data orchestration strategies.



The fields of the Event that you can write data to from the edge or the cloud are the elems and hash fields. All the other fields of the Event are generated by the system and cannot be written to. For more information about Event fields see Event in the Octave API documentation.

The following is an example of the JSON document for an Event:

  "creationDate": 1587387677625,
  "creatorId": "i5d8...",
  "elems": {
    "redSensor": {
      "accel": {
        "enable": true,
        "period": 10
      "light": {
        "enable": true,
        "period": 60
  "generatedDate": null,
  "hash": null,
  "id": "e5e9d9d...",
  "lastEditDate": 1587387677625,
  "lastEditorId": "i5d873b...",
  "location": null,
  "metadata": null,
  "path": "/iot_solutions/devices/d_reg_test/:command",
  "streamId": "s5daf2...",
  "tags": {

Viewing Events

You can view Events on the following screens within the Octave UI:

  • Device > Details screen, *Recent events** region.
  • Device > Streams listing screen - click on a Stream path (e.g., :command) to display Events on that stream.
  • Cloud > Streams listing screen - click on a Stream path to display Events on that stream.

Depending on the type of Stream, the following columns of information may be displayed to the Stream's Events:

  • createdDate: the date/time when the Event was created. For cloud Streams, this is the date/time when the Event reached the cloud.
  • generatedDate (applicable to Sensor Events): the date/time when the Input or Sensor on an Octave edge device provided a reading/measurement.
  • delta: the difference, in milliseconds, between the createdDate and generatedDate.
  • elems: the information stored in the Event (i.e., the Event's JSON message).

Stream Hierarchy

Streams are organized in a hierarchy like a file system. Not only do devices have their own space, but users and companies do as well. This hierarchy plays an important role in controlling access to the data contained in events.

The hierarchy is as follows:

  • <company>: The company is the root namespace under which all Cloud Streams exist.
  • :inbox: Contains all company-wide streams showing every event that has happened on the system. For example /company/:inbox/cloud-actions shows events generated from the respective source of actions.
  • :summary-inbox: Contains redacted versions of all events under the :inbox node, with minimal information.
  • devices: Lists all devices registered on Octave. Each device can then be expanded to show its streams.
  • users: Lists all users registered on Octave. Each user can then be expanded to show its streams.



The ":" prefix, indicates that the Stream was generated by Octave and cannot be modified.

Updated 3 months ago

Events and Streams

Suggested Edits are limited on API Reference Pages

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