frodovdr
/
hyperion.ng
mirror of https://github.com/hyperion-project/hyperion.ng.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Localize/stylize/freshen the en JSON API docs (#1074)

This commit is contained in:
Dermot Duffy 2020-11-09 09:41:27 -08:00 committed by GitHub
parent 36c05142a3
commit e2c8735fde
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 330 additions and 333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGELOG.md
View File

@ -36,6 +36,7 @@ Allow execution with option "--version", while another hyperion daemon is runnin
- Change links from http to https (#1067)
- UI: Separate LED-Layout creation from UI code
- Docs: Refreshed EN JSON API documentation
### Fixed
- Properly save Hue light state between sessions (#1014)

49
docs/docs/en/api/Detect.md
View File

@ -1,52 +1,57 @@
# Detect Hyperion
Hyperion pronounces it's services at the network. Currently with ZeroConf and SSDP.
Hyperion announces it's services on the network, via ZeroConf and SSDP.
[[toc]]
## SSDP
**S**imple**S**ervice**D**iscovery**P**rotocol ([SSDP](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol)), is the discovery subset of UPnP. The implementation is lighter than ZeroConf as it just needs a UdpSocket without further dependencies.
**S**imple**S**ervice**D**iscovery**P**rotocol
([SSDP](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol)) is the
discovery subset of UPnP. The implementation is lighter than ZeroConf as it just needs a
UDP Socket without any further dependencies.
### SSDP-Client Library
Here are some client libraries for different programming languages. You can also search for "UPnP" client libraries. This list isn't complete, nor tested but will show you how simple it actually is!
Here are some example client libraries for different programming languages (many others available):
* [NodeJS](https://github.com/diversario/node-ssdp#usage---client)
* [Java](https://github.com/resourcepool/ssdp-client#jarpic-client)
### Usage
If you found a ssdp-client library, all you need to do is searching for the following USN / service type:
With a given SSDP-client library, you can use the following USN / service type:
`urn:hyperion-project.org:device:basic:1`
Some headers from the response.
* Location: The URL of the webserver
* USN: The unique id for this Hyperion instance, it will remain the same also after system restarts or Hyperion updates
* HYPERION-FBS-PORT: The port of the flatbuffers server
* HYPERION-JSS-PORT: The port of the JsonServer
* HYPERION-NAME: The user defined name for this server
* More may be added in future with additional data to other Hyperion network ports
Some headers from the response will include:
* **Location**: The URL of the webserver
* **USN**: The unique id for this Hyperion instance, it will remain the same after system restarts or Hyperion updates
* **HYPERION-FBS-PORT**: The port of the flatbuffers server
* **HYPERION-JSS-PORT**: The port of the JsonServer
* **HYPERION-NAME**: The user defined name for this server
You will receive further notifications when the data changes (Network adapter changed the IP Address, port change) or Hyperion shuts down.
As the data changes (e.g. network adapter IP address change), new updates will be automatically announced.
## Zeroconf
Also known as [Apple Bonjour](https://en.wikipedia.org/wiki/Bonjour_(software)) or [Avahi](https://en.wikipedia.org/wiki/Avahi_(software)). Hyperion is detectable through zeroconf.
**Hyperion publishes the following informations:**
* _hyperiond-http._tcp -> Hyperion Webserver (HTTP+Websocket)
* _hyperiond-json._tcp -> Hyperion JSON Server (TcpSocket)
* _hyperiond-flatbuf._tcp -> Hyperion Flatbuffers server (Google Flatbuffers)
* **_hyperiond-http._tcp**: Hyperion Webserver (HTTP+Websocket)
* **_hyperiond-json._tcp**: Hyperion JSON Server (TcpSocket)
* **_hyperiond-flatbuf._tcp**: Hyperion Flatbuffers server (Google Flatbuffers)
So you get the IP address, hostname and port of the system. Also the Hyperion instance name is part of it (before the @ for the full name). As this works realtime you have always an up2date list of available Hyperion servers right to your hand. So check your development environment if you have access to it.
You get the IP address, hostname, port and the Hyperion instance name (before the @ for
the full name). As this works realtime you can always have an up to date list of available
Hyperion servers.
### TXT RECORD
Each published entry contains at least the following informations at the txt field
* id = A static unique id to identify a hyperion instance (good value to sort between new and known instances)
* version = Hyperion version
Each published entry contains at least the following data in the txt field:
* **id**: A static unique id to identify an Hyperion instance.
* **version**: Hyperion version.
### Test Clients
There are several clients available for testing like the [avahi-browse](http://manpages.ubuntu.com/manpages/bionic/man1/avahi-browse.1.html) commandline tool for ubuntu/debian. Example command
There are several clients available for testing like the
[avahi-browse](http://manpages.ubuntu.com/manpages/bionic/man1/avahi-browse.1.html) a
commandline tool for Ubuntu/Debian. Example command
``` bash
sudo apt-get install avahi-browse &&
avahi-browse -r _hyperiond-http._tcp
sudo apt-get install avahi-browse && avahi-browse -r _hyperiond-http._tcp
```
<ImageWrap src="/images/en/avahi-browse.jpg" alt="Searching for Hyperion Server with Avahi cli" />

12
docs/docs/en/api/Guidelines.md
View File

@ -1,13 +1,14 @@
# Guidelines
Improve the experience with Hyperion by following a rule set
Improve the user experience with Hyperion by following these guidelines.
[[toc]]
## Priority Guidelines
The possibilities of priorities mixing and using is endless. But where are a lot of possibilities you require also some guidelines to reduce confusion on user and developer side and to get the best matching experience possible.
Please adhere to the following priority guidelines to avoid user confusion and ensure
the best user experience possible:
The user expects, that an Effect or Color should be higher in priority than capturing as you usually run them from remotes and not all time.
While we have different capture/input methods, we follow also a specific priority chain to make sure that it fit's the most use cases out of the box.
The user expects that an effect or color should be higher in priority (lower in value)
than capturing, as colors/effects are usually run intermittently.
| Type | Priority/Range | Recommended | Comment |
| :---------------------: | :------------: | :---------: | :----------------------------------------: |
@ -19,5 +20,4 @@ While we have different capture/input methods, we follow also a specific priorit
| USB Capture | 240 | - | |
| Platform Capture | 250 | - | |
| Background Effect/Color | 254 | - | |
| Reserved | 255 | - | |
| Reserved | 255 | - | |

99
docs/docs/en/json/Authorization.md
View File

@ -1,21 +1,27 @@
## Authorization
Hyperion has an authorization system where people can login via password and applications with Tokens. The user can decide how strong or weak the Hyperion API should be protected.
Hyperion has an authorization system allowing users to login via password, and
applications to login with tokens. The user can configure how strong or weak the Hyperion API
should be protected from the `Configuration` -> `Network Services` panel on the Web UI.
[[toc]]
### Token System
Tokens are a simple way to authenticate an App for API access. They can be created "by hand" TODO LINK TO WEBUI TOKEN CREATION at the webconfiguration or your application can [request one](#request-a-token).
Tokens are a simple way to authenticate an App for API access. They can be created in
the UI on the `Configuration` -> `Network Services` panel (the panel appears when `API
Authentication` options is checked). Your application can also [request a
token](#request-a-token) via the API.
### Authorization Check
It's for sure useful to check if you actually need an authorization to work with the API. Ask Hyperion by sending
``` json
Callers can check whether authorization is required to work with the API, by sending:
```json
{
"command" : "authorize",
"subcommand" : "tokenRequired"
}
```
If the property "required" is true, you need authentication. Example response.
``` json
If the property `required` is true, authentication is required. An example response:
```json
{
"command" : "authorize-tokenRequired",
"info" : {
@ -27,8 +33,8 @@ If the property "required" is true, you need authentication. Example response.
```
### Login with Token
Login with your token as follows. And get a [Login response](#login-response)
``` json
Login with a token as follows -- the caller will receive a [Login response](#login-response).
```json
{
"command" : "authorize",
"subcommand" : "login",
@ -37,14 +43,14 @@ Login with your token as follows. And get a [Login response](#login-response)
```
### Login with Token over HTTP/S
Add the HTTP Authorization header to every request. On error, you will get a failed [Login response](#login-response)
``` http
Add the HTTP Authorization header to every request. On error, the user will get a failed [Login response](#login-response).
```http
Authorization : token YourPrivateTokenHere
```
#### Login response
Login success response
``` json
A successful login response:
```json
{
"command" : "authorize-login",
"success" : true,
@ -52,8 +58,8 @@ Login success response
}
```
Login failed response
``` json
A failed login response:
```json
{
"command" : "authorize-login",
"error" : "No Authorization",
@ -63,15 +69,18 @@ Login failed response
```
### Logout
You can also logout. Hyperion doesn't verify the login state, it will be always a success.
``` json
Users can also logout. Hyperion doesn't verify the login state, this call will always
return a success.
```json
{
"command" : "authorize",
"subcommand" : "logout"
}
```
Response
``` json
Response:
```json
{
"command" : "authorize-logout",
"success" : true,
@ -79,19 +88,26 @@ Response
}
```
::: warning
A Logout will stop all streaming data services and subscriptions
Logging out will stop all streaming data services and subscriptions
:::
### Request a Token
If you want to get the most comfortable way for your application to authenticate
* You ask Hyperion for a token along with a comment (A text which identifies you as the sender, meaningful informations are desired - appname + device) and a short random created id (numbers/letters)
* Wait for the response, the user needs to accept the request from the webconfiguration
* -> On success you get a UUID token which is now your personal app token
* -> On error you won't get a token, in this case the user denied the request or it timed out (180s).
* Now you are able to access the API, your access can be revoked by the user at any time, but will last for current connected sessions.
Requesting a token is easy, just send the following command, make sure to add a sufficient comment. The "id" field has 5 random chars created by yourself. And add a meaningful comment.
``` json
Here is the recommended workflow for your application to authenticate:
* Ask Hyperion for a token along with a comment (a short meaningful string that
identifies the caller is the most useful, e.g. includes an application name and
device) and a short randomly created `id` (numbers/letters).
* Wait for the response. The user will need to accept the token request from the Web UI.
* On success: The call will return a UUID token that can be repeatedly used. Note that
access could be revoked by the user at any time, but will continue to last for
currently connected sessions in this case.
* On error: The call won't get a token, which means the user either denied the request or it timed out (180s).
Request a token using the follow command, being sure to add a comment that is
descriptive enough for the Web UI user to make a decision as to whether to grant or deny
the request. The `id` field has 5 random chars created by the caller, which will appear
in the Web UI as the user considers granting their approval.
```json
{
"command" : "authorize",
"subcommand" : "requestToken",
@ -99,13 +115,15 @@ Requesting a token is easy, just send the following command, make sure to add a
"id" : "T3c91"
}
```
Now you wait for the response, show a popup that the user should login to the webconfiguration and accept the token request. Show the comment and the id so that the user can confirm the origin properly. After 180 seconds without a user action, the request is automatically rejected. You will get a notification about the failure.
After the call, a popup will appear in the Web UI to accept/reject the token request.
The calling application should show the comment and the id so that the user can confirm
the origin properly in the Hyperion UI. After 180 seconds without a user action, the
request is automatically rejected, and the caller will get a failure response (see below).
#### Success response
If the user accepted your token request you will get the following message.
* Save the token somewhere for further use, it doesn't expire.
* Be aware that a user can revoke the access. It will last for current connected sessions.
``` json
If the user accepted the token request the caller will get the following response:
```json
{
"command" : "authorize-requestToken",
"success" : true,
@ -116,12 +134,15 @@ If the user accepted your token request you will get the following message.
}
}
```
* Save the token somewhere for further use. The token does not expire.
* Be aware that a user can revoke the token. It will continue to function for currently connected sessions.
#### Failed response
A request will fail when
* Timeout - no user action for 180 seconds
* User denied the request
``` json
A request will fail when either:
* It times out (i.e. user neither approves nor rejects for 180 seconds after the request
is sent).
* User rejects the request.
```json
{
"command" : "authorize-requestToken",
"success" : false,
@ -130,8 +151,9 @@ A request will fail when
```
#### Request abort
You can abort the request by adding an "accept" property to the original request. The request will be deleted
``` json
You can abort the token request by adding an "accept" property to the original request.
The request will be deleted:
```json
{
"command" : "authorize",
"subcommand" : "requestToken",
@ -140,4 +162,3 @@ You can abort the request by adding an "accept" property to the original request
"accept" : false
}
```

158
docs/docs/en/json/Control.md
View File

@ -1,8 +1,8 @@
# Control
You can control Hyperion by sending specific JSON messages. Or get a image and led colors stream of the current active source priority.
You can control Hyperion by sending specific JSON messages.
::: tip
The `tan` property is supported, but omitted.
The `tan` property is supported in these calls, but omitted for brevity.
:::
[[toc]]
@ -15,19 +15,19 @@ Set a color for all leds or provide a pattern of led colors.
| Property | Type | Required | Comment |
| :------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
| color | Array | true | An array of R G B Integer values e.g. `[R,G,B]` |
| duration | Integer | false | Duration of color in ms. If you don't provide a duration, it's `0` -> endless |
| duration | Integer | false | Duration of color in ms. If you don't provide a duration, it's `0` -> indefinite |
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
``` json
// Example: Set color blue with endless duration at priority 50
```json
// Example: Set a blue color with indefinite duration at priority 50
{
"command":"color",
"color":[0,0,255],
"priority":50,
"origin":"My Fancy App"
}
// Example: Set color cyan for 12 seconds at priority 20
// Example: Set a cyan color for 12 seconds at priority 20
{
"command":"color",
"color":[0,255,255],
@ -36,8 +36,8 @@ Set a color for all leds or provide a pattern of led colors.
"origin":"My Fancy App"
}
// Example: Provide a color pattern, which will be reapted until all LEDs have a color
// In this case LED 1: Red, LED 2: Red, LED 3: Blue. This repeats now
// Example: Provide a color pattern, which will be repeated until all LEDs have a color
// In this case LED 1: Red, LED 2: Red, LED 3: Blue.
{
"command":"color",
"color":[255,0,0,255,0,0,0,0,255], // one led has 3 values (Red,Green,Blue) with range of 0-255
@ -48,17 +48,17 @@ Set a color for all leds or provide a pattern of led colors.
```
### Set Effect
Set an effect by name. Get a name from [Serverinfo](/en/json/ServerInfo.md#effect-list)
Set an effect by name. Available names can be found in the [serverinfo effect list](/en/json/ServerInfo.md#effect-list).
| Property | Type | Required | Comment |
| :------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
| effect | Object | true | Object with additional properties. e.g. `"name":"EffectName"`. |
| duration | Integer | false | Duration of effect in ms. If you don't provide a duration, it's `0` -> endless |
| duration | Integer | false | Duration of effect in ms. If you don't provide a duration, it's `0` -> indefinite |
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
``` json
// Example: Set effect Warm mood blobs with endless duration
```json
// Example: Set the 'Warm mood blobs' effect with indefinite duration
{
"command":"effect",
"effect":{
@ -67,7 +67,7 @@ Set an effect by name. Get a name from [Serverinfo](/en/json/ServerInfo.md#effec
"priority":50,
"origin":"My Fancy App"
}
// Example: Set effect Rainbow swirl for 5 seconds
// Example: Set 'Rainbow swirl' effect for 5 seconds
{
"command":"effect",
"effect":{
@ -77,9 +77,9 @@ Set an effect by name. Get a name from [Serverinfo](/en/json/ServerInfo.md#effec
"priority":50,
"origin":"My Fancy App"
}
// Example: Set effect Rainbow swirl for 1 seconds with overwritten agrument
// Each effect has different agruments inside the args property that can be overwritten
// WARNING: We highly recommend to use the effects configurator instead. As you can send wrong values and the effect can crash/ behave strange
// Example: Set 'Rainbow swirl' effect for 1 second with overridden agrument
// Each effect has different agruments inside the args property that can be overridden.
// WARNING: We highly recommend using the effects configurator in the UI instead. Sending invalid values may cause the effect to misbehave or crash.
{
"command":"effect",
"effect":{
@ -94,7 +94,7 @@ Set an effect by name. Get a name from [Serverinfo](/en/json/ServerInfo.md#effec
```
### Set Image
Set a single image. Supported are all [Qt5](https://doc.qt.io/qt-5/qimagereader.html#supportedImageFormats) image formats, including png/jpg/gif.
Set a single image. Supports all [Qt5](https://doc.qt.io/qt-5/qimagereader.html#supportedImageFormats) image formats, including png/jpg/gif.
| Property | Type | Required | Comment |
| :-------: | :-----: | :------: | :--------------------------------------------------------------------------------------------------------------: |
@ -105,8 +105,8 @@ Set a single image. Supported are all [Qt5](https://doc.qt.io/qt-5/qimagereader.
| priority | Integer | true | We recommend `50`, following the [Priority Guidelines](/en/api/guidelines#priority_guidelines). Min `2` Max `99` |
| origin | String | true | A short name of your application like `Hyperion of App` . Max length is `20`, min `4`. |
``` json
// Set a image for 5 seconds
```json
// Set an image for 5 seconds
{
"command":"image",
"imagedata":"VGhpcyBpcyBubyBpbWFnZSEgOik=", // as base64!
@ -119,8 +119,9 @@ Set a single image. Supported are all [Qt5](https://doc.qt.io/qt-5/qimagereader.
```
### Clear
Clear a priority, usually used to revert these: [set color](#set-color), [set effect](#set-effect), [set image](#set-image)
``` json
Clear a priority, usually used to revert [set color](#set-color), [set
effect](#set-effect) or [set image](#set-image).
```json
// Clear effect/color/image with priority 50
{
"command":"clear",
@ -133,11 +134,13 @@ Clear a priority, usually used to revert these: [set color](#set-color), [set ef
}
```
::: warning
When you clear all, you clear all effects and colors independent who set it! We recommend to provide a list of possible clear targets instead based on the priority list
When you clear all, you clear all effects and colors regardless of who set them!
Instead, we recommend users provide a list of possible clear targets based on a
priority list
:::
### Adjustments
Adjustments reflect the color calibration. You can modify all properties of [serverinfo adjustments](/en/json/serverinfo#adjustments)
Adjustments reflect the color calibration. You can modify all properties of [serverinfo adjustments](/en/json/serverinfo#adjustments).
| Property | Type | Required | Comment |
| :--------------------: | :------------: | :------: | :--------------------------------------------------------------------------------------------: |
@ -157,7 +160,7 @@ Adjustments reflect the color calibration. You can modify all properties of [ser
| backlightColored | Boolean | false | If `true` the backlight is colored, `false` it's white. Disabled for effect/color/image |
| id | String | false | Short identifier |
``` json
```json
// Example: Set gammaRed to 1.5
{
"command":"adjustment",
@ -191,8 +194,8 @@ Adjustments reflect the color calibration. You can modify all properties of [ser
```
### LED mapping
Switch the image to led mapping mode. Available are `unicolor_mean` (led color based on whole picture color) and `multicolor_mean` (led colors based on led layout)
``` json
Switch the image to led mapping mode. Possible values are `unicolor_mean` (led color based on whole picture color) and `multicolor_mean` (led colors based on led layout)
```json
// Example: Set mapping mode to multicolor_mean
{
"command":"processing",
@ -206,8 +209,8 @@ Switch the image to led mapping mode. Available are `unicolor_mean` (led color b
```
### Video Mode
Switch the video mode between 2D, 3DSBS, 3DTAB.
``` json
Switch the video mode. Possible values are: `2D`, `3DSBS` and `3DTAB`.
```json
// Example: Set video mode to 3DTAB
{
"command":"videomode",
@ -221,12 +224,12 @@ Switch the video mode between 2D, 3DSBS, 3DTAB.
```
### Control Components
It is possible to enable and disable certain components during runtime.
To get the current state and available components See [serverinfo Components](/en/json/serverinfo#components).
See also: [Components/IDs explained](#components-ids-explained)
Some components can be enabled and disabled at runtime. To get the current state and
available components see [Serverinfo Components](/en/json/serverinfo#components). See
also: [Components/IDs explained](#components-ids-explained)
``` json
// Example: disable component LEDDEVICE
```json
// Example: disable LEDDEVICE component
{
"command":"componentstate",
"componentstate":{
@ -234,7 +237,7 @@ See also: [Components/IDs explained](#components-ids-explained)
"state":false
}
}
// Example: enable component SMOOTHING
// Example: enable SMOOTHING component
{
"command":"componentstate",
"componentstate":{
@ -244,12 +247,13 @@ See also: [Components/IDs explained](#components-ids-explained)
}
```
::: warning
Hyperion needs to be enabled! Check the status of "ALL" at the components list before you change another component!
Hyperion itself needs to be enabled! Check the status of "ALL" in the components list before you change another component!
:::
### Components/IDs explained
Each component has a unique id. Not all of them can be enabled/disabled some of them like effect and color is used to determine the source
type you are confronted with at the priority overview.
Each component has a unique id. Not all of them can be enabled/disabled -- some of them,
such as effect and color, are used to determine the source type when examining the
[priority list](/en/json/ServerInfo.html#priorities).
| ComponentID | Component | Enable/Disable | Comment |
| :------------: | :------------------: | :------------: | :---------------------------------------------------------------------------: |
| SMOOTHING | Smoothing | Yes | Smoothing component |
@ -268,30 +272,36 @@ Each component has a unique id. Not all of them can be enabled/disabled some of
### Source Selection
Sources are always selected automatically by priority value (lowest number first), now you could select on your own a specific priority which should be visible (shown). You need the priority value of the source you want to select. Get them from the [serverinfo Priorities](/en/json/serverinfo#priorities).
``` json
Sources are always selected automatically by priority value (lowest value is the highest
priority). You need to know the priority value of the source you want to select -- these
priority values are available in the [serverinfo
Priorities](/en/json/serverinfo#priorities).
```json
// Example: Set priority 50 to visible
{
"command":"sourceselect",
"priority":50
}
```
If you get a success response, the `priorities_autoselect`-status will switch to false: [serverinfo Autoselection Mode](/en/json/serverinfo##priorities-selection-auto-manual). You are now in manual mode, to switch back to auto mode send:
``` json
If you get a success response, the `priorities_autoselect`-status will switch to false (see [serverinfo Autoselection Mode](/en/json/serverinfo##priorities-selection-auto-manual)). You are now in manual mode, to switch back to auto mode send:
```json
{
"command":"sourceselect",
"auto":true
}
```
Now, the `priorities_autoselect`-status will be again true
After which, the `priorities_autoselect`-status will return to `true`.
::: warning
You can just select priorities which are `active:true`!
You can only select priorities which are `active:true`!
:::
### Control Instances
An instance represents a LED hardware instance, it runs within a own scope along with it's own plugin settings, led layout, calibration. First, you need to get informations about instances. The first shot from [serverinfo Instance](/en/json/serverinfo#instance).
``` json
An instance represents an LED hardware instance. It runs within its own scope with it's
own plugin settings, led layout and calibration. Before selecting you can instance, you
should first get information about the available instances from [serverinfo](/en/json/serverinfo#instance).
```json
// Command to start instance 1
{
"command" : "instance",
@ -306,36 +316,43 @@ An instance represents a LED hardware instance, it runs within a own scope along
"instance" : 1
}
```
In both cases you get a success response, it doesn't return any error responses.
### API Instance handling
On connection to the API you will be connected to instance `0`, that means you can control just one instance at the same time within a connection. It's possible to switch to another instance with the following command.
On connection to the API you will be connected to instance `0` by default. You can
control only one instance at the same time within a single connection, and
[subscriptions](/en/json/subscribe#instance-updates) are in the context of the selected instance.
``` json
// We switch to instance 1
It's possible to switch to another instance with the following command:
```json
// Switch to instance 1
{
"command" : "instance",
"subcommand" : "switchTo",
"instance" : 1
}
```
Will return a success response, or a error response when the instance isn't available
This will return a success response or an error if the instance isn't available.
::: warning
It's possible that an instance will stop while you are connected. In this case you will be automatically reseted to instance `0`. So keep watching the instance data as subscription: [Instance updates](/en/json/subscribe#instance-updates)
It's possible that an instance will stop while you are connected to it. In this case
connections on that instance will automatically be reset to instance `0`. Keep watching
the instance data via subscription if you need to handle this case.
See: [Instance updates](/en/json/subscribe#instance-updates).
:::
### Live Image Stream
You can request a live image stream (when the current source priority can deliver). So it might be possible that there is no response or it stops and starts in between.
``` json
You can request a live image stream (if the current source priority supports it,
otherwise here may be no response).
```json
{
"command":"ledcolors",
"subcommand":"imagestream-start"
}
```
You will receive "ledcolors-imagestream-update" messages with a base64 encoded image.
Stop the stream by sending
``` json
Stop the stream by sending:
```json
{
"command":"ledcolors",
"subcommand":"imagestream-stop"
@ -347,16 +364,17 @@ This feature is not available for HTTP/S JSON-RPC
### Live Led Color Stream
You can request a live led color stream with current color values in RGB for each single led. Update rate is 125ms.
``` json
You can request a live led color stream with current color values in RGB for each single
led. The update rate is 125ms.
```json
{
"command":"ledcolors",
"subcommand":"ledstream-start"
}
```
You will receive "ledcolors-ledstream-update" messages with an array of all led colors.
Stop the stream by sending
``` json
Stop the stream by sending:
```json
{
"command":"ledcolors",
"subcommand":"ledstream-stop"
@ -365,25 +383,3 @@ Stop the stream by sending
::: danger HTTP/S
This feature is not available for HTTP/S JSON-RPC
:::
### Plugins
::: danger NOT IMPLEMENTED
THIS IS NOT IMPLEMENTED
:::
You can start and stop plugins. First, you need to get informations about plugins. The first short from [serverinfo plugins](/en/json/serverinfo#plugins).
You need now the plugin id. Example: `service.kodi`.
``` json
// Command to start a plugin
{
"command":"plugin",
"subcommand":"start",
"id":"service.kodi"
}
// Command to stop a plugin
{
"command":"plugin",
"subcommand":"stop",
"id":"service.kodi"
}
```
You will get a response of your action. `plugin-start` or `plugin-stop` with success true/false.

54
docs/docs/en/json/README.md
View File

@ -1,21 +1,28 @@
# JSON RPC Introduction
The JSON-RPC provide lot's of possibilities to interact with Hyperion. You could get information about Hyperion and it's states and trigger certain actions based on these informations or just out of the wild.
The JSON-RPC interfaces provides many ways to interact with Hyperion. You can retrieve
information about your server, your instances and take actions (such as setting a
priority input).
[[toc]]
## What is JSON?
JSON is a standardized message format [JSON.org](http://www.json.org/) and is supported by lot's of programming languages, which is perfect to transmit and process informations. While it's not the smartest in traffic size, it can be read by humans.
JSON is a standardized message format (see [JSON.org](http://www.json.org/)) and is supported
by most programming languages. It is human readable which makes for easier debugging.
### Sending JSON
Hyperion requires a special formatted JSON message to process it. `command` is always required, while `tan` is optional. The tan is a integer you could freely define. It is part of the response so you could easy filter for it in case you need it (Might be very rarely).
``` json
Hyperion requires a specially formatted JSON message. A `command` argument is always
required. A `tan` argument is optional. This is an integer you can freely choose -- it is
part of the response you will receive to allow you to filter the response from other server
messages (this functionality is likely necessary for advanced usecases only).
```json
{
"command" : "YourCommand",
"tan" : 1
}
```
Depending on command, there might be an additional subcommand required
``` json
Depending on the command, there might be an additional subcommand required:
```json
{
"command" : "YourCommand",
"subcommand" : "YourSubCommand",
@ -24,8 +31,8 @@ Depending on command, there might be an additional subcommand required
```
### Response
Most messages you send, trigger a response of the following format:
``` json
Most messages you send will trigger a response of the following format:
```json
{
"command" : "YourCommand",
"info":{ ...DATA... },
@ -33,27 +40,28 @@ Most messages you send, trigger a response of the following format:
"tan" : 1
}
```
- command: The command you requested.
- tan: The tan you provided (If not, defaults to 1).
- success: true or false. In case of false you get a proper answer what's wrong within an **error** property.
- info: The data you requested (if so)
- **command**: The command you requested.
- **tan**: The tan you provided (If not, it will default to 0 in the response).
- **success**: true or false. If false, an **error** argument will contain details of the issue.
- **info**: The data you requested (if any).
## Connect
Supported are currently TCP Socket ("Json Server"), WebSocket and HTTP/S.
Hyperion currently supports multiple connection mechanisms: TCP Socket ("Json Server"), WebSocket and HTTP/S.
::: tip
You can discover Hyperion servers! Checkout [Detect Hyperion](/en/api/detect.md)
You can automatically discover Hyperion servers! See [Detect Hyperion](/en/api/detect.md)
:::
### TCP Socket
Is a "raw" connection, you send and receive json from the json-rpc (default port: 19444). Also known as "Json Server".
This is a "raw" connection, you can send and receive line-separated json from the server
(default port: 19444). This is also known as the "Json Server".
### WebSocket
Part of the webserver (default port: 8090). You send and receive json from the json-rpc.
Supported is also WSS at port 8092. We support just TEXT mode. Read more at [Websocket](https://en.wikipedia.org/wiki/WebSocket|).
This is part of the Hyperion webserver (default port: 8090). You send and receive json
commands. WSS is also supported on port 8092. Only TEXT mode is supported. Read more
about websockets at [Websocket](https://en.wikipedia.org/wiki/WebSocket|).
### HTTP/S Json
HTTP requests can be also send to the webserver (default port: 8090, for HTTPS: 8092).
Send a HTTP/S POST request along with a properly formatted json message at the body to the (example) url: `http://IpOfDevice:WebserverPort/json-rpc`
HTTP requests can also be sent to the webserver (default port: 8090, for HTTPS: 8092). Send a HTTP/S POST request along with a properly formatted json message in the body to the (example) url: `http://IpOfDevice:WebserverPort/json-rpc`
<ImageWrap src="/images/en/http_jsonrpc.jpg" alt="Control Hyperion with HTTP JSON RPC">
Example picture with a [Firefox](https://addons.mozilla.org/de/firefox/addon/restclient/)/[Chrome](https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related) Addon to send HTTP JSON messages
@ -61,7 +69,7 @@ Example picture with a [Firefox](https://addons.mozilla.org/de/firefox/addon/res
</ImageWrap>
::: tip
If you get a "No Authorization" message back, you need to create an [Authorization Token](/en/json/Authorization.md#token-system)
If you get a "No Authorization" response, you need to create an [Authorization Token](/en/json/Authorization.md#token-system)
:::
::: warning HTTP/S Restrictions
@ -72,10 +80,10 @@ Please note that the HTTP JSON-RPC lacks of the following functions due to techn
## API
### Server Info
All kind of infos from the Server: [Server Info](/en/json/ServerInfo.md)
A large variety of data is available from the server: [Server Info](/en/json/ServerInfo.md)
### Control
Control Hyperion: [Control](/en/json/Control.md)
Control your Hyperion server: [Control](/en/json/Control.md)
### Authorization
All around the Authorization system: [Authorization](/en/json/Authorization.md)
Authorization mechanisms: [Authorization](/en/json/Authorization.md)
### Subscribe
Data subscriptions: [Subscribe](/en/json/Subscribe.md)

128
docs/docs/en/json/ServerInfo.md
View File

@ -1,25 +1,29 @@
# Sever Information
It provides you informations about Hyperion that are required to perform certain actions.
# Server Information
This is the primary read mechanism of the Hyperion server. This single command provides data about the live state of Hyperion, broken down into a number
of different parts (described below).
[[toc]]
Grab it by sending:
``` json
You can request a `serverinfo` response by sending the following command:
```json
{
"command":"serverinfo",
"tan":1
}
```
## Parts
## Parts of a serverinfo response
### Components
List of Hyperion components and their current status "enabled" (on/off). You can enable or disable them during runtime. The "ALL" component reflect Hyperion as a whole and as long "ALL" is false (off) you can't enable another component. [See control components](/en/json/control#control-components)
List of Hyperion components and their current status "enabled" (on/off). You can enable
or disable them during runtime . The "ALL" component reflect Hyperion as a whole -- if
"ALL" is false (off) you can't enable any other component. [See control
components](/en/json/control#control-components)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Component updates](/en/json/subscribe#component-updates)
:::
``` json
```json
{
"components":[
{
@ -59,11 +63,12 @@ You can subscribe to future data updates. Read more about [Component updates](/e
```
### Adjustments
Adjustments reflects the value of the last performed (non persistent) color adjustment. Read more about [control Adjustments](/en/json/control#adjustments)
Adjustments reflect the value of the last performed (non-persistent) color adjustment
(e.g. brightness). Read more about [control Adjustments](/en/json/control#adjustments)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Adjustment updates](/en/json/subscribe#adjustment-updates)
:::
``` json
```json
{
"adjustment":[
{
@ -87,12 +92,16 @@ You can subscribe to future data updates. Read more about [Adjustment updates](/
```
### Effect list
An array of effects where each object is one effect, usually you just use the `name` to create a list for the user. You could filter between user created effects and provided effects by checking the effect `file` string. In case it begins with `:` it's a provided effect. If the path begins with `/`, it's a user created effect. Could be used to list the user effects earlier than the provided effects and to keep the overview.
An array of effects where each object is one named effect. You can filter between user
created effects and system provided effects by checking the effect `file` string -- if
it begins with `:` it's a system provided effect, whereas if the path begins with `/`,
it's a user created effect.
See also [set Effect](/en/json/control#set-effect)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Effect updates](/en/json/subscribe#effects-updates)
:::
``` json
```json
{
"effects":[
{
@ -132,38 +141,43 @@ You can subscribe to future data updates. Read more about [Effect updates](/en/j
```
### LED mapping
Active mode of led area mapping. [See control LED mapping](/en/json/control#led-mapping)
Active mode of the led area mapping. [See control LED mapping](/en/json/control#led-mapping)
::: tip Subscribe
You can subscribe to future data updates. Read more about [LED mapping updates](/en/json/subscribe#led-mapping-updates)
:::
``` json
```json
"imageToLedMappingType":"multicolor_mean"
```
### Video mode
The current video mode of grabbers Can be switched to 3DHSBS, 3DVSBS. [See control video mode](/en/json/control#video-mode)
The current video mode of grabbers. Can be switched to 3DHSBS, 3DVSBS. [See control video mode](/en/json/control#video-mode)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Video mode updates](/en/json/subscribe#videomode-updates)
:::
``` json
```json
"videomode" : "2D"
```
### Priorities
Overview of the registered/active sources. Each object is a source.
* active: If "true" it is selectable for manual source selection. [See also source selection](/en/json/control#source-selection)
* visible: If "true" this source is displayed and will be pushed to the led device. The `visible:true`-source is always the first entry!
* componentId: A string belongs to a specific component. [See available components](/en/json/control#components-ids-explained)
* origin: The external setter of this source "NameOfRemote@IP". If not given it's `System` (from Hyperion).
* owner: Contains additional information related to the componentId. If it's an effect, the effect name is shown here. If it's USB capture it shows the capture device. If it's platform capture you get the name of it (While we use different capture implementations on different hardware (dispmanx/x11/amlogic/...)).
* priority: The priority of this source.
* value: Just available if source is a color AND color data is available (active = false has usually no data). Outputs the color in RGB and HSL.
* duration_ms: Actual duration in ms until this priority is deleted. Just available if source is color or effect AND a specific duration higher than `0` is set (because 0 is endless).
* **active**: If "true" it is selectable for manual source selection. [See also source selection](/en/json/control#source-selection)
* **visible**: If "true" this source is displayed and pushed to the led device. The `visible:true`-source is always the first entry!
* **componentId**: A key belonging to a specific component that indicates the kind of input. [See available components](/en/json/control#components-ids-explained)
* **origin**: A named external setter of this source for reference purposes. If not given it's `System` (from Hyperion).
* **owner**: Contains additional information related to the componentId. If it's an effect,
the effect name is shown here. If it's USB capture, the capture device is shown. If
it's platform capture, you get the name of the platform capture implementation (e.g. dispmanx/x11/amlogic/...).
* **priority**: The priority of this source, an integer between 0 and 255.
* **value**: If the source is a color AND color data is available (if active is false
there's usually no datta),hen this will be the color in RGB and HSL.
* **duration_ms**: Actual duration in ms until this priority is automatically deleted.
This is shown if source is color or effect AND a specific duration higher than
`0` is set (0 means indefinite).
::: tip Subscribe
You can subscribe to future data updates. Read more about [Priority updates](/en/json/subscribe#priority-updates)
:::
``` json
```json
"priorities":[
{
"active":true,
@ -196,17 +210,23 @@ You can subscribe to future data updates. Read more about [Priority updates](/en
]
```
### Priorities selection Auto/Manual
If "priorities_autoselect" is "true" the visible source is determined by priority. The lowest number is selected. If someone request to set a source manual, the value switches to "false".
In case the manual selected source is cleared/stops/duration runs out OR the user requests the auto selection, it switches back to "true". [See also source selection](/en/json/control#source-selection).
This value will be updated together with the priority update.
### Priorities selection: Auto/Manual
If `priorities_autoselect` is "true" the visible source is determined by priority. The
lowest number is automatically selected. If a caller requests to set a source manually,
then `priorities_autoselect` switches to `false`.
If the manually selected source is cleared/stops/completes-duration OR the user requests
the auto selection, `priorities_autoselect` switches back to `true`. This value is
atomically updated with the priority updates (shown above).
[See also source selection](/en/json/control#source-selection).
### Instance
Information about available instances and their state. Each instance represents a LED device. How to control them: [Control Instance](/en/json/control#control-instances).
Information about available instances and their state. Each instance represents a LED
device. Instances can be controlled, see: [Control Instance](/en/json/control#control-instances).
::: tip Subscribe
You can subscribe to future data updates. Read more about [Instance Updates](/en/json/subscribe#instance-updates)
:::
``` json
```json
"instance":[
{
"instance": 0,
@ -218,7 +238,7 @@ You can subscribe to future data updates. Read more about [Instance Updates](/en
"running" : false,
"friendly_name" : "PhilipsHue LED Hardware instance"
}
[
]
```
### LEDs
@ -226,7 +246,7 @@ Information about led layout (image mapping positions) and led count.
::: tip Subscribe
You can subscribe to future data updates. Read more about [LEDs Updates](/en/json/subscribe#leds-updates)
:::
``` json
```json
{
"leds":[
{
@ -247,16 +267,18 @@ You can subscribe to future data updates. Read more about [LEDs Updates](/en/jso
```
### System & Hyperion
It's possible to gather some basic software informations Hyperion runs on. This information is static and won't change during runtime.
``` json
It's possible to retrieve basic system information about the Hyperion server and the
host it runs on. This information is static and won't change during runtime.
```json
{
"command" : "sysinfo",
"tan" : 1
}
```
You can use the "version" (Hyperion version) string to check application compatibility. We use [Semantic Versioning 2.0.0](https://semver.org/).
If you need a specific id to re-detect known servers you can use the "id" field which provides a unique id.
``` json
If you need a specific id to re-detect known servers you can use the `id` field which
provides a unique id and will not change for a given server.
```json
{
"hyperion":{
"build":"webd (brindosch-38f97dc/814977d-1489698970)",
@ -278,18 +300,13 @@ If you need a specific id to re-detect known servers you can use the "id" field
}
```
Hyperion will answer your request. Below just the "info"-part of the response, splitted for better overview.
::: tip Subscribe
You can subscribe to future data updates. Read more about [Subscriptions](/en/json/subscribe)
:::
### Sessions
"sessions" shows all Hyperion servers at the current network found via Zeroconf/avahi/bonjour. See also [detect Hyperion](/en/api/detect.md)
`sessions` shows all Hyperion servers on the current network found via Zeroconf/avahi/bonjour. See also [detect Hyperion](/en/api/detect.md)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Session updates](/en/json/subscribe#session-updates)
:::
``` json
```json
{
"sessions":[
{
@ -303,28 +320,3 @@ You can subscribe to future data updates. Read more about [Session updates](/en/
]
}
```
### Plugins
::: danger NOT IMPLEMENTED
THIS IS NOT IMPLEMENTED
:::
Information about installed plugins. How to control them: [Control Plugins](/en/json/control#plugins)
::: tip Subscribe
You can subscribe to future data updates. Read more about [Plugin updates](/en/json/subscribe#plugin-updates)
:::
``` json
"plugins": {
"service.kodi": {
"description": "Connect to a Kodi instance to get player state",
"name": "Kodi Connector",
"version": "0.0.2",
"running": true
},
"service.wol": {
"description": "Send WOL packages to somewhere",
"name": "WOL Packages",
"version": "0.0.1",
"running": false
}
}
```

162
docs/docs/en/json/Subscribe.md
View File

@ -1,10 +1,13 @@
# Subscription
During initial serverinfo request you can subscribe to specific data updates or all of them at once, these updates will be pushed to you whenever a server side data change occur.
During a `serverinfo` request the caller can optionally subscribe to updates -- either
to specific [serverinfo parts](/en/json/ServerInfo.html#parts) or all available data.
These updates will be pushed whenever a server-side data change occurs, without the need
for the caller to poll.
[[toc]]
To subscribe for specific updates modify serverinfo command to
``` json
To subscribe to specific updates, you can modify the serverinfo command to:
```json
{
"command":"serverinfo",
"subscribe":[
@ -16,7 +19,7 @@ To subscribe for specific updates modify serverinfo command to
}
```
To subscribe for all available updates modify the severinfo command to
``` json
```json
{
"command":"serverinfo",
"subscribe":["all"],
@ -24,8 +27,10 @@ To subscribe for all available updates modify the severinfo command to
}
```
### Base response layout
All responses will have a `-update` suffix in their command property, it's the same command you subscribed to. The new data is in the `data` property. A `tan` and `success` property does not exist.
``` json
All pushed subscription updates will have an `-update` suffix added to the relevant key
from the [serverinfo part in question](/en/json/ServerInfo.html#parts). The new data
will be in the `data` property. There is no `tan` nor `success` argument provided.
```json
{
"command":"XYZ-update",
"data":{
@ -34,8 +39,11 @@ All responses will have a `-update` suffix in their command property, it's the s
}
```
### Component updates
You can subscribe to updates of components. These updates are meant to update the `components` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to component updates. These updates are meant to update the
`components` section of the caller's initial serverinfo. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":[
@ -44,8 +52,8 @@ You can subscribe to updates of components. These updates are meant to update th
"tan":1
}
```
You will get incremental updates, here an example response
``` json
After this, the caller will receive incremental updates. An example:
```json
{
"command":"components-update",
"data":{
@ -56,8 +64,10 @@ You will get incremental updates, here an example response
```
### Session updates
You can subscribe to session updates (Found with Bonjour/Zeroconf/Ahavi). These updates are meant to update the `sessions` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to session updates (Hyperion instances found with
Bonjour/Zeroconf/Ahavi). These updates are meant to update the `sessions` section of
the caller's initial serverinfo. Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":[
@ -66,9 +76,9 @@ You can subscribe to session updates (Found with Bonjour/Zeroconf/Ahavi). These
"tan":1
}
```
These updates aren't incremental, so they contain always all found entries.
Example response with 2 HTTP server sessions (_hyperiond-http._tcp)
``` json
These updates aren't incremental -- they contain all found entries on each update.
Example response with 2 HTTP server sessions (`_hyperiond-http._tcp`):
```json
{
"command":"sessions-update",
"data":[
@ -92,16 +102,19 @@ Example response with 2 HTTP server sessions (_hyperiond-http._tcp)
}
```
### Priority updates
You can subscribe to priority updates. These updates are meant to update the `priorities` and `priorities_autoselect` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to priority updates. These updates are meant to update the
`priorities` and `priorities_autoselect` section of the caller's initial `serverinfo`.
Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["priorities-update"],
"tan":1
}
```
You get the complete data, please note that if a color or effect is running with a timeout > -1 you will receive at least within a 1 second interval new data. Here an example update:
``` json
Caller will get the complete data. Please note that if a color or effect is running with
a timeout > -1, the caller will receive new data each second. An example update:
```json
{
"command":"priorities-update",
"data":{
@ -140,15 +153,17 @@ You get the complete data, please note that if a color or effect is running with
}
```
### LED Mapping updates
You can subscribe to LED mapping type updates. These updates are meant to update the `imageToLedMappingType` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to LED mapping type updates. These updates are meant to update
the `imageToLedMappingType` section of the caller's initial `serverinfo`.
Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["imageToLedMapping-update"],
"tan":1}
```
Here an example update:
``` json
An example update:
```json
{
"command":"imageToLedMapping-update",
"data":{
@ -157,16 +172,18 @@ Here an example update:
}
```
### Adjustment updates
You can subscribe to adjustment updates. These updates are meant to update the `adjustment` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to adjustment updates. These updates are meant to update the
`adjustment` section of the caller's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["adjustment-update"],
"tan":1
}
```
Here an example update:
``` json
An example update:
```json
{
"command":"adjustment-update",
"data":[{
@ -189,16 +206,18 @@ Here an example update:
}
```
### VideoMode updates
You can subscribe to videomode updates. These updates are meant to update the `videomode` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to videomode updates. These updates are meant to update the
`videomode` section of the cakker's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["videomode-update"],
"tan":1
}
```
Here an example update:
``` json
An example update:
```json
{
"command":"videomode-update",
"data":{
@ -207,16 +226,18 @@ Here an example update:
}
```
### Effects updates
You can subscribe to effect list updates. These updates are meant to update the `effects` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to effect list updates. These updates are meant to update the
`effects` section of the caller's initial `serverinfo`. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["effects-update"],
"tan":1
}
```
Here an example update:
``` json
An example update:
```json
{
"command":"effects-update",
"data":{
@ -226,16 +247,19 @@ Here an example update:
```
### Instance updates
You can subscribe to instance updates. These updates are meant to update the `instance` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to instance updates. These updates are meant to update the
`instance` section of the caller's initial serverinfo. Relevant `serverinfo`
subscription command:
```json
{
"command":"serverinfo",
"subscribe":["instance-update"],
"tan":1
}
```
Here an example update, you will also get the whole section:
``` json
An example update. This is not incremental -- the caller will get the full set of
instances:
```json
{
"command":"instance-update",
"data":[
@ -253,16 +277,17 @@ Here an example update, you will also get the whole section:
}
```
### LEDs updates
You can subscribe to leds updates. These updates are meant to update the `leds` section of your initial serverinfo. Modify serverinfo command to
``` json
The caller can subscribe to leds updates. These updates are meant to update the `leds`
section of the caller's initial `serverinfo`. Relevant `serverinfo` subscription command:
```json
{
"command":"serverinfo",
"subscribe":["leds-update"],
"tan":1
}
```
Here an example update, you will also get the whole section:
``` json
An example update. This is not incremental -- the caller willg et the full set of leds:
```json
{
"command":"leds-update",
"data": {
@ -278,54 +303,3 @@ Here an example update, you will also get the whole section:
}
}
```
### Plugin updates
::: danger NOT IMPLEMENTED
THIS IS NOT IMPLEMENTED
:::
You can subscribe to plugin updates. These updates are meant to update the `plugins` section of your initial serverinfo. Modify serverinfo command to
``` json
{
"command":"serverinfo",
"subscribe":[
"plugins-update"
],
"tan":1
}
```
Response on new plugin has been added (or plugin has been updated to a newer version)
``` json
{
"command":"plugins-update",
"data":{
"IdOfPlugin":{
"name":"The name of plugin",
"description":"The description of plugin",
"version":"TheVersion",
"running":false
}
}
}
```
Response on plugin removed, the data object contains a `removed` property / the plugin id object is empty
``` json
{
"command":"plugins-update",
"data":{
"ThePluginId":{
"removed":true
}
}
}
```
Response on plugin running state change
``` json
{
"command":"plugins-update",
"data":{
"ThePluginId":{
"running":true
}
}
}
```