Device SDK Required Functionality
Overview
This document sets out the required functionality of a Device SDK other than the implementation of its REST API (see ADR 0011) and the Dynamic Discovery mechanism (see Discovery).
This functionality is categorised into three areas - actions required at startup, configuration options to be supported, and support for push-style event generation.
Startup
When the device service is started, in addition to any actions required to support functionality defined elsewhere, the SDK must:
- Manage the device service's registration in metadata
- Provide initialization information to the protocol-specific implementation
Registration
The core-metadata service maintains an extent of device service registrations so that it may route requests relating to particular devices to the correct device service. The SDK should create (on first run) or update its record appropriately. Device service registrations contain the following fields:
Name
- the name of the device serviceDescription
- an optional brief description of the serviceLabels
- optional string labelsBaseAddress
- URL of the base of the service's REST API
The default device service Name
is to be hardcoded into every device service
implementation. A suffix may be added to this name at runtime by means of
commandline option or environment variable. Service names must be unique in a
particular EdgeX instance; the suffix mechanism allows for running multiple
instances of a given device service.
The Description
and Labels
are configured in the [Service]
section of the
device service configuration.
BaseAddress
may be constructed using the [Service]/Host
and [Service]/Port
entries in the device service configuration.
Initialization
During startup the SDK must supply to the implementation that part of the
service configuration which is specific to the implementation. This
configuration is held in the Driver
section of the configuration file or
registry.
The SDK must also supply a logging facility at this stage. This facility should
by default emit logs locally (configurable to file or to stdout) but instead
should use the optional logging service if the configuration element
Logging/EnableRemote
is set true
. Note: the logging service is deprecated
and support for it will be removed in EdgeX v2.0
The implementation on receipt of its configuration should perform any necessary initialization of its own. It may return an error in the event of unrecoverable problems, this should cause the service startup itself to fail.
Configuration
Configuration should be supported by the SDK, in accordance with ADR 0005
Commandline processing
The SDK should handle commandline processing on behalf of the device service.
In addition to the common EdgeX service options, the --instance
/ -i
flag
should be supported. This specifies a suffix to append to the device service
name.
Environment variables
The SDK should also handle environment variables. In addition to the common
EdgeX variables, EDGEX_INSTANCE_NAME
should if set override the --instance
setting.
Configuration file and Registry
The SDK should use (or for non-Go implementations, re-implement) the standard mechanisms for obtaining configuration from a file or registry.
The configuration parameters to be supported are:
Service section
Option | Type | Notes |
---|---|---|
Host | String | This is the hostname to use when registering the service in core-metadata. As such it is used by other services to connect to the device service, and therefore must be resolvable by other services in the EdgeX deployment. |
Port | Int | Port on which to accept the device service's REST API. The assigned port for experimental / in-development device services is 49999. |
Timeout | Int | Time (in milliseconds) to wait between attempts to contact core-data and core-metadata when starting up. |
ConnectRetries | Int | Number of times to attempt to contact core-data and core-metadata when starting up. |
StartupMsg | String | Message to log on successful startup. |
CheckInterval | String | The checking interval to request if registering with Consul. Consul will ping the service at this interval to monitor its liveliness. |
ServerBindAddr | String | The interface on which the service's REST server should listen. By default the server is to listen on the interface to which the Host option resolves. A value of 0.0.0.0 means listen on all available interfaces. |
Clients section
Defines the endpoints for other microservices in an EdgeX system. Not required when using Registry.
Data
Option | Type | Notes |
---|---|---|
Host | String | Hostname on which to contact the core-data service. |
Port | Int | Port on which to contact the core-data service. |
Metadata
Option | Type | Notes |
---|---|---|
Host | String | Hostname on which to contact the core-metadata service. |
Port | Int | Port on which to contact the core-metadata service. |
Device section
Option | Type | Notes |
---|---|---|
DataTransform | Bool | For enabling/disabling transformations on data between the device and EdgeX. Defaults to true (enabled). |
Discovery/Enabled | Bool | For enabling/disabling device discovery. Defaults to true (enabled). |
Discovery/Interval | Int | Time between automatic discovery runs, in seconds. Defaults to zero (do not run discovery automatically). |
MaxCmdOps | Int | Defines the maximum number of resource operations that can be sent to the driver in a single command. |
MaxCmdResultLen | Int | Maximum string length for command results returned from the driver. |
UpdateLastConnected | Bool | If true, update the LastConnected attribute of a device whenever it is successfully accessed (read or write). Defaults to false. |
Logging section
Option | Type | Notes |
---|---|---|
LogLevel | String | Sets the logging level. Available settings in order of increasing severity are: TRACE , DEBUG , INFO , WARNING , ERROR . |
Driver section
This section is for options specific to the protocol driver. Any configuration specified here will be passed to the driver implementation during initialization.
Push Events
The SDK should implement methods for generating Events other than on receipt of device GET requests. The AutoEvent mechanism provides for generating Events at fixed intervals. The asynchronous event queue enables the device service to generate events at arbitrary times, according to implementation-specific logic.
AutoEvents
Each device may have as part of its definition in Metadata a number of AutoEvents
associated with it. An AutoEvent
has the following fields:
- resource: the name of a deviceResource or deviceCommand indicating what to read.
- frequency: a string indicating the time to wait between reading events, expressed as an integer followed by units of ms, s, m or h.
- onchange: a boolean: if set to true, only generate new events if one or more of the contained readings has changed since the last event.
The device SDK should schedule device readings from the implementation according to these AutoEvent
defininitions. It should use the same logic as it would if the readings were being requested via REST.
Asynchronous Event Queue
The SDK should provide a mechanism whereby the implementation may submit device readings at any time without blocking. This may be done in a manner appropriate to the implementation language, eg the Go SDK provides a channel on which readings may be pushed, the C SDK provides a function which submits readings to a workqueue.