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 Configuration: Configuration for the device instances that the plugin should interface with and manage.
- Output Type Configuration: Configuration for the supported reading outputs for the supported devices.
Plugin Configuration¶
Plugins are configured from a YAML file that defines how the plugin should operate. Most plugin configurations have sane default values, so it may not even be necessary to specify your own plugin configuration.
The plugin config file must be named config.{yml|yaml}
.
Config Policies¶
The following config policies relate to plugin configuration.
- PluginConfigFileOptional (default)
- PluginConfigFileRequired
- PluginConfigFileProhibited
Config Locations¶
The default locations for the plugin configuration (in order of evaluation) are:
$PWD
$HOME/.synse/plugin
/etc/synse/plugin
Where $PWD
(or .
) is the directory in which the plugin binary is being run from.
A non-default location can be used by setting the PLUGIN_CONFIG
environment variable
to either the directory containing the config file, or to the config file itself.
PLUGIN_CONFIG=/tmp/plugin/config.yml
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
debug: | Enables debug logging. debug: true
|
||||||||||||||||||||||||
network: | Network settings for the gRPC server. If this is not specified, it will default to a type of tcp with an address of localhost:5001.
|
||||||||||||||||||||||||
settings: | Settings for how the plugin should run, particularly the read/write behavior.
|
||||||||||||||||||||||||
dynamicRegistration: | |||||||||||||||||||||||||
Settings and configurations for the dynamic registration of devices by a plugin.
|
|||||||||||||||||||||||||
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.
|
||||||||||||||||||||||||
health: | Configuration for plugin health checks.
|
||||||||||||||||||||||||
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. |
Example¶
Below is an example of a plugin configuration.
version: 1.0
debug: true
network:
type: tcp
address: ":5001"
settings:
mode: parallel
read:
interval: 1s
write:
interval: 2s
Device Configuration¶
Device configurations define the devices that a plugin will interface with and expose to Synse Server.
All device configs are unified into a single config when the plugin reads them in and validates them. Device configurations can be specified in a single file, or across multiple files. The file name does not matter, but it must have a .yml or .yaml extension.
Config Policies¶
The following config policies relate to device configuration.
For file configuration:
- DeviceConfigFileOptional
- DeviceConfigFileRequired (default)
- DeviceConfigFileProhibited
For dynamic configuration:
- DeviceConfigDynamicOptional (default)
- DeviceConfigDynamicRequired
- DeviceConfigDynamicProhibited
Config Locations¶
The default locations for the device configuration(s) (in order of evaluation) are:
./config/device
/etc/synse/plugin/config/device
A non-default location can be used by setting the PLUGIN_DEVICE_CONFIG
environment variable
to either the directory containing the config file, or to the config file itself.
PLUGIN_DEVICE_CONFIG=/tmp/device/config.yml
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
locations: | A list of location definitions. Device instances specify their location by referencing the locations defined here. locations:
- name: r1b1
rack:
fromEnv: RACK
board:
name: board1
|
||||||||||||||||||||
devices: | A list of device kinds, where each item in the list is referenced as devices:
- name: temperature
metadata:
model: example-temp
instances:
- channel: "0014"
location: r1b1
info: Temperature Device 1
|
Output Type Config Options
type: | The name of the output type that describes the output format for a device reading output. type: foo.temperature
|
---|---|
info: | Any info that can be used to provide a short human-understandable label, description, or summary of the reading output. This is optional. info: On-board temperature reading value
|
data: | A map where the key is a string and the value is anything. This data contains any protocol/output specific configuration associated with the device output. Most device outputs will not need their own configuration data specified here, in which case this can be left empty. It is the responsibility of the plugin to handle these values correctly. data:
channel: 3
port: /dev/ttyUSB0
|
Device Instance Config Options
info: | A short human-understandable label, description, or summary of the device instance. While this is not required, it is recommended to used, as it makes identifying devices much easier. info: top right temperature sensor
|
---|---|
location: | The location of the device. This should be a string that references the location: r1b1
|
data: | Any protocol/device specific configuration for this device instance. This will often be data used to communicate with the device. It is the responsibility of the plugin to handle these values correctly. data:
channel: 5
port: /dev/ttyUSB0
id: 14
|
outputs: | A list of the output types for the readings that this device supports. A device instance will need to have at least one output type, but can have more. It can inherit output types from its device kind. For more, see the section on device outputs, above. outputs:
- type: foo.temperature
- type: foo.humidity
|
disableOutputInheritance: | |
A flag that, when set, will prevent this instance from inheriting output types from its parent device kind. This is false by default (so it will inherit by default). disableOutputInheritance: true
|
|
handlerName: | The name of a device handler to match to this device instance. By default, a device instance will match with a device handler using the Name field of its device kind. This field can be set to override that behavior and match to a handler with the name specified here. This field is optional. handlerName: foo.bar.something
|
Example¶
Below is an example of a device configuration.
version: 1.0
locations:
- name: r1vec
rack:
name: rack-1
board:
name: vec
devices:
- name: temperature
metadata:
model: example-temp
manufacturer: vaporio
outputs:
- type: temperature
instances:
- info: Example Temperature Sensor 1
location: r1vec
data:
id: 1
- info: Example Temperature Sensor 2
location: r1vec
data:
id: 2
- info: Example Temperature Sensor 3
location: r1vec
data:
id: 3
Output Type Configuration¶
Output type configurations define output types which describe how a device reading should be formatted and adds context info around the reading output. Output type configurations can be specified directly in the code, so they do not need to be set via config file. Since these should not change frequently, it is recommended to define them in-code, but that may not work well for all plugins, so the option to define them via config exists.
Config Policies¶
The following config policies relate to output type configuration.
- TypeConfigFileOptional (default)
- TypeConfigFileRequired
- TypeConfigFileProhibited
Config Locations¶
The default locations for the output type configuration(s) (in order of evaluation) are:
./config/type
/etc/synse/plugin/config/type
A non-default location can be used by setting the PLUGIN_TYPE_CONFIG
environment variable
to either the directory containing the config file, or to the config file itself.
PLUGIN_DEVICE_CONFIG=/tmp/type/config.yml
Configuration Options¶
version: | The version of the configuration scheme. version: 1.0
|
||||
---|---|---|---|---|---|
name: | The name of the output type. Output type names should be unique for a plugin. The name can be arbitrarily namespaced. name: foo.temperature
|
||||
precision: | The decimal precision that the reading should be rounded to. This is only applied to readings that provide float values. This specifies the number of decimal places to round to. precision: 3
|
||||
unit: | The unit of reading. unit:
name: millimeters per second
symbol: mm/s
|
||||
scalingFactor: | A factor that the reading value can be multiplied by to get the final output value. This is optional and will be 1 if not specified (e.g. the reading value will not change). This value should resolve to a numeric. Negatives and fractional values are supported. This can be the value itself, e.g. “0.01”, or a mathematical representation of the value, e.g. “1e-2”. scalingFactor: -.4E10
|