From 92bcdb3ede751625219a1811ada10ffb9e94831d Mon Sep 17 00:00:00 2001
From: Dorian Zedler <dorian@itsblue.de>
Date: Sat, 17 Oct 2020 23:11:47 +0000
Subject: [PATCH] Create home

---
 home.md | 181 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 home.md

diff --git a/home.md b/home.md
new file mode 100644
index 0000000..b1176a0
--- /dev/null
+++ b/home.md
@@ -0,0 +1,181 @@
+This is how the Bluetooth protocol works:
+Please note:  
+Some design choices, like sending one reply/request per set and parameter, may seem strange. This decision was made because it is not possible to send large amounts of data at once via BluetoothLE. 
+# Format definition
+## Request
+A request looks like this:
+```json
+{
+    "header":<command>,
+    "data":"<command data>"
+}
+```
+`<command>` is the command (see below).  
+`<data>` is some additional data required for the command (see below).
+
+## Reply
+A reply will look like this:
+
+```json
+{
+    "status":"<status code>",
+    "header":<command>,
+    "body":"<data>"
+}
+```
+`<command>` is the command the reply is answering to.  
+`<status code>` is the return code of the request, similar to an HTTP status code (see below).  
+`<data>` is additional data the command returned (see below).
+
+# Status codes
+```cpp
+enum OmobiDisplayStatusCode
+{
+    Success = 200,
+    BadRequestError = 400,
+    Unauthorized = 401,
+    InternalError = 500,
+    DisplayControllerError = 501
+};
+```
+
+# Text set parameters
+```cpp
+enum DisplayTextSetParameter
+{
+    TextParameter = 0,
+    ActiveParameter,
+    RuntimeParameter,
+    ColorParameter,
+    AlignmentParameter,
+    ScrollParameter,
+    ScrollSpeedParameter,
+    ScrollCountParameter,
+    IndexParameter,
+    DisplayTextSetParameterCount    /*!< Just for helping purposes */
+};
+```
+
+# Display controller error
+```cpp
+enum GetSetTextSetParameterExitCode
+{
+    Success,
+    InvalidParameterError,
+    ParameterNotWritableError,
+    ValueOutOfRangeError,
+    IndexOutOfRangeError,
+    ValueIsNullptrError,
+    InternalError
+};
+```
+
+# Commands
+## General commands
+### `0` - Authenticate
+Command to initially authenticate with the display.  
+This is requited in order to execute any other command (except keep alive).  
+#### Request data
+```
+{
+    "secret": "<display secret>"
+}
+```
+`<display secret>` is the secret of the display. It is `sha256(<display address><display code>)` in hex representation. The default for `<display code>` is `1234`.
+The `<display code>` can be changed using command  `22`.
+#### Reply data
+`null`
+
+### `1` - Keep alive
+This command has to be sent at leas every 10 seconds! Otherwise, the client will be disconnected from the display.
+#### Request data
+`null`
+#### Reply data
+`null`
+
+## Getter commands
+### `10` - Get all text sets
+Command to get all text sets stored on the display. 
+#### Specialties
+Before this command will be directly replied to, there will potentially be a lot of replies with the header `11`, one for each parameter of each existing text set. See `11` for more Information.
+#### Request data
+`null`
+#### Reply data
+`null`
+
+### `11` - Get a parameter of a text set
+Command to get a specific parameter of a single text set.
+#### Specialties
+This command can not be used for requests. It is only used to reply to a `10` command!
+#### Request data
+`null`
+#### Reply data
+```json
+{
+    "index":<text set index>,
+    "parameter":<parameter>,
+    "value":"<parameter value>"
+}
+```
+
+### `12`- Get display brightness
+Command to get the current brightness of the display.
+#### Request data
+`null`
+#### Reply data
+```
+{
+    "displayBrightness":<display brightness>
+}
+```
+`<display brightness>` is between 0 and 255
+
+## Setter commands
+### `20` - Set text set parameter
+Command to set a single parameter of a single set. To create a new text set, just edit its index.
+#### Request data
+```
+{
+    "index":<text set index>,
+    "parameter":<text set parameter>,
+    "value":<value>
+}
+```
+#### Reply data
+`null`
+
+### `21` - Set display brightness
+Command to set the current brightness of the display
+#### Request data
+```
+{
+    "displayBrightness":<display brightness>
+}
+```
+`<display brightness>` is between 0 and 255
+#### Reply data
+`null`
+
+### `22` - Set display code
+Command to modify the code of the display that is used for authentication (see `0`).
+#### Request data
+```
+{
+    "displayCode":"<display code>"
+}
+```
+#### Reply data
+`null`
+
+### `23` - Set display name
+Command to modify the name of the display
+#### Specialties
+This command requires the display (and some clients) to be rebooted in order to take effect.
+#### Request data
+```
+{
+    "displayName":"<display name"
+}
+```
+#### Reply data
+`null`
\ No newline at end of file