Synse Emulator Plugin

A plugin with emulated devices for the Synse platform.

This plugin is designed to be simple and have no dependencies on any backend hardware or protocol. It is meant to be a standalone plugin that can run with Synse Server out of the box allowing you to quickly experiment and develop with Synse Server. It may also serve as an example on how to write plugins of your own.

Getting Started

Getting

You can install the emulator plugin via a release binary or via Docker image

docker pull vaporio/emulator-plugin

If you wish to use a development build, fork and clone the repo and build the plugin from source.

Running

A compose file is included in this repo which provides a basic example of how to run the emulator plugin in conjunction with Synse Server. You may also run the emulator on its own

docker run -d --name emulator -p 5001:5001 vaporio/emulator-plugin

and use the Synse CLI to query the plugin's gRPC API.

The emulator plugin ships with some default built-in device configurations. If you wish to run the plugin with a different set of plugins, be sure to read through the SDK Documentation on configuring plugin devices.

Emulator Plugin Configuration

All devices supported by the emulator plugin return dummy data. State is maintained for most writable devices, so any state that you write should be retrievable via a subsequent read.

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

Device Handlers

Device Handlers are referenced by name.

Name	Description	Outputs	Read	Write	Bulk Read	Listen
airflow	A handler for emulated airflow devices.	`airflow`	✓	✓	✗	✗
energy	A handler for emulated energy devices.	`kilowatt-hour`	✓	✓	✗	✗
fan	A handler for emulated fan devices.	`direction`, `rpm`	✓	✓	✗	✗
fan-multi	A handler for emulated fan devices with multiple RPM readings.	`direction`, `rpm`	✓	✓	✗	✗
humidity	A handler for emulated humidity devices.	`humidity`, `temperature`	✓	✓	✗	✗
led	A handler for emulated LED devices.	`color`, `state`	✓	✓	✗	✗
lock	A handler for emulated lock devices.	`status`	✓	✓	✗	✗
power	A handler for emulated power devices.	`watt`	✓	✓	✗	✗
pressure	A handler for emulated pressure devices.	`pascal`	✓	✓	✗	✗
temperature	A handler for emulated temperature devices.	`temperature`	✓	✓	✗	✗
voltage	A handler for emulated voltage devices.	`voltage`	✓	✓	✗	✗

Write Values

This plugin supports the following values when writing to a device via a handler.

The emulator enables writing on devices where it would generally not otherwise be possible, allowing the user to adjust the reading values and ranges at runtime without having to re-deploy. Handlers set up this way will have the min, max, and current write actions available.

Handler	Write Action	Write Data	Description
airflow	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
energy	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
fan	`speed`	`int`	The speed to set the fan to.
humidity	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
led	`state`	`string`: on, off, blink	The LED power state.
	`color`	`string`	RGB hex color string.
lock	`lock`	-	Lock the door.
	`unlock`	-	Unlock the door.
	`pulseUnlock`	-	Unlock the door for a short time, then lock it again.
power	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
pressure	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
temperature	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.
voltage	`min`	`int`	The minimum bound for readings to be generated within.
	`max`	`int`	The maximum bound for readings to be generated within.
	`current`	`int`	The static current reading value.

Device Configurations

In addition to allowing values to be set via writing to devices, the behaviors/data ranges for device readings may also be configured in the device configuration YAML for certain devices. These options should be set under a device's data configuration, e.g.

version: 3
devices:
  - type: temperature
    context:
      model: emul8-temp
    instances:
      - info: Synse Temperature Sensor 1
        data:
          id: 1
          min: 20
          max: 40

The table below describes the supported configuration values for each type. None of the values specified below are required to be set. If omitted, the plugin falls back on sane defaults. Definitions for the settings follow:

min: The lower bound for a random walk. The walk will not subceed this value.
max: The upper bound for a random walk. The walk will not exceed this value.
step: The maximum size that a random walk may step by. For each iteration, the step is randomly chosen between this max step size and 0.
seed: The starting value for the device.

Device Type	Setting	Type	Default
airflow	`min`	int	-100
	`max`	int	100
	`step`	int	4
current	`min`	int	0
	`max`	int	30
	`step`	int	4
energy	`min`	int	0
	`max`	int	100000
fan	`seed`	int	0
frequency	`min`	int	0
	`max`	int	60
	`step`	int	4
humidity	`min`	int	0
	`max`	int	100
	`step`	int	4
power	`min`	int	1000
	`max`	int	3000
	`step`	int	4
pressure	`min`	int	-5
	`max`	int	5
	`step`	int	4
temperature	`min`	int	0
	`max`	int	100
	`step`	int	4
voltage	`min`	int	100
	`max`	int	500
	`step`	int	0

Compatibility

Below is a table describing the compatibility of plugin versions with Synse platform versions.

	Synse v2	Synse v3
plugin v1.x	✗	✗
plugin v2.x	✓	✗
plugin v3.x	✗	✓

Troubleshooting

Debugging

The plugin can be run in debug mode for additional logging. This is done by:

Setting the debug option to true in the plugin configuration YAML (config.yml)
```
debug: true
```
Passing the --debug flag when running the binary/image
```
docker run vaporio/emulator-plugin --debug
```
Running the image with the PLUGIN_DEBUG environment variable set to true
```
docker run -e PLUGIN_DEBUG=true vaporio/emulator-plugin
```

Developing

A development/debug Dockerfile is provided in the project repository to enable building image which may be useful when developing or debugging a plugin. Unlike the slim scratch-based production image, the development image uses an ubuntu base, bringing with it all the standard command line tools one would expect. To build a development image:

make docker-dev

The built image will be tagged using the format dev-{COMMIT}, where COMMIT is the short commit for the repository at the time. This image is not published as part of the CI pipeline, but those with access to the Docker Hub repo may publish manually.

Contributing / Reporting

If you experience a bug, would like to ask a question, or request a feature, open a new issue and provide as much context as possible. All contributions, questions, and feedback are welcomed and appreciated.

License

The Synse Emulator Plugin is licensed under GPLv3. See LICENSE for more info.

vapor-ware/synse-emulator-plugin