Virtual Device Service Component

The Virtual Device Service component allows you to simulate different kinds of device and generated readings.

The Virtual Device Service supports the following key features:

Setting, and subsequently reading, values
Generating random boolean or numeric values in a specified range
Generating numeric value sequences representing a waveform
Generating numeric values, which steadily increase or decrease
Generating values following a fixed script

Virtual Device Service Configuration

Note

The core components required for running the Virtual Device Service (and all other device services) are contained in Device Service Component Configuration. Please refer to this page to ensure the appropriate core components are assigned before continuing.

The Virtual Device Service has no service-specific options for configuration.

Virtual Device Service Configuration Example

{
  "Library": "libxrt-virtual-device-service.so",
  "Factory": "xrt_virtual_device_service_factory",
  "Name": "virtual",
  "TelemetryTopic": "xrt/devices/virtual/telemetry",
  "RequestTopic": "xrt/devices/virtual/request",
  "ReplyTopic": "xrt/devices/virtual/reply",
  "DiscoveryTopic": "xrt/devices/virtual/discovery",
  "StateDir": "./deployment/state",
  "ProfileDir": "./deployment/profiles",
  "Scheduler": "sched",
  "Logger": "logger",
  "ThreadPool": "pool",
  "Bus": "bus"
}

Virtual Device Profile

Details on general profile usage can be found on the Device Profiles page

There are five types of virtual resources:

Arithmetic
Random
Script
Waveform
Non-sequence

Arithmetic Resources

The attribute sequenceType must be set to "arithmetic" to create a resource of this type.

This is a read-only resource where an initial value is set via the attribute firstValue and after each reading the value will be incremented/decremented by a specified amount via the attribute difference.

The available attributes are described in the following table:

Attribute	Description	Valid Values	Default
firstValue	Defines the initial value	Any value of the same type as the resource data type	0 or 0.0
difference	Defines the increment/decrement between values	Integer, Floating-point	1 or 1.0

The following data types are supported for this resource:

Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64

An example resource is provided which starts at a value of 10 and after each reading will increment the value by 2.

{
  "name": "ArithmeticResource",
  "description": "Integer value which starts at 10 and counts upward in 2",
  "attributes": {"sequenceType": "arithmetic", "firstValue": 10, "difference": 2},
  "properties": {"valueType": "Int32", "readWrite": "R"}
}

Random Resources

The attribute sequenceType must be set to "random" to create a resource of this type.

This is a read-only resource that generates a random value between an upper and lower limit that can be specified via the attributes minimum and maximum.

The available attributes are described in the following table:

Attribute	Description	Valid Values	Default
minimum	Defines the minimum limit of the random value	Any value of the same type as the resource data type	Minimum value of the resource data type
maximum	Defines the maximum limit of the random value	Any value of the same type as the resource data type	Maximum value of the resource data type

The following data types are supported for this resource:

Bool
Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64

An example resource is provided which will generate a random value between -10 and 100.

{
  "name": "RandomExample",
  "description": "Generate random value between -10 and 100",
  "attributes": {"sequenceType": "random", "minimum": -10, "maximum": 100},
  "properties": {"valueType": "Int8", "readWrite": "R"}
}

Script Resources

The attribute sequenceType must be set to "script" to create a resource of this type.

This is a read-only resource that provides a sequence of values to be iterated via the attribute script. The sequence will restart once the end has been reached.

The available attributes are described in the following table:

Attribute	Description	Valid Values	Default
script	Defines the script sequence of values where elements can be repeated	Vector where each element is a map that can contain 2 entries: value - Mandatory value of the same type as the resource data type repeat - Optional positive integer	No default; must be set

The following data types are supported for this resource:

Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64

An example resource is provided which produces a sequence of 1, 2, 3, 3, 3, 3, 3, 4, 5 and then repeats.

{
  "name": "SequenceExample",
  "description": "Integer value which follows a scripted sequence from 1 to 5, repeating value 3 five times",
  "attributes":
  {
    "sequenceType": "script",
    "sequence": [{"value": 1}, {"value": 2}, {"value": 3, "repeat": 5}, {"value": 4}, {"value": 5}]
  },
  "properties": { "valueType": "Int32", "readWrite": "R" }
}

Waveform Resources

The attribute sequenceType must be set to "waveform" to create a resource of this type.

This is a read-only resource where several types of waveform can be generated by setting shape attribute. The wave can also be altered by changing its parameters using the amplitude, period, phase and offset attributes.

The available attributes are described in the following table:

Attribute	Description	Valid Values	Default
shape	Specifies the waveform shape to generate	"sinewave", "sawtooth", "triangle", "square"	"sinewave"
period	Specifies the period of the wave; how many successive readings constitute a full cycle	Positive integer	No default; must be set
amplitude	Specifies the amplitude of the wave, measured peak-to-trough	Floating point	No default; must be set
phase	Advances the wave by a specified number of readings	Positive integer	0
offset	Specifies an offset to apply to generated values	Floating point	0.0

The following data types are supported for this resource:

Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64

Note

These waveform values are generated as double-precision floating-point values and cast to the resource data type. If the value produced is larger than the data type can represent then the reading will return an error.

Two example resources are provided which will generate the same sine wave. The second resource has a phase and offset change.

{
  "name": "ExampleSinewave1",
  "description": "Value which traces a sinewave",
  "attributes": {"sequenceType": "waveform", "shape": "sinewave", "period": 8, "amplitude": 4.0},
  "properties": {"valueType": "Float64", "readWrite": "R"}
},
{
  "name": "ExampleSinewave2",
  "description": "Another value which traces a sinewave",
  "attributes": {"sequenceType": "waveform", "shape": "sinewave", "period": 8, "amplitude": 4.0, "offset": 10.0, "phase": 2},
  "properties": {"valueType": "Float64", "readWrite": "R"}
}

The following graph shows two reading sequences obtained from the sinewave resources, both with an amplitude of 4.0 and a period of 8; sinewave2 also has an offset of 10.0 and a phase of 2 (which causes it to lead sinewave by two readings):

Generated sine waves

Non-sequence Resources

If the attribute sequenceType is not set, it will default to a standard resource you can write to and read back.

The attribute firstValue can be used to set an initial value. All data types are supported for this resource but only a subset are supported when the firstValue attribute is included. This subset is:

String
Bool
Int8
UInt8
Int16
UInt16
Int32
UInt32
Int64
UInt64
Float32
Float64

The available attributes are described in the following table:

Attribute	Description	Valid Values	Default
firstValue	Defines the initial value	Boolean, Integer, Floating-point, String	Defaults to an empty or zero value

An example resource that is provided allows writing and reading of an Object value.

{
  "name": "ExampleNonSequenceObject",
  "description": "Resource that stores an object",
  "attributes": {},
  "properties": { "valueType": "Object", "readWrite": "RW"}
}

An example resource that is provided allows writing and reading of a String value with an initial value of "Hello".

{
  "name": "ExampleNonSequenceString",
  "description": "Resource that stores a string with initial value",
  "attributes": {"firstValue":  "Hello"},
  "properties": { "valueType": "String", "readWrite": "RW"}
}

Device Commands

See the Device Commands page for details on how to define device commands for grouping device resources for fewer requests.

Device Service Interaction

For information on how to dynamically execute reads, writes, setting up schedules and more, please refer to the MQTT API Guide.

For interactive examples of the Virtual Device Service refer to Virtual Xrt Example. Follow the instructions in those links which will demonstrate many features of Edge Xrt with the Virtual Device Service.

Run the Virtual Device Service

Find details on how to run the Virtual Device Service on the Run Device Services page.