GuidesAPI ReferenceForum
Login

Setting a Value From a REST API Call

This topic describes how to set a value using the Octave REST API.

Suggest Edits

The Octave REST API allows you to programmatically set actuator values on an Octave-enabled edge device from anywhere.

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, to update a single compound attribute (i.e. a single attribute inside the "state" object), you must supply the full object.

Check out the Device object REST API page for Reference.

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 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.
486
  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 stream :command 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 stream :command 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 about 4 years ago