{"id":23469902,"url":"https://github.com/vapor-ware/synse-emulator-plugin","last_synced_at":"2025-04-14T16:33:47.045Z","repository":{"id":31609988,"uuid":"119695700","full_name":"vapor-ware/synse-emulator-plugin","owner":"vapor-ware","description":"Emulator plugin for Synse","archived":false,"fork":false,"pushed_at":"2023-08-04T05:27:10.000Z","size":409,"stargazers_count":3,"open_issues_count":2,"forks_count":3,"subscribers_count":8,"default_branch":"develop","last_synced_at":"2025-03-21T22:03:07.818Z","etag":null,"topics":["emulator","plugin","synse","synse-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vapor-ware.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-31T14:09:56.000Z","updated_at":"2022-12-14T22:47:38.000Z","dependencies_parsed_at":"2024-06-19T09:52:54.266Z","dependency_job_id":"91f51519-de31-41ab-81e8-b4502d19f71f","html_url":"https://github.com/vapor-ware/synse-emulator-plugin","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-ware%2Fsynse-emulator-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-ware%2Fsynse-emulator-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-ware%2Fsynse-emulator-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vapor-ware%2Fsynse-emulator-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vapor-ware","download_url":"https://codeload.github.com/vapor-ware/synse-emulator-plugin/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248916599,"owners_count":21182836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emulator","plugin","synse","synse-plugin"],"created_at":"2024-12-24T15:36:48.840Z","updated_at":"2025-04-14T16:33:47.021Z","avatar_url":"https://github.com/vapor-ware.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://github.com/vapor-ware/synse-emulator-plugin/workflows/build/badge.svg)](https://github.com/vapor-ware/synse-emulator-plugin/actions)\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fvapor-ware%2Fsynse-emulator-plugin.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fvapor-ware%2Fsynse-emulator-plugin?ref=badge_shield)\n\n# Synse Emulator Plugin\n\nA plugin with emulated devices for the Synse platform.\n\nThis plugin is designed to be simple and have no dependencies on any backend hardware\nor protocol. It is meant to be a standalone plugin that can run with Synse Server\nout of the box allowing you to quickly experiment and develop with Synse Server. It\nmay also serve as an example on how to write plugins of your own.\n\n## Getting Started\n\n### Getting\n\nYou can install the emulator plugin via a [release](https://github.com/vapor-ware/synse-emulator-plugin/releases)\nbinary or via Docker image\n\n```\ndocker pull vaporio/emulator-plugin\n```\n\nIf you wish to use a development build, fork and clone the repo and build the plugin\nfrom source.\n\n### Running\n\nA [compose file](docker-compose.yml) is included in this repo which provides a basic example of\nhow to run the emulator plugin in conjunction with Synse Server. You may also run the emulator on\nits own\n\n```\ndocker run -d --name emulator -p 5001:5001 vaporio/emulator-plugin\n```\n\nand use the [Synse CLI](https://github.com/vapor-ware/synse-cli) to query the plugin's gRPC API.\n\nThe emulator plugin ships with some default built-in [device configurations](config/device). If you\nwish to run the plugin with a different set of plugins, be sure to read through the\n[SDK Documentation](https://synse.readthedocs.io/en/latest/sdk/configuration/device/) on configuring\nplugin devices.\n\n## Emulator Plugin Configuration\n\nAll devices supported by the emulator plugin return dummy data. State is maintained for most writable\ndevices, so any state that you write should be retrievable via a subsequent read.\n\n### Outputs\n\nOutputs are referenced by name. A single device may have more than one instance\nof an output type. A value of `-` in the table below indicates that there is no value\nset for that field. The *custom* section describes outputs which this plugin defines\nwhile the *built-in* section describes outputs this plugin uses which are [built-in to\nthe SDK](https://synse.readthedocs.io/en/latest/sdk/concepts/reading_outputs/#built-ins).\n\n**Custom**\n\n| Name    | Description                                      | Unit  | Type    | Precision |\n| ------- | ------------------------------------------------ | :---: | ------- | :-------: |\n| airflow | A measure of airflow, in millimeters per second. | mm/s  | `speed` | 3         |\n\n**Built-in**\n\n| Name          | Description                                        | Unit  | Type          | Precision |\n| ------------- | -------------------------------------------------- | :---: | ------------- | :-------: |\n| color         | A color, represented as an RGB string.             | -     | `color`       | -         |\n| direction     | A measure of directionality.                       | -     | `direction`   | -         |\n| humidity      | A measure of humidity, as a percentage.            | %     | `humidity`    | 2         |\n| kilowatt-hour | A measure of energy, in kilowatt-hours.            | kWh   | `energy`      | 3         |\n| pascal        | A measure of pressure, in Pascals.                 | Pa    | `pressure`    | 3         |\n| rpm           | A measure of frequency, in revolutions per minute. | RPM   | `frequency`   | 2         |\n| state         | A generic description of state.                    | -     | `state`       | -         |\n| status        | A generic description of status.                   | -     | `status`      | -         |\n| temperature   | A measure of temperature, in degrees Celsius.      | C     | `temperature` | 2         |\n| voltage       | A measure of voltage, in Volts.                    | V     | `voltage`     | 5         |\n| watt          | A measure of power, in Watts.                      | W     | `power`       | 3         |\n\n### Device Handlers\n\nDevice Handlers are referenced by name.\n\n| Name        | Description                                 | Outputs                   | Read  | Write | Bulk Read | Listen |\n| ----------- | ------------------------------------------- | ------------------------- | :---: | :---: | :-------: | :----: |\n| airflow     | A handler for emulated airflow devices.     | `airflow`                 | ✓     | ✓     | ✗         | ✗      |\n| energy      | A handler for emulated energy devices.      | `kilowatt-hour`           | ✓     | ✓     | ✗         | ✗      |\n| fan         | A handler for emulated fan devices.         | `direction`, `rpm`        | ✓     | ✓     | ✗         | ✗      |\n| fan-multi   | A handler for emulated fan devices with multiple RPM readings. | `direction`, `rpm` | ✓ | ✓ | ✗     | ✗      |\n| humidity    | A handler for emulated humidity devices.    | `humidity`, `temperature` | ✓     | ✓     | ✗         | ✗      |\n| led         | A handler for emulated LED devices.         | `color`, `state`          | ✓     | ✓     | ✗         | ✗      |\n| lock        | A handler for emulated lock devices.        | `status`                  | ✓     | ✓     | ✗         | ✗      |\n| power       | A handler for emulated power devices.       | `watt`                    | ✓     | ✓     | ✗         | ✗      |\n| pressure    | A handler for emulated pressure devices.    | `pascal`                  | ✓     | ✓     | ✗         | ✗      |\n| temperature | A handler for emulated temperature devices. | `temperature`             | ✓     | ✓     | ✗         | ✗      |\n| voltage     | A handler for emulated voltage devices.     | `voltage`                 | ✓     | ✓     | ✗         | ✗      |\n\n### Write Values\n\nThis plugin supports the following values when writing to a device via a handler.\n\nThe emulator enables writing on devices where it would generally not otherwise be possible,\nallowing the user to adjust the reading values and ranges at runtime without having to re-deploy.\nHandlers set up this way will have the `min`, `max`, and `current` write actions available.\n\n| Handler     | Write Action  | Write Data | Description |\n| ----------- | :-----------: | :--------: | ----------- |\n| airflow     | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| energy      | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| fan         | `speed`       | `int`      | The speed to set the fan to. |\n| humidity    | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| led         | `state`       | `string`: *on*, *off*, *blink* | The LED power state. |\n|             | `color`       | `string`   | RGB hex color string. |\n| lock        | `lock`        | -          | Lock the door. |\n|             | `unlock`      | -          | Unlock the door. |\n|             | `pulseUnlock` | -          | Unlock the door for a short time, then lock it again. |\n| power       | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| pressure    | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| temperature | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n| voltage     | `min`         | `int`      | The minimum bound for readings to be generated within. |\n|             | `max`         | `int`      | The maximum bound for readings to be generated within. |\n|             | `current`     | `int`      | The static current reading value. |\n\n### Device Configurations\n\nIn addition to allowing values to be set via writing to devices, the behaviors/data ranges\nfor device readings may also be configured in the device configuration YAML for certain\ndevices. These options should be set under a device's `data` configuration, e.g.\n\n```yaml\nversion: 3\ndevices:\n  - type: temperature\n    context:\n      model: emul8-temp\n    instances:\n      - info: Synse Temperature Sensor 1\n        data:\n          id: 1\n          min: 20\n          max: 40\n```\n\nThe table below describes the supported configuration values for each type. None of the values\nspecified below are required to be set. If omitted, the plugin falls back on sane defaults.\nDefinitions for the settings follow:\n\n* `min`: The lower bound for a random walk. The walk will not subceed this value.\n* `max`: The upper bound for a random walk. The walk will not exceed this value.\n* `step`: The maximum size that a random walk may step by. For each iteration, the step is randomly chosen\n   between this max step size and 0.\n* `seed`: The starting value for the device.\n\n| Device Type | Setting | Type  | Default |\n| :---------: | :-----: | :---: | :-----: |\n| airflow     | `min`   | int   | -100 |\n|             | `max`   | int   | 100 |\n|             | `step`  | int   | 4 |\n| current     | `min`   | int   | 0 |\n|             | `max`   | int   | 30 |\n|             | `step`  | int   | 4 |\n| energy      | `min`   | int   | 0 |\n|             | `max`   | int   | 100000 |\n| fan         | `seed`  | int   | 0 |\n| frequency   | `min`   | int   | 0 |\n|             | `max`   | int   | 60 |\n|             | `step`  | int   | 4 |\n| humidity    | `min`   | int   | 0 |\n|             | `max`   | int   | 100 |\n|             | `step`  | int   | 4 |\n| power       | `min`   | int   | 1000 |\n|             | `max`   | int   | 3000 |\n|             | `step`  | int   | 4 |\n| pressure    | `min`   | int   | -5 |\n|             | `max`   | int   | 5 |\n|             | `step`  | int   | 4 |\n| temperature | `min`   | int   | 0 |\n|             | `max`   | int   | 100 |\n|             | `step`  | int   | 4 |\n| voltage     | `min`   | int   | 100 |\n|             | `max`   | int   | 500 |\n|             | `step`  | int   | 0 |\n\n## Compatibility\n\nBelow is a table describing the compatibility of plugin versions with Synse platform versions.\n\n|             | Synse v2 | Synse v3 |\n| ----------- | -------- | -------- |\n| plugin v1.x | ✗        | ✗        |\n| plugin v2.x | ✓        | ✗        |\n| plugin v3.x | ✗        | ✓        |\n\n## Troubleshooting\n\n### Debugging\n\nThe plugin can be run in debug mode for additional logging. This is done by:\n\n- Setting the `debug` option  to `true` in the plugin configuration YAML ([config.yml](config.yml))\n\n  ```yaml\n  debug: true\n  ```\n\n- Passing the `--debug` flag when running the binary/image\n\n  ```\n  docker run vaporio/emulator-plugin --debug\n  ```\n\n- Running the image with the `PLUGIN_DEBUG` environment variable set to `true`\n\n  ```\n  docker run -e PLUGIN_DEBUG=true vaporio/emulator-plugin\n  ```\n\n### Developing\n\nA [development/debug Dockerfile](Dockerfile.dev) is provided in the project repository to enable\nbuilding image which may be useful when developing or debugging a plugin. Unlike the slim `scratch`-based\nproduction image, the development image uses an ubuntu base, bringing with it all the standard command line\ntools one would expect. To build a development image:\n\n```\nmake docker-dev\n```\n\nThe built image will be tagged using the format `dev-{COMMIT}`, where `COMMIT` is the short commit for\nthe repository at the time. This image is not published as part of the CI pipeline, but those with access\nto the Docker Hub repo may publish manually.\n\n## Contributing / Reporting\n\nIf you experience a bug, would like to ask a question, or request a feature, open a\n[new issue](https://github.com/vapor-ware/synse-emulator-plugin/issues) and provide as much\ncontext as possible. All contributions, questions, and feedback are welcomed and appreciated.\n\n# License\n\nThe Synse Emulator Plugin is licensed under GPLv3. See [LICENSE](LICENSE) for more info.\n\n[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fvapor-ware%2Fsynse-emulator-plugin.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fvapor-ware%2Fsynse-emulator-plugin?ref=badge_large)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvapor-ware%2Fsynse-emulator-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvapor-ware%2Fsynse-emulator-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvapor-ware%2Fsynse-emulator-plugin/lists"}