Skip to content

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 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.