The internal gRPC API for Synse Server and its plugins
Switch branches/tags
Clone or download
edaniszewski Migrate to Jenkins CI (#35)
* Add .jenkins file for new CI

* cleanup release testing
Latest commit e4834d1 Dec 10, 2018

README.md

Synse GRPC

The internal gRPC API for Synse Server and its plugins.

As of version 2.0, Synse Server uses a gRPC API internally to communicate with plugins to get information and readings to/from configured devices. This repo contains the gRPC API spec as well as auto-generated Python and Go packages for the gRPC API client/server.

Since the gRPC API components are used in multiple places (e.g. Python client in Synse Server, Go server in Plugins), this repo serves as the common location for the shared pieces.

The Synse Ecosystem

Synse Server is one component of the greater Synse Ecosystem.

  • vapor-ware/synse-server: An HTTP server providing a uniform API to interact with physical and virtual devices via plugin backends. This can be thought of as a 'front end' for Synse Plugins.

  • vapor-ware/synse-sdk: The official SDK (written in Go) for Synse Plugin development.

  • vapor-ware/synse-cli: A CLI that allows you to easily interact with Synse Server and Plugins directly from the command line.

  • vapor-ware/synse-graphql: A GraphQL wrapper around Synse Server's HTTP API that provides a powerful query language enabling simple aggregations and operations over multiple devices.

  • vapor-ware/synse-emulator-plugin: A simple plugin with no hardware dependencies that can serve as a plugin backend for Synse Server for development, testing, and just getting familiar with how Synse Server works.

Building

If changes need to be made to the gRPC API, the go/ and python/ (and any future supported language directory) should not be modified. Only the protobuf spec (synse.proto) should be modified. Once changed as desired, the language specific code can be generated via the make target:

make all

Additionally, packages for a supported language can be built by passing make the name of the language, e.g.

# auto-generate the python source
make python

# auto-generate the go source
make go

Using

Go

To use the generated client/server code for the Synse gRPC API, you simply just need to get it as you would any other go package.

go get -v github.com/vapor-ware/synse-server-grpc/go

It is then simple to import in a project.

package plugin

import (
    synse "github.com/vapor-ware/synse-server-grpc/go"
)

Python

To use the generated client/server code for the Synse gRPC API, you can get if from pypi with pip

pip install synse-grpc

It is then simple to import in a project.

import synse_grpc

Releasing

GitHub releases are done via CI. The go source does not need to be published anywhere, as it can be imported directly from this repo. The python source does need to be published. A make target is provided to make it easy.

make py-publish

Troubleshooting

To see a list of available make targets and a brief description, use

make help

If there is a bug or other issue you would like to report, please open a GitHub issue and provide as much context around the bug/issue as possible.

License

FOSSA Status