Plugin Configuration¶
This page describes the different kinds of configuration a plugin has, and gives examples for each. There are three basic kinds of configuration:
- Plugin Configuration: Configuration for how the plugin should behave.
- Device Prototype: Meta information for a supported device type.
- Device Instance: Instance information for a supported device type.
Device prototype information is relatively static and should not change much. It is considered safe to package it with the plugin, e.g. in a Docker image. The plugin configuration and device instance configuration, however, should be defined on a per-instance basis.
Plugin Configuration¶
The plugin configuration is a YAML file the defines some plugin metainfo and describes how the plugin should operate.
Default Location¶
The default locations for the plugin configuration (in order of evaluation) are:
/etc/synse/plugin
$HOME/.synse/plugin
$PWD
Where $PWD
(or .
) is the directory in which the plugin binary is being run from.
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name: | The name of the plugin. name: example
|
||||||||||||||||||||||||
debug: | Enables debug logging. debug: true
|
||||||||||||||||||||||||
network: | Network settings for the gRPC server.
|
||||||||||||||||||||||||
settings: | Settings for how the plugin should run, particularly the read/write behavior.
|
||||||||||||||||||||||||
auto_enumerate: | The auto-enumeration context for a plugin. This is dependent on the plugin and the device enumeration handler, but in general it can be anything. For more, see Device Enumeration Handler. |
||||||||||||||||||||||||
context: | Configurable context for the plugin. This is generally not used, but is made available as a general map in order to pass values in/around the plugin if needed. |
||||||||||||||||||||||||
limiter: | Configurations for a rate limiter against reads and writes. Some backends may limit interactions, e.g. some HTTP APIs. This configuration allows a limiter to be set up to ensure that a limit is not exceeded.
|
Example¶
Below is a complete, if contrived, example of a plugin configuration.
version: 1.0
name: example
debug: true
network:
type: unix
address: example.sock
settings:
mode: parallel
read:
interval: 1s
write:
interval: 2s
Device Prototype Configuration¶
Prototype configurations define the static meta-info for a given device type. Additionally, they define the expected output scheme for those devices.
Default Location¶
The default location for device instance configurations is
/etc/synse/plugin/config/proto
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
prototypes: | A list of prototype objects.
|
The output configuration is a list of reading types. This is separated from
the <proto>.output
above only to give it more room on the page.
output: | A list of the supported reading outputs for the device.
|
---|
Example¶
Below is a complete, if contrived, example of a device prototype configuration.
version: 1.0
prototypes:
- type: temperature
model: example-temp
manufacturer: Vapor IO
protocol: example
output:
- type: temperature
unit:
name: degrees celsius
symbol: C
precision: 2
range:
min: 0
max: 100
Device Instance Configuration¶
Device instance configurations define the instance-specific configurations for a device. This is often, but not exclusively, the information needed to connect to a device, e.g. an IP address or port. Because device instance configurations should be unique to an instance of a device, parts of these configurations are also used to generate the composite id hash for the device.
Default Location¶
The default location for device instance configurations is
/etc/synse/plugin/config/device
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||||||
---|---|---|---|---|---|---|---|---|---|
locations: | A mapping of location alias to location object. Device instances specify their location by referencing the location alias key. locations:
r1b1:
rack: rack1
board: board1
|
||||||||
devices: | A list of the device instances, where each item in the list is referenced as devices:
- type: temperature
model: example-temp
instances:
- channel: "0014"
location: r1b1
info: Temperature Device 1
|
Example¶
Below is a complete, if contrived, example of a device instance configuration.
version: 1.0
locations:
r1vec:
rack: rack-1
board: vec
devices:
- type: temperature
model: example-temp
instances:
- id: "1"
location: r1vec
info: Example Temperature Sensor 1
- id: "2"
location: r1vec
info: Example Temperature Sensor 2
- id: "3"
location: r1vec
info: Example Temperature Sensor 3
Environment Overrides¶
It may not be convenient to place the configuration files into their default locations, e.g. when testing locally or mounting into a container. Environment overrides exist that allow you to tell the plugin where to look for its configuration.
- PLUGIN_CONFIG : Specifies the directory which contains the plugin configuration
file,
config.yml
. - PLUGIN_DEVICE_CONFIG : Specifies the directory which contains
proto
andconfig
subdirectories that hold the configuration YAMLs for the prototype and instance configurations, respectively. - PLUGIN_PROTO_PATH : Specifies the directory which contains the prototype configuration YAMLs.
- PLUGIN_DEVICE_PATH : Specifies the directory which contains the device instance configuration YAMLs.