Merge branch 'master' into cleanups

hyperion-project · Nov 11, 2020 · 1ac7c21 · 1ac7c21
2 parents 325b573 + e2c8735
commit 1ac7c21
Show file tree

Hide file tree

Showing 9 changed files with 344 additions and 340 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -28,6 +28,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Documentation: Optimized images (#1058)
 - UX: Default LED-layout is now one LED only to avoid errors as in #673
 - UX: Change links from http to https (#1067)
+- Change links from http to https (#1067)
+- Cleanup packages.cmake & extend NSIS plugin directory
+- Optimize images (#1058)
+- Update LICENSE
+- Change links from http to https (#1067)
+- UI: Separate LED-Layout creation from UI code
+- Docs: Refreshed EN JSON API documentation
 
 ### Fixed
 - Color calibration for Kodi 18 (#1044)

diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -308,17 +308,17 @@ if (CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
 	#
 	#      "environments": [
 	#    {
-	#      "Qt5_BASE_DIR": "D:\\Qt\\5.15.1\\msvc2019_64"
+	#      "Qt5_BASE_DIR": "D:/Qt/5.15.1/msvc2019_64"
 	#    }
 	#  ]
 
 	if (NOT DEFINED ENV{Qt5_BASE_DIR})
 		FIRSTSUBDIR(SUBDIRQT "C:/Qt")
 		SET(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} "${SUBDIRQT}/msvc2019_64")
 	else()
-		message(STATUS "QT5_BASE_DIR: $ENV{QT5_BASE_DIR}")
-		message(STATUS "Add QT5_BASE_DIR: $ENV{QT5_BASE_DIR} to CMAKE_PREFIX_PATH")
-		SET(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} $ENV{Qt5_BASE_DIR})
+		message(STATUS "Qt5_BASE_DIR: $ENV{Qt5_BASE_DIR}")
+		message(STATUS "Add Qt5_BASE_DIR: $ENV{Qt5_BASE_DIR} to CMAKE_PREFIX_PATH")
+		SET(CMAKE_PREFIX_PATH ${CMAKE_PREFIX_PATH} "$ENV{Qt5_BASE_DIR}")
 	endif()
 
 	if (NOT DEFINED ENV{Qt5_DIR})
@@ -328,10 +328,11 @@ if (CMAKE_CXX_COMPILER_ID MATCHES "MSVC")
 			SET (qt_module_path "$ENV{Qt5_BASE_DIR}/lib/cmake/Qt5")
 		endif()
 	else()
-		SET (qt_module_path $ENV{Qt5_DIR})
+		SET (qt_module_path "$ENV{Qt5_DIR}")
 	endif()
+
 	message(STATUS "Add ${qt_module_path} to CMAKE_MODULE_PATH")
-	SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} ${qt_module_path})
+	SET(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${qt_module_path}")
 
 	#message(STATUS "CMAKE_PREFIX_PATH: ${CMAKE_PREFIX_PATH}")
 	#message(STATUS "CMAKE_MODULE_PATH: ${CMAKE_MODULE_PATH}")

diff --git a/docs/docs/en/api/Detect.md b/docs/docs/en/api/Detect.md
@@ -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" />
diff --git a/docs/docs/en/api/Guidelines.md b/docs/docs/en/api/Guidelines.md
@@ -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       |      -      |                                            |
diff --git a/docs/docs/en/json/Authorization.md b/docs/docs/en/json/Authorization.md
@@ -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,23 +43,23 @@ 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,
     "tan" : 0
 }
 ```
 
-Login failed response
-``` json
+A failed login response:
+```json
 {
     "command" : "authorize-login",
     "error" : "No Authorization",
@@ -63,49 +69,61 @@ 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,
     "tan" : 0
 }
 ```
 ::: 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",
     "comment" : "OpenHab 2 Binding",
     "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
 }
 ```
-