1 files changed, 110 insertions, 0 deletions
diff --git a/readme.rst b/readme.rst
new file mode 100755
index 0000000..b8ffca2
--- /dev/null
+++ b/readme.rst
@@ -0,0 +1,110 @@
+
+Requirements
+============
+
+python3 -m pip install pystray pyserial zope.component
+
+for debian you may need to install :
+
+sudo apt install python3-pil.imagetk
+
+Configuration
+=============
+
+The configuration lies in an ini file:
+
+Serial connection
+-----------------
+
+.. code:: ini
+
+    [connexion.serial]
+    port = \\.\COM12
+
+
+Initialize a connection directly with the macropad
+
+Socket connection
+-----------------
+
+.. code:: ini
+
+    [connexion.socket]
+    port = 9999
+    host = localhost
+
+Use a proxy to connect with the keyboard (as client)
+
+Socket server
+-------------
+
+.. code:: ini
+
+    [socket.serve]
+    port = 9999
+    host = localhost
+    name = The name of the application to associate with
+
+Use a proxy to connect with the keyboard (as server)
+
+The mapping
+-----------
+
+.. code:: ini
+
+    [mapping]
+    Mozilla Firefox = Firefox
+    Teams = Teams
+    irssi = Irssi
+    …
+
+Mapping list
+============
+
+When a new window is selected, the application will look in the table for a
+match, and send the corresponding layer to the endpoint.
+
+.. note::
+
+    When using XLib, the application will match the name with both the CLASS or
+    the NAME of the selected window
+
+If the application receive a notification for a new layer, it will also
+register it, and store it for the session. This allow to make the application
+"learn" about the layer you want to use.
+
+Serial connection
+=================
+
+Sending message
+---------------
+
+The application send a json string to the endpoint (network or serial connection):
+
+.. code:: json
+
+    {"layout": "Firefox"}
+
+This application does not handle the code in the keyboard. CircuitPython
+provide a native library in order `to read or store json`_, and firmware build
+upon it (like KMK) are easer to use with.
+
+.. _`to read or store json`: https://docs.circuitpython.org/en/latest/docs/library/json.html
+
+Reading message
+---------------
+
+The endpoint can also send a message to the application. For now, the message
+is a raw string with the name of the layer.
+
+When the application receive such message, it will look for the active window
+in the desktop, and register the application with this layer. If this
+application is selected again, the application will ask the endpoint to switch
+to the same layer again.
+
+Network connection
+==================
+
+You can relay the events to another one instance using the network. I'm using
+this when I'm connected over VNC in order to use the keyboard as if it was
+plugged directly in the host.