Reading Outputs

Outputs provide definitions of the metadata associated with device readings. They provide information about the type of reading, what the precision of the value, and the unit of the reading.

All readings must be associated with an output -- without the context that an Output provides, the reading is effectively just an arbitrary value. Outputs may be set in a Device Handler (if the handler is device-specific), or in the device configuration, if the handler is general-purpose.

A number of built-in Outputs are provided by the SDK are a good starting point for plugin, but will not be enough for all devices/plugins. Custom Outputs may be registered with the plugin (see below for an example). It is important to note that since Outputs are referenced by name, their names must be unique. If an Output is defined which conflicts with an existing one (whether custom or built-in), the SDK will return an error.

Example

Below is an example of a simple output type definition for a custom "time" reading, as well as how it is registered to the plugin. See the Device Handlers section for an example of how it can be used.

outputs.go

package main

import (
    "github.com/vapor-ware/synse-sdk/sdk/output"
)

var (
    Time = output.Output{
        Name:      "time",
        Type:      "timestamp",
    }
)

main.go

package main

import (
    "log"

    "github.com/vapor-ware/synse-sdk/sdk"
)

func main() {
    // Create a new plugin instance
    plugin, err := sdk.NewPlugin()
    if err != nil {
        log.Fatal(err)
    }

    // Register custom outputs
    err = plugin.RegisterOutputs(
        &Time,
    )
    if err != nil {
        log.Fatal(err)
    }

    // Run the plugin
    if err := plugin.Run(); err != nil {
        log.Fatal(err)
    }
}

Built-ins

The Synse plugin SDK provides a number of built-in reading output types with sane values which can be used by any plugin. This "core" set of outputs provides a good foundation to describe what data plugins can support, but individual plugin implementations are free to define their own outputs, as shown above.

Below is a table describing the outputs built-in to the SDK. If you are interested in adding more built-in outputs, feel free to open a pull request. In the table below, a value of - indicates no value.

Name Type Precision Unit
color color - -
direction direction - -
electric-current current 3 Ampere (A)
electric-resistance resistance 2 Ohm (Ω)
frequency frequency 2 Hertz (Hz)
humidity humidity 2 Percent humidity (%)
kilojoule energy 3 Kilojoule (kJ)
kilowatt-hour energy 3 Kilowatt-hour (kWh)
microseconds duration 6 Microseconds (µs)
nanoseconds duration 6 Nanoseconds (ns)
pascal pressure 3 Pascal (Pa)
percentage percentage - Percent (%)
psi pressure 3 Pounds per square inch (PSI)
rpm frequency 2 Revolutions per minute (RPM)
seconds duration 3 Seconds (s)
state state - -
status status - -
switch state 1 -
temperature temperature 2 Celsius (C)
velocity velocity 3 Meters per second (m/s)
voltage voltage 5 Volt (V)
volt-second flux 3 Volt second (Vs)
watt power 3 Watt (W)
weber flux 3 Weber (Wb)

Documenting Outputs

Whether a plugin uses built-in outputs, custom outputs, or a mix of both, it is helpful to plugin users to document which outputs that plugin uses. There is no set way that outputs should be defined, but an example of how they could be defined is provided below for reference (taken from the Synse emulator plugin).

### Outputs

Outputs are referenced by name. A single device may have more than one instance
of an output type. A value of `-` in the table below indicates that there is no value
set for that field. The *custom* section describes outputs which this plugin defines
while the *built-in* section describes outputs this plugin uses which are built-in to
the SDK.

**Custom**

| Name    | Description                                      | Unit  | Type    | Precision |
| ------- | ------------------------------------------------ | :---: | ------- | :-------: |
| airflow | A measure of airflow, in millimeters per second. | mm/s  | `speed` | 3         |

**Built-in**

| Name          | Description                                        | Unit  | Type          | Precision |
| ------------- | -------------------------------------------------- | :---: | ------------- | :-------: |
| color         | A color, represented as an RGB string.             | -     | `color`       | -         |
| direction     | A measure of directionality.                       | -     | `direction`   | -         |
| humidity      | A measure of humidity, as a percentage.            | %     | `humidity`    | 2         |
| kilowatt-hour | A measure of energy, in kilowatt-hours.            | kWh   | `energy`      | 3         |
| pascal        | A measure of pressure, in Pascals.                 | Pa    | `pressure`    | 3         |
| rpm           | A measure of frequency, in revolutions per minute. | RPM   | `frequency`   | 2         |
| state         | A generic description of state.                    | -     | `state`       | -         |
| status        | A generic description of status.                   | -     | `status`      | -         |
| temperature   | A measure of temperature, in degrees Celsius.      | C     | `temperature` | 2         |
| voltage       | A measure of voltage, in Volts.                    | V     | `voltage`     | 5         |
| watt          | A measure of power, in Watts.                      | W     | `power`       | 3         |