Virtual Resources

Virtual Resources are resources which are user-defined and are not associated with a physical measurement or device property. Virtual resources are useful for:

• capturing and monitoring state information
• storing global values for edge processing
• aggregating multiple resource values together into a single resource that can be monitored in a single stream

The following subsections describe how to create, read/write, and store state information in virtual resources within Octave.

Creating a Virtual Resource

Virtual Resource are added to your device from the Device > Resources screen.

1. Navigate to Device > Resources
2. Click the Add Virtual Resource button

3. Define the Virtual resource

In the following example we create a Virtual Resource of type JSON and we don't provide any Configured value.
Click Add and Apply to finalize the creation.

The configuration is sent to the device, which will create the Virtual Resource, it will appear after few seconds in the Resource tree:

Write in a Virtual Resource

The instruction to write in the Virtual Resource /virtual/report from an edge action is:

function(event) {
 // edge action code
 // ...
  
 var report = {
   "temperature": temperature,
   "pressure": pressure,
   "location": { "lat": lat, "lon": lon },
   "light": light,
   "signal_bars": bars,
   "cell_technology": technology
 }
 
 return {
  "vr://report": [report] // or 
  "dh://virtual/report/value": [report] 
 }
}

Let's update the Virtual Resource we created previously with sensor readings we gather from our device, so we create a device report, we can send to the cloud periodically.
Here are some examples for mangOH red:

mangOH red

function(event) {
	var temperature = Datahub.read("/redSensor/imu/temp/value",0).value;
	var pressure = Datahub.read("/redSensor/pressure/value",0).value;
	var lat = 0;
	var lon = 0;
	var pos = Datahub.read("/location/coordinates/value",0);
	if (pos) {
		lat = pos.lat;
		lon = pos.lon
	}
	var light = Datahub.read("/redSensor/light/value",0).value;
	var bars = Datahub.read("/util/cellular/signal/value",0).value.bars;
	var technology = Datahub.read("/util/cellular/signal/value",0).value.rat;
	var report = {
		"temperature": temperature,
		"pressure": pressure,
		"location": { "lat": lat, "lon": lon },
		"light": light,
   		"signal_bars": bars,
   		"cell_technology": technology
 	}
 
	return {
	"vr://report": [report]
	}
}

Read a Virtual Resource

The instruction to read the value of a Virtual Resource is:

function(event) {
 //edge action code
 // ...
 
var report = Datahub.read("/virtual/report/value",0).value;

// report will contain the JSON object   
  
}

Observe the Virtual Resource

Like any other resource, a Virtual Resource can be observed:

In this example, the Virtual Resource updates are reported in the stream report of your device:

Use Virtual Resources to store state

Virtual Resources configured in /virtual/config are persisted in the non volatile memory of the device. Check out the section about Resources for more details.

In the following example we use a Virtual Resource to store a state, and send an alert to the Cloud.

1. Navigate tio the Device > Resources screen
2. Add Virtual Resource lightThreshold of type Numeric, with Configured value of 1500
3. Add another Virtual Resource tooMuchLight of type Boolean false
4. Apply the changes

5. Add an observation to the resource redSensor/light/value to an edge action

6. Write the following edge action to detect and report light alerts

function(event) {
	var light_reading = event.value;
	var light_threshold = Datahub.read("/virtual/lightThreshold/value",0).value;
	var previous_state = Datahub.read("/virtual/tooMuchLight/value",0).value;

	if(previous_state===false) {
		if(light_reading >= light_threshold) {
			//send alert and store state
			return {
				"cl://": [{"alert": "tooMuchLight", "lightReading": light_reading, "lightThreshold": light_threshold}],
				"vr://tooMuchLight": [true]
			}
		}
		// else do nothing: no alert
	}
	// else do nothing, alert already raised
}

7. You can change the light intensity on your device until the event "toMuchLight" is sent to the Cloud

The alert is sent only once.

You can also check that the Virtual Resource tooMuchLight value has changed to true:

8. You can now reset the status of the alert sending a command to the device, setting false to the Virtual Resource tooMuchLight:

• Navigate to the Device > Resources screen
• Locate the the virtual resource tooMuchLight
• Click the Send command button

• Enter the new value. The screen is showing the previous command you sent.
• and click the Send button

• You can see the command is actually sent checking the Recent changes widget in the Device details page.

• And also confirm the virtual resource tooMuchLight now reports false in the Device > Resources screen:

📘

More details on the Virtual Resources

Check our Resources reference for more information about resources in general, and persistence of Virtual Resources too.