From 484f8f26e76ba4b1b8d73b24eb1b1672639189d9 Mon Sep 17 00:00:00 2001
From: Jonas Zeunert <jonas@zeunert.org>
Date: Sun, 25 Feb 2024 21:11:53 +0100
Subject: [PATCH] Update README.md

---
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index c2b2662..0de373d 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,8 @@ By default a static library gets build together with a networking target which e
  * Boost: program_options thread timer chrono filesystem
  * libthread
 
+ [^1]: Please note that wiringPi is deprecated and may not work on future releases of raspbian and most probably not on a Raspberry Pi5 and future versions.
+
 ### Build
 To build the flippr-driver library run the following commands:
 ```sh1
@@ -34,7 +36,6 @@ We added a script /usr/bin/reset_flippr this can be found in the repo and must b
  * `-DBUILD_NETWORKING` Builds the networking target binary. Default: On
  * `-DBUILD_CLI` Build a basic TUI to control the flipper by hand. Default: Off
 
- [^1]: Please note that wiringPi is deprecated and might not work on future releases of raspbian and most probably not on a Raspberry Pi5 and future versions.
 
  ## Usage
  ### Configuration
@@ -44,12 +45,58 @@ We added a script /usr/bin/reset_flippr this can be found in the repo and must b
  The Readme there contains all necessary information about the specific files.
 
 ### Networking
- When built with the networking target (default), the driver is accessible via two UNIX Domain Socket through a simple REST API. 
+ When built with the networking target (default), the driver is accessible via two UNIX Domain Socket through a simple HTTP/REST API. 
  The sockets can be found either in the folder specified through the env variable `XDG_RUNTIME_DIR` or if it is not set in `/tmp`.
 
  The sockets are:
+
     * `S.flippR_driver.in`: All input events that occure on the pinball machine get pushed there.
     * `S.flippr_driver.out`: With this socket the driver can be controlled.
+ 
+An example connector writtin in Python can be found in the TUI [[FlippR_Networking.py|https://gitlab.rhetenor.de/rhetenor/flippr-code/src/branch/master/cli/FlippR_Networking.py]]
 
-    
- An example connector writtin in Python can be found in the TUI [[FlippR_Networking.py|https://gitlab.rhetenor.de/rhetenor/flippr-code/src/branch/master/cli/FlippR_Networking.py]]
+In the following subsection the API is described.
+
+#### Output Socket
+The following GET commands are understood by the Output Socket:
+
+##### Solenoids
+
+ * `/solenoids`: Returns all available solenoids
+ * `/solenoids/ + name + /trigger`: Triggers the solenoid with the given name
+
+##### Sounds
+
+ * `/sounds`: Returns all available sounds
+ * `/sounds/ + name + /play`: Plays the sound with the given name
+
+##### Lamps
+
+ * `/lamps`: Returns all available lamps
+ * `/lamps/ + name + /activate`: Activates the lamp with the given name
+ * `/lamps/ + name + /deactivate`: Deactivates the lamp with the given name
+ * `/lamps/ + name + /status`: Returns the status of the lamp (active/inactive)
+
+##### Displays
+
+ * `/displays`: Returns all available displays
+ * `/displays/ + name + /write_score/ + score`: Writes the given number to the display
+ * `/displays/ + name + /write_content/ + content`: Writes the given content to the display
+
+##### Flippers
+
+ * `/flippers/ + name + /activate`: Activates the flippers (top or bottom)
+ * `/flippers/ + name + /deactivate`: Deactivates the flippers (top or bottom)
+
+#### Input Socket
+
+The input socket events are character terminated with a 0x02 byte [^2] and contain the JSON events defined in the `Input Matrix Config`:
+```
+{
+    "name": string,
+    "address": number,
+    "priority": number
+}
+```
+
+[^2]: This should be 0x03 ETX (End of text)