Device Aliases
Plugin devices each have an ID associated with them, which is generated by the SDK deterministically. These IDs are computed hashes and are not a human-friendly means to identify or reference a device manually.
To make this easier, the Synse SDK allows devices to have an alias associated with it. A device alias is just a string which should be human readable and provides a meaningful way to reference the device, as an alternative to the device ID. In order to ensure that a device alias only references a single device, the aliases must also be unique. While there are some safeguards/checks built into the SDK, it is the responsibility of the plugin configurer to ensure that there are no alias collisions.
A device alias can be used in place of a device ID for all Synse operations. Device aliases are defined in the device configuration. There are two ways that an alias can be specified: explicitly, or via template.
Explict Alias¶
An explicit alias is just a string which is not processed any further. For example:
version: 3 devices: - type: example-device instances: - info: example device instance 1 alias: name: device-1
This example configuration defines device-1
as the device's explicit alias.
Templated Alias¶
The device alias may also be defined with a Go template string.
version: 3 devices: - type: example-device instances: - info: example device instance 1 context: partNumber: abc123 alias: template: 'device-{{ .Device.Type }}-{{ ctx "partNumber" }}-1'
In the above example, the alias would render out to "device-example-device-abc123-1"
.
An AliasContext
provides the context for the template. From it, the device information and plugin information
can be referenced.
Alias Context
Key | Description |
---|---|
.Meta.Name |
The name of the plugin. |
.Meta.Maintainer |
The plugin maintainer. |
.Meta.Description |
The description of the plugin. |
.Meta.VCS |
The VCS string for the plugin. |
.Device.Type |
The type of the device. |
.Device.Info |
The device's configured human-readable info string. |
.Device.Handler |
The name of the device's device handler. |
.Device.SortIndex |
The optional custom sort index for the device. |
.Device.WriteTimeout |
The duration string for the device write timeout. |
.Device.Output |
The name of the optionally configured device output. |
Additionally, the SDK provides some simple template functions:
Function | Description | Example |
---|---|---|
env |
Get a value from the environment. | {{ env "PLUGIN_HOSTNAME" }} |
ctx |
Get a value from the device's configured context . |
{{ ctx "manufacturer" }} |