1. Selecting Driver Device Templates
   1. How to Select the Right Device Template:
   2. Receptor Device
   3. Scheduled Device
   4. Scheduled Receptor Device
   5. Device Configuration Manager
      1. Special Use Case: Device Manager and REST Controllers
   6. Deleting Devices

Selecting Driver Device Templates

Device Templates are pre-loaded with the SDK Package Template. The first step to building the application’s Driver is to choose the correct Device Templates that can be customised according to the application’s requirements.

How to Select the Right Device Template:

The Template best suited to a specific use case is influenced by several factors, including:

1. The communication direction (inbound/outbound). Possible scenarios:

   • Inbound communication: In this scenario the Driver is set up to receive meta and telemetry from any physical device that matches a general configuration. The physical device is pushing data to the Driver (i.e. “push” device). In a typical use case, the Receptor Device would be the best template for this scenario.
   • Outbound communication: In this case, the Driver defines the device to which it needs to connect. The communication is outbound, from the Driver to the device (the device is a “pull” device). In a typical use case, the Scheduled Device adheres to this process.

2. The number of telemetry sources:

   In a scenario where multiple similar devices need to be connected to the Driver (and it would be time consuming to define configurations for each device), a Receptor Device would very likely be the best option.

3. How registration, authentication and authorisation should be handled

   • Registration: The manner in which registration packets are handled will dictate the best Device suitable for the application. If it is more convenient to configure all the Device’s properties in the configuration file, a Scheduled Device can be chosen. If the developer wants more control when it comes to building meta packets for the Device, a Receptor Device could be a better option.
   • Authentication: The manner in which credentials are used to authenticate a device with the system. With Scheduled Devices, for example, your property mappings will include a username and password that can authenticate with the system. With Receptor Devices, authentication can be handled in the V-Raptor portal.
   • Authorisation: This handles user permissions. With Receptor Devices, this process is also handled in the V-Raptor Portal.

Device Templates available in the Template include:

• Receptor Device Template
• Scheduled Device Template
• Scheduled Receptor Device Template

The sections below will briefly describe each relevant template. The sections that follow will show the user how to install, run, and set up a Driver with a Receptor Device template.

Self-Executing Device templates are also available in the Driver SDK template package. The template will be discussed in advanced topics related to the Driver SDK but has been left out of the introduction guide, since understanding the other templates is more than sufficient to help the user easily set up and run a Driver.

Receptor Device

When to choose a Receptor Device Template: Typical Use Case

Receptor Devices generally support applications where external telemetry sources push data to the V-Raptor (inbound communication).

A Receptor Device Template:

• Has one or more external telemetry sources that will push data to the Device, either directly or through a subscription service.
• Does not need configured property mappings.
• Has 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.

Driver Characteristics with Receptor Device:

• Push device.
• Does not run on a schedule.
• Multiple external telemetry sources per Device.
• Meta requests sent manually.
• Telemetry requests sent manually.

Device templates are available for users to quickly start up applications and send telemetry to Commander. The characteristics listed above provide a general indication of a typical use case for a Receptor Device. Receptor Devices are not limited to these features and can be configured to also have (for example) property mappings if the application requires this.

Scheduled Device

When to choose a Scheduled Device Template: Typical Use Case

Scheduled Devices generally support applications with pull devices, and execute on a scheduled basis.

The template provides a framework for individual Devices to set configurations that represent specific physical devices (external telemetry sources). This method configures both the device’s characteristics (properties), as well as how often it sends data.

Driver Characteristics with Scheduled Device:

• Pull device.
• Runs on a schedule.
• Has out-of-the-box configured Property Mappings. Scheduled Devices generally define the registration packet through the Devices Options (configuration) file.
• Limits external telemetry sources to one source per Device.
• Meta requests sent automatically.
• Telemetry requests sent automatically.

In summary, a Scheduled Device Template is typically used when:

• The user needs to extract telemetry from one or more external telemetry sources on a scheduled basis.
• The application requires configured Property Mappings. Although a Scheduled Device can be configured without property mappings, it is one of the Device templates that provides boilerplate code for this feature, making it easier to use with applications that would best suit this type of setup.
• Each configured Device communicates with exactly one external telemetry source. In other words, the Driver is able to communicate with multiple external telemetry sources using Scheduled Device Interfaces, however each Interface can only represent one physical device.
• The meta and telemetry sent from each configured Device has the same Device Name, Device Type, Group Name and Gateway Id. These values are defined in in the Device’s configuration file (e.g. “DevicesOptions.json”, in the “Devices” section).

Scheduled Receptor Device

When to choose a Scheduled Receptor Device Template: Typical Use Case

Typical use cases where this type of Device is used include:

• Location tracking, where the Driver is scheduled to execute every second (for example) but data should only be triggered to send once people have moved.
• Cases where the physical device is streaming live data to the Driver, but the Driver only sends data every 30 seconds (for example) to aggregate data and lessen the load sent to Commander.

Driver Characteristics with Scheduled Receptor Device:

• Pull device.
• Runs on a 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 manually.
• Telemetry requests sent manually.

Device Configuration Manager

Device Configuration Manger (or Device Manager) is an SDK service that uses the Devices configuration file to find and instantiate all Devices in the Driver. Device Manager can run one or more Devices at the same time.

Device Manager finds Devices to instantiate through “Device Binding”. In the configuration file, each Device that needs to be instantiated when the Driver executes will have a “DeviceType” property which defines the alias/pseudonym that lets Device Manager bind the Device to the root composition file.

