This page provides detailed information about Resources including the various additional (sub) Resources that may be exposed by a Resource, Resource-specific details, accessing Resources in actions, and Resource naming conventions.

Maximum Path, Naming, and Data Limits

Octave enforces a number of limits on Resources for different types of Octave Edge Devices:

Resources as Tuples

A Resource is transmitted as a tuple consisting of a value and a timestamp:

{ "value" : value, "timestamp" : ts }

Anytime an application reads from or subscribes to a Resource, both the raw value and timestamp are delivered. The following shows some examples of the underlying tuples when transmitting different types of data:

• Boolean: [ true, 1554471539 ]
• Numeric values: [ 1.23, 1554471539 ]
• JSON [ "{"a":1}", 1554471539 ]
• Trigger: [ NULL, 1554471539]"

Additional Resources

A Sensor or Actuator will normally expose multiple Resources - both for direct access to the hardware and for configuration purposes. For example, a light sensor might expose the following resources:

The value Resource is the standardized naming convention for the Resource which generates the Events the Sensor is named for. So in this example, /sensor/light/value will generate light readings. For additional information about naming see Resource Names and Data Representations Across Contexts below.

A Sensor also exposes other Resources for configuration. The period Resource accepts a numeric value (in seconds) for how frequently the hardware should be polled, and emit a new Event on the value Resource. For example, a temperature sensor might have a polling frequency. If the sensor exposes a numeric Output called /polling_frequency, it can then receive values pushed to that Resource, and update its polling frequency accordingly.

Interrupt-based sensors, such as alarms, might not have this Resource. The Sensor driver has marked this Resource mandatory, indicating that a numeric value must be sent to this Resource for the Sensor to work.

The enable Resource allows the system to turn the Sensor on or off.

The calibration Resource allows the system to provide calibration information to the driver. It is marked non-mandatory, so the Sensor can be used without providing this information. If a value is not provided, it will default to the default value. The Resource's data type is JSON, indicating that it receives a string value containing valid JSON.

Additional Information About Specific Resource Types

Digital Input (GPIO)

GPIO pins configured as Inputs in Octave will report their value as true or false depending on if the voltage, which varies by pin, is above or below the midpoint of a voltage range (within some tolerance). Internal pull-up or pull-down resistors can also be enabled.

If edge detection is enabled, the IO Service will update the value of the digital input and emit an event to any Observations attached to the Resource any time the state changes from high to low, or vice versa. Without edge detection, you must configure a period on your IO Resource and the IO Service will report a boolean value at the specified periodicity. This "interrupt" functionality can be very useful when detecting events like a button push or switch throw that you might otherwise miss between polls when observing boolean values at a set period.

Persistence of Virtual Resources

There is no specific option to persist Virtual Resources: any Virtual Resource defined in the /virtual/config resource is persisted on the device.

The values of the resources are written in the flash memory :

• every 60 seconds,
• when the Virtual Resource configuration is updated,
• when the edge goes to low power mode,
• when edge reboot command is triggered: /util/reboot/trigger.

When the edge is switched on, the virtual application reads the new value from the internal storage and initialize the resource with the latest value stored. If there is no value stored in the non-volatile memory, the configured value is applied.

When a blueprint is applied, the configured value in the cloud is not used to set the new value of the virtual resource. This way the persisted value on the edge remains.

When a new configuration is sent from the cloud, if it is set, the configured value is applied to the Virtual Resource which may change.

From the Cloud it is also possible to update any Virtual Resource sending an Event with the Virtual Resource Value path to the :command stream of the device.

It is also possible to create non-persisted Virtual Resources from an Edge Action using the following syntax, in this case the Resource will not be persisted.

return { "vr://my_resource_name": [my_resource_value] }

Resource Names and Data Representations Across Contexts

Octave features various ways of naming Resources and representing data depending on the context of use.

Data

Event in Streams and input to Cloud Action

When an Event is received in a Cloud action, the event parameter is deserialized from the following JSON.

Note that the Resource 'value' is not included in the event sent to the Cloud, the actual value is reported under the Resource name directly.

{
  "elems": { 
    //event JSON
    "virtual" : { 
      "NAME" : value
    }
  },
  "tags": {},
  "metadata": null
}

Event in Edge Action
When an Event is received in a Cloud action, the event parameter is deserialized from the following JSON.

function(event) {
 
  //edge action script
 var Val = event.value;
  
}
 
//event JSON 
{
  "value" : value,
  "timestamp" : ts // ex: 1582827837.235676 (float)
}

For example, the code can read the value of a light sensor Resource from event.value:

function(event){
  var lightReading = event.value;
  var lightDescription;

  if (lightReading > 1500) {
    lightDescription = "bright";
  } else if (lightReading > 300) {
    lightDescription = "a bit dim";
  } else {
    lightDescription = "dark";
  }

  var s = "It's " + lightDescription + " in here.";

  return {
    "dh://lcd/txt3":[s]
  }
}

Resource Names

Virtual Resources

Resource Trigger

Cellular Signal Status Values

The /util/cellular/signal/status Resource indicates the current status of the Octave device's cellular connection. The following table lists the possible values: