/*
Backend providing a JSON based component connector via Websockets.
Configuration
In order to use this websocket based connector add something like the following
to your configuration file:
backends:
- type: websocket
listen: httpapi
Description
The `listen` parameter may specifiy an endpoint the websocket server should
be bound to (e.g. localhost:8080, 0.0.0.0:6600, :9000). As a special case,
"httpapi" can be specified. If so, the websocket connector backend attaches it
self the the HTTP API plugin and will therefore share it's HTTP server. In the
latter case the access URI will be "/devices" instead of "/".
API Description
First a Websocket connection must be established. During this HTTP request,
the device name and type must be provided. Consider the following Websocket URL:
ws://example.com/device?name=<YourDeviceName>&type=<YourDeviceType>
If this module is not used in conjunction with the HTTP API plugin the request
URL should look like:
ws://example.com/?name=<YourDeviceName>&type=<YourDeviceType>
If both parameters are provided a websocket connection can be initialized.
Now the client can start providing data by sending JSON messages following this
format:
{
"topic": "state_changed",
"state": <YourStateOfWhatsOEver>
}
Everything provided in `state` will be published on the internal eventbus and
thus be available for all subscribers.
Note that a WebSocket component can only send state updates and register service
calles. It is prohibited to execute other services or send other topics then
"state_changed" and "register_service".
Invalid messages will be logged and the respective connection will be closed.
In order to register new service calles within GoHome a Websocket component could
send a service registration request with the following format:
{
"topic": "register_service",
"name": "<NameOfYourService>",
"required": {
"param1": "This is the first and only parameter required"
},
"optional" {
"param2": "This is an optional parameter which defaults to: some-value"
}
}
The `name`, `required` and `optional` fields are required to be set during
service registration. However, `required` and `optional` may be an empty
map/object.
Whenever a service should be executed GoHome send the following request via the
Websocket connection:
{
"topic": "service_call",
"method": "<NameOfYourService>",
"params": [<ListOfParameters]
}
BUG: Currently it is NOT possible for Websocket components to return a response
to the caller! All service call will immediately return nil.
*/
func WebsocketConnectorBackend(config map[string]interface{}, back *backend.Backend) error {
logrus.Infof("Started backend %s with name %s", config["type"].(string), back.Name())
listen, _ := utils.GetString("listen", config, "httpapi")
back.OnShutdown = shutdownWebsockets
back.Internal = &websocketServer{
clients: make(map[string]peer),
name: back.Name(),
back: back,
}
if listen == "httpapi" {
logrus.Infof("Backend: %s: attaching to default HTTP server (httpapi) on URI /device", back.Name())
http.Handle("/device", back.Internal.(*websocketServer))
} else {
logrus.Infof("Backend: %s: listening on %s", back.Name(), listen)
go http.ListenAndServe(listen, back.Internal.(*websocketServer))
}
return nil
}
func initExampleBackend(config map[string]interface{}, back *backend.Backend) error {
// config represents the backend configuration passed to GoHome. Thus,
// the `name` (if set) and `typ` fields are still present within the map.
logrus.Infof("Started backend %s with name %s", config["type"].(string), back.Name())
// Manipulate the backend structure as you like
back.OnShutdown = shutdownExampleBackend
// use the component registration channel to register new components
// here a simple boolen "sensor" is created which value will toggle every
// few seconds
comp := &backend.Component{
StateSink: make(chan interface{}),
Name: "example",
Polling: updateExampleComponent,
Internal: true,
}
back.RegisterComponent <- comp
return nil
}