Files that are important in this process are:

• DevicesOptions.json (Devices configuration file).
• HostBuilderExtensions.cs (where Device Manager Builder links Devices to the root composition file).

1. Devices Configuration file

   Device Manager uses the Device configuration file to find and apply Devices that need to be instantiated by the Driver. In the SDK Template it is generally called DevicesOptions.json. Inside this file, the “Devices” section will look something like this:

            {
              "Devices": {
                "DefaultProperties": {
                  "DeviceType": "DefaultProperties",
                  "GroupName": "driver_demoDevices",
                  "PropertyMaps": {
                    "Prop1": {
                      "DataType": "double"
                    },
                    "Prop2": {
                      "DataType": "int"
                    }
                  }
                },
                "DemoScheduledDevice": {
                  "Enabled": true,
                  "DeviceType": "Scheduleddriver_demo",
                  "PropertiesDeviceName": "DefaultProperties",
                  "Debug": true, 
                  "OtherProperties": "here"
                },
                "DemoSelfExecutingDevice": {
                  "Enabled": true,
                  "DeviceType": "SelfExecutingdriver_demo",
                  "PropertiesDeviceName": "DefaultProperties",
                  "Debug": true,
                  "OtherProperties": "here"
                },
                "DemoReceptorDevice": {
                  "Enabled": true,
                  "DeviceType": "Receptordriver_demo",
                  "Debug": true,
                  "OtherProperties": "here"
                },
                "DemoScheduledReceptorDevice": {
                  "Enabled": true,
                  "DeviceType": "ScheduledReceptordriver_demo",
                  "Debug": true,
                  "OtherProperties":  "here" 
                } 
              }
            }
   

   In the code sample above, the “DeviceType” placeholder is automatically defined in the Template as the type of Device (for example, Receptor Device), followed by the Device Name provided when the SDK was installed. “DeviceType” can be changed to whatever the user needs it to be, provided it is consistent across all the files that Device Manager uses to instantiate the Device in the Driver (for Device Binding).

2. HostBuilderExtensions.cs file

   The “DeviceType” becomes the pseudonym used in the HostBuilderExtensions.cs file (which is executed in the root composition file, Project.cs):

        public static class HostBuilderExtensions
             {
                 /// <summary>
                 /// The Default Properties device name
                 /// </summary>
                 public const string DefaultPropertiesDeviceName = "DefaultProperties";
   
                 /// <summary>
                 /// The Scheduled Driverdriver_demo device name
                 /// </summary>
                 public const string ScheduledDriverdriver_demoDeviceName = "ScheduledDriverdriver_demo";
   
                 /// <summary>
                 /// The Self Executing Driverdriver_demo device name
                 /// </summary>
                 public const string SelfExecutingDriverdriver_demoDeviceName = "SelfExecutingDriverdriver_demo";
   
                 /// <summary>
                 /// The Receptor Driverdriver_demo device name
                 /// </summary>
                 public const string ReceptorDriverdriver_demoDeviceName = "ReceptorDriverdriver_demo";
   
                 /// <summary>
                 /// The Receptor Driverdriver_demo device name
                 /// </summary>
                 public const string ScheduledReceptorDriverdriver_demoDeviceName = "ScheduledReceptorDriverdriver_demo";
   
                 .....
            }
   

DeviceType for Device Binding can be customised according to the application’s requirements, provided it stay consistent across all relevant files and it links to the correct Device Interface.

Special Use Case: Device Manager and REST Controllers

Some physical devices (external telemetry sources) use APIs to send meta and telemetry from the device to the Driver. In these cases, a REST Controller needs to be configured when building the telemetry packet so that the Driver can receive data from these sources.

Device Manager is the SDK service/module that “links” the REST Controller to the Device Interface. The REST Controller:

• Receives data from the external telemetry sources.
• Pulls in the Device Interface’s name (“Device Name”) that is found in the DevicesOptions.json file (the Device Configuration file).
• Calls on Device Manager to retrieve the instance of that specific Device Interface in the Driver.
• Calls a method (i.e. process the data packet being received) on that Device.

This guide’s first use case includes a REST Controller. An example of a configured telemetry packet with a REST Controller will be provided in the Sending Telemetry section.

Deleting Devices

Once a Device has been chosen, Devices not being used in the application need to be deleted.

Where to delete Devices:

1. Delete both the Concrete Device and Device Options files:

   In the example below, both the Scheduled Device and Scheduled Device Options files are highlighted. Depending on which template needs to be deleted, ensure that both the Device and Device Options files in this section are deleted.

   

   Figure 1 - Delete Device and DeviceOptions files

2. Delete both Abstraction (Interface) Device and Device Options files:

   In the example below, under “Abstractions” the Interface files of the Scheduled Device and Scheduled Device Options are highlighted. Depending on which template needs to be deleted, ensure that both the Device and Device Options files in this section are deleted.

   

   Figure 2 - Delete IDevice and IDeviceOptions files

3. Delete references to the files in the HostBuilderExtensions.cs file:

   If the Scheduled Device needs to be deleted (for example), then the following highlighted sections in the HostBuilderExtensions file need to be deleted:

   

   Figure 3 - Delete Devices in HostBuilderExtensions file (1)

   

   Figure 4 - Delete Devices in HostBuilderExtensions file (2)

4. Delete references to Devices in the Devices configuration file (DevicesOptions.json):

   The example below highlights the section that will need to be deleted if the Scheduled Device template needs to be deleted from the SDK.

   

   Figure 5 - Delete Devices in DevicesOptions file