1. Driver Characteristics
2. Typical use case
3. Properties
4. Methods
   1. CreateProperty
      1. Parameters
   2. SendMetaAsync
      1. Parameters
   3. SendTelemetryAsync
      1. Parameters
5. Call-back functions
   1. OnInitializeAsync
   2. OnStartAsync
   3. OnProcessDeviceCommandAsync
      1. Parameters
   4. OnGetPropertyMapsAsync
      1. Parameters
   5. OnNewOptionsAsync
      1. Parameters

Driver Characteristics

The scheduled device template contains the following driver characteristics:

• Push Device
• Does not run on a Schedule
• Multiple External Telemetry Sources per Device
• Meta requests sent manually
• Telemetry requests sent manually

Typical use case

• You have one or more External Telemetry Sources that will push data to your device either directly, or through a subscription service.
• You do not need configured property mappings.
• One or more configured Devices, each of which can communicate with multiple external telemetry sources.
• Device Name, Device Type, Group Name and Gateway Id values sent from each configured Receptor Device Interface are dependent on an external telemetry source’s properties. In other words, these properties are not predefined in the Device’s configuration, but depend on the data being received from each external telemetry source.

Properties

Methods

The following methods are provided for the purposes of creating meta and telemetry requests.

CreateProperty

• Used to create an IDevicePropertyObject with the specified data type and name.
• These are required when sending Meta and Telemetry requests

Parameters

• A string containing the required data type

• A string containing the name of the property.

• Returns an IDevicePropertyObject

SendMetaAsync

• Sends a Meta request to the Collector service.

• Meta requests must be sent at least once per External Telemetry Source, when the source first sends telemetry after service start, and every time the properties change.

Parameters

• A dictionary containing the list of IDevicePropertyObject instances that hold the telemetry values. The key of each dictionary item must be the PropertyPathKey property of the IDevicePropertyObject.

• An IDeviceInfo instance containing the information about the device associated with the telemetry values. This property is optional. If null, it will use the configured values for the Device.

• Returns a Boolean indicating whether the Meta request was successfully queued for transmission.

SendTelemetryAsync

• Sends a Telemetry request to the Collector service.

Parameters

• A dictionary containing the list of IDevicePropertyObject instances that hold the telemetry values. The key of each dictionary item must be the PropertyPathKey property of the IDevicePropertyObject

• An IDeviceInfo instance containing the information about the device associated with the telemetry values. This property is optional. If null, it will use the configured values for the Device.

• Returns a Boolean indicating whether the Telemetry request was successfully queued for transmission.

Call-back functions

The following method callbacks are provided in order to state changes in the driver.

OnInitializeAsync

• Executed when the Device needs to be initialized.
• If the device needs to report its Make and Model information with the Device Meta, it should obtain and set this information in this call-back.

OnStartAsync

• Executed when the Device is started.
• This task can be long running. Use the CancellationToken property to detect when the service shuts down.

OnProcessDeviceCommandAsync

• Executed when a Device Command needs to be processed.
• The device command, the current property list and the configured property maps are passed to the function as parameters. The function can set the current values for the property objects in the property list if it needs to.

Parameters

• An IDeviceCommand instance containing the device command to process.
• An ICurrentProperties instance containing a dictionary holding the current device properties and a dictionary holding the property mappings.

The function must return true if the device command was successfully processed.

OnGetPropertyMapsAsync

• Executed one or more times when the workflow is loading the options for the device and the configured Default Properties device.
• This function is executed at the start and whenever the options change.
• The function is expected to return a dictionary containing the list of property mappings associated with the device passed as a parameter.
• The device type is passed as an enumerated parameter. Current supported device types are Default Properties and Current Device.

Parameters

• A MapDeviceType enumeration that specifies the type of the device. Currently this can be either DefaultProperties or CurrentDevice.
• An IRaptorDevice instance holding the current device.
• An IRaptorDeviceOptions instance holding the current device options.

The function must return a dictionary containing the property maps configured for the device.

OnNewOptionsAsync

• Executed when the device’s options change.

Parameters

• A TOptions instance holding the previous device options.
• A TOptions instance holding the current (new) device options.