Setting a Value From a REST API Call

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:

• Permanently changing a value updating the device configuration: Typically used to set a default configuration such as with a Blueprint when the device is being set up.
• Temporarily changing a value via an event in the command stream: Typically used to send a command or configure a specific parameter on a device as you also could do from an Edge Action or Cloud Action.

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. Locate your username and master token on the user screen in the Octave Dashboard.
3. Copy the username and master token. You must provide these in the X-Auth-User and X-Auth-Token headers respectively, when invoking the endpoint.
4. Navigate to Build > 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.
5. (Recommended) In a command-line window, invoke the GET /device/<device_identifier> endpoint to obtain the full state object for the device. You will need to send a full state object in the next step. See the warning below.

❗️

Warning: You Must Provide the Full Device State Object

When setting a value (performed in Step 6 below) you must supply the full object to update even a single compound attribute (i.e., a single attribute inside the "state" object). If you only supply a partial state object (i.e., only the attribute(s) that you want to update), then the state object will be updated to contain only the attribute(s) you provide.

Therefore it's recommended that you first invoke the GET /device/<device_identifier> endpoint as suggested in Step 6, to obtain the full state object and then use that as the base object on which modify, add, and/or remove the attributes of the state object that you will send.

6. In a command line window 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,

      ...
   }
}

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.

Gathering the Auth Token and User

1. Open a browser and log in to the Octave Dashboard.
2. Locate your username and master token on the user screen in the Octave Dashboard.
3. Copy the username and master token. You must provide these in the X-Auth-User and X-Auth-Token headers respectively, when invoking the endpoint.

Changing the Value

Choose one of the following methods to send an Event.

Method 1 - POSTing to the Command Stream Directly

Follow the steps below to POST directly the device's Command Stream. This is the more commonly used method because you only need to know the path/endpoint of the device to POST to its Command Stream:

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" \
     -H "X-Auth-User: <your user name>" \
     -H "X-Auth-Token: <your user token>" \
     -H 'Content-Type: text/plain; charset=utf-8' \
     -d $'{ 
 "path" : "/company_name/devices/device_name/:command",
 "elems" : { "/lcd/txt1": "Pong" } 

}'

Method 2 - POSTing to the Command Stream Using its Stream ID

Follow the steps below to identify the ID of the device's :command Stream and to POST an Event directly to that Stream. Note that this method is less commonly used than Method 1 because it requires you to know/identify the ID of the device's Command Stream:

1. Navigate to Build > Device > Streams and locate the :command stream.
2. Select the `:command Stream.
3. 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.

4. 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" } 
}'

Verifying the Result

After the endpoint executes, the first line of the LCD screen should update with the value specified in the Event. You should also see that the Event was 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 :inbox Stream 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 :

JSON

{  
  "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 } \
}'