The V-Raptor Microservice - Overview
Dec 7 2023 at 12:00 AM
How the V-Raptor Works
The V-Raptor is comprised of microservices that work together to process and transmit telemetry values from physical devices to Commander. This process generally adheres to the following order:
Figure 1 - V-Raptor Services
- Physical devices (external telemetry sources) provide telemetry values to the Driver (shown as the Device Integration Service in the image above).
- The Driver sends these values (as telemetry requests) to the Collector Service.
- The Collector Service keeps a local copy of the current telemetry values received from each physical device.
- As telemetry is received, it is forwarded to the Commander interface service for upload to Commander.
- The Identity Service is used to provide authentication to validate requests received by each Service.
- V-Raptor also implements Data Storage in Transit (DSIT) to ensure that no request is lost in the event of a Service crash or power failure.
This quick start guide will focus on the Driver Service. This microservice integrates Devices and provides an interface for physical devices. The Driver can be installed using an SDK package template, which provides all the boilerplate code necessary to quickly set up, configure and run Device Interfaces that represent physical devices and their telemetry.
Driver Service, Devices and Device Templates
The following section will briefly define the main components in the Driver SDK:
Raptor Device Service (raptordeviceservice)
The Raptor Device Service (raptordeviceservice) is the name of the SDK template that contains boilerplate code that makes Driver setup and configuration fast and easy. When installing the SDK, the user will choose the raptordeviceservice template from the list of template options in the DotNet package.
Services (microservices) and SDK services
The microservices that work together in V-Raptor include:
- Driver
- Collector
- Identity
- Cloud
The guide provided in the pages that follow will focus on how to use the Driver’s SDK template. The SDK template is comprised of a collection of SDK services that provides a support structure for the Driver microservice’s functionality. The SDK uses these services to set up a basic application without the user needing to configure the building blocks manually.
Physical devices
Physical devices (also referred to as devices or external telemetry sources) communicate with the V-Raptor to send telemetry and meta data to Commander.
Drivers and Devices (Device Interfaces)
The Driver is a microservice written using an SDK template. It is the microservice in V-Raptor that integrates Devices and sends telemetry to the Collector Service.
The digital representation of external telemetry sources (physical devices) in a Driver microservice is called a Device (or Device Interface). The Driver microservice communicates with physical devices by creating instances of one or more Devices or Device Interfaces.
Drivers run on the V-Raptor to translate a physical device’s Protocol so that telemetry can be processed and transmitted to Commander. For example, a Driver could be configured to listen to TCP connections from the physical device and decode the messages using the Protocol definition configured in the Device (or Device Interface).
Drivers can have multiple Devices. However, Drivers are generally created for specific Protocols or Vendors, i.e. a Device can be written for one Protocol which can be applied to all physical devices that use that Protocol (for example, a Driver created for physical devices that use a DLMS Protocol to communicate).
Abstract and Concrete Devices
When building the Driver, it is best practice to separate Abstract Devices (Interface and Interface Options files) from Concrete Devices and Options:
Figure 2 - Devices File Structure in SDK Template
In the image above, the Driver is divided into Concrete Devices and Abstractions (Interfaces). Each Concrete and Abstract Device also has a corresponding Options file.
Note that in this introduction guide, generally when the article refers to a Device Interface, it is referring to the virtual representation of the physical device. It refers to the Concrete class file where the Device Template is extended for a specific use case. This guide will be clear about when it is referring to the Abstract Interface file. Device Driver Templates
Device Driver Templates are templates in the SDK with boilerplate code that provides a basic framework to construct certain types of Devices. These templates are included and extended in Devices (Device Interfaces) so that the user can configure their Devices quickly, easily, and according to a certain standard.
These templates include:
- Receptor Device Template
- Scheduled Device Template
- Scheduled Receptor Device Driver Template
Once an SDK template package is installed, the full solution will have boilerplate code for each type of template. These files can be found here:
Figure 3 - Device Templates
To configure the Driver, the user will choose the templates necessary for the required application, and delete the templates that are unnecessary. This process will be discussed in Select Device Templates.
Naming Conventions
There are a few concepts/components in the SDK that could refer to different aspects of the Raptor Device Service, depending on the context. The following naming conventions will help to clarify some concepts:
Concept | Naming Convention |
---|---|
Microservice | Service (uppercase S) / microservice (lowercase m, when not at the beginning of the sentence) |
SDK service | SDK service / Module (module) / Software service (software service) / service (lowercase s) |
Device Interface | Device (uppercase D) |
Physical Device | physical device / device |
Raptor Device Service | Raptor Device Service (sentence case) |
Driver microservice | Driver / Device Integration Service (sentence case) / Driver Service (sentence case) |
Collector microservice | Collector / Collector Service (sentence case) |
Identity microservice | Identity / Identity Service (sentence case) |
Cloud microservice | Cloud Service (sentence case) |
Device Driver Template | Device Templates (sentence case) / Device templates (capital D) |
Meta | meta (lowercase m) / Meta (uppercase M) |
Telemetry | telemetry (lowercase ) / Telemetry (uppercase) |
Receptor Device Driver Template | Receptor Device / Receptor Device Template (sentence case) |
Scheduled Device Driver Template | Scheduled Device / Scheduled Device Template (sentence case) |
Scheduled Receptor Device Template | Scheduled Receptor Device / Scheduled Receptor Device Template (sentence case) |
Virtual Raptor | Virtual Raptor / V-Raptor |