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

Setting a Value From a REST API Call

This topic describes how to set a value on an Octave edge device from an external entity using the Octave REST API.

The Octave REST API allows you to programmatically set Actuator values on an Octave edge device from any device with an internet connection.

Here are the main options available with the Octave REST API for changing Resources on the edge:

The following subsections use the example of setting the LCD value on the LCD screen included with the mangOH Red, to illustrate the two methods for setting a value.

Permanently Changing a Value via the Device State

You can set a value by invoking the Update a Device endpoint of the Octave REST API. Follow the steps to invoke this endpoint using cURL, to set the text on the mangOH Red's LCD screen:

  1. Open a browser and log in to the Octave Dashboard.
  2. Click on the Master Token link, located in the bottom left corner of the navigation pane. The Master Token pop up appears.
  3. Copy the token and the user name from this pop up. You must provide these as X-Auth-Token and X-Auth_User headers respectively, when invoking the endpoint.
  4. Close the pop up.
  5. Navigate to Device > Details and copy the ID value. This is the unique ID of your mangOH Red that must be included as a path parameter for the REST API call.
  6. Open a command line window and enter the following, replacing the items surrounded by "<" and ">" with the required values:
curl -X PUT https://octave-api.sierrawireless.io/v5.0/<your company name>/device/<your device ID> \
     -H "X-Auth-User: <your user name>" \
     -H "X-Auth-Token: <your user token>" \
     -d '{
      "state": {
      "/lcd/txt1" : "<some text>",
      "/util/cellular/signal/period": 30,
      "/cloudInterface/developer_mode/enable": true,
      "/cloudInterface/store_forward/period": 60,
      "/util/cellular/signal/enable": true
      }
     }'

After the endpoint executes, the first line of the LCD screen should update with the value specified for /lcd/txt1 in the state body parameter.

The status field in the response indicates if the request was successful, and the body contains the entire updated state of the device:

{
   "head":{
      "status":200,
      "ok":true,
      "messages":[

      ],
      "errors":[

      ],
      "references":{

      }
   },
   "body":{
      "id":"d5c7...",
      "avSystemId":"a1c0...",
      "blueprintId":{
         "id":"b5d2...",
         "version":2
      },
      "broadcastDate":1568834780509,

      ...
   }
}

🚧

You Must Provide the Full Object

As shown in the example, you must supply the full object to update a single compound attribute (i.e., a single attribute inside the "state" object).

For more information, see the Device object REST API page.

Temporarily Changing a Value via an Event

You can change a value of one or several Resources on a device by calling the Creating an Event endpoint of the Octave REST API. The Event will have to be sent to the :command stream of the device.
Follow the steps below to invoke this endpoint using cURL, to set the text on the mangOH Red's LCD screen:

  1. Open a browser and log in to the Octave Dashboard.
  2. Click on the Master Token link, located in the bottom left corner of the navigation pane. The Master Token pop up appears.
  3. Copy the token and the user name from this pop up. You must provide these as X-Auth-Token and X-Auth_User headers respectively, when invoking the endpoint.
  4. Close the pop up.
  5. Navigate to Device > Streams and locate the :command stream.
  6. Select the :command stream
  7. Copy the unique identifier of the stream for the url: this is the unique ID of the :command stream of your device that must be included as a path parameter for the REST API call.
  1. Open a command line window and enter the following, replacing the items surrounded by "<" and ">" with the required values:
curl -X POST https://octave-api.sierrawireless.io/v5.0/<your company name>/event/<your stream id> \
-H "X-Auth-User: <your user name>" \
-H "X-Auth-Token: <your user token>" \
-d '{ 
  "elems": { "/lcd/txt1": "Pong" } 
}'

After the endpoint executes, the first line of the LCD screen should update with the value specified in the Event.

  1. You will see the Event added to the :command Stream of your device.

Like in previous example, you can know if the command has been processed on the device and if there was some error, looking for COMMAND_START / COMMAND_COMPLETE or COMMAND_FAULT in the stream :inbox of your device, they also appear in the Recent changes widget of the Device details screen.

📘

Resource Path

Most of the time you will need to change the sub resource value of a Resource, in this case you add value to the Resource path: /app/NAME/value.

Example of event to send in order to update a virtual resource named lightThreshold :

{  
  "elems": {
    "virtual/lightThreshold/value": 1200
  }
}

It is possible to add a timeout or ttl: time to live parameter to the Event you are sending to the :command Stream of a device. When this parameter is set, Octave will attempt to deliver the command to the device until it succeeds, or the timeout is exceeded. Timeout and TTL are defined as optional attributes of the event metadata field, parameter is milliseconds.

In the example below the command will timeout after 1 minute:

curl -X POST https://octave-api.sierrawireless.io/v5.0/<your company name>/event/<your stream id> \
-H "X-Auth-User: <your user name>" \
-H "X-Auth-Token: <your user token>" \
-d '{ 
  "elems": { "/lcd/txt1": "Pong" }, 
  "metadata": { "ttl": 60000 } \
}'

Updated 4 days ago

Setting a Value From a REST API Call


This topic describes how to set a value on an Octave edge device from an external entity using the Octave REST API.

Suggested Edits are limited on API Reference Pages

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