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 receptor device template contains the following driver characteristics:

• Pull Device
• Runs on Schedule
• Does not need configured Property Mappings. With typical Scheduled Receptor Device use cases, the registration packet is defined by the developer in the Device Interface’s file.
• Limits external telemetry sources to one source per Device Interface. However, this external telemetry source could contain a collection of physical devices. In other words, the Device Interface will communicate with one external telemetry source “point”, but can receive data from multiple physical devices.
• Meta requests sent automatically
• Telemetry requests sent automatically

Typical use case

• You have one or more External Telemetry Sources that your service will pull the telemetry from on a scheduled basis.
• You do not need configured property mappings.
• Each configured device communicates with multiple External Telemetry Sources.
• The meta and telemetry sent from each configured device has Device Name, Device Type, Group Name and Gateway Id values that are dependent on the External Telemetry Source that the meta or telemetry originated from.

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.