diff --git a/docs/source/_autosummary/localite.api.rst b/docs/source/_autosummary/localite.api.rst
deleted file mode 100644
index 9705bd0..0000000
--- a/docs/source/_autosummary/localite.api.rst
+++ /dev/null
@@ -1,6 +0,0 @@
-localite.api
-============
-
-.. automodule:: localite.api
- :members:
- :undoc-members:
\ No newline at end of file
diff --git a/docs/source/_static/flow-diagram.png b/docs/source/_static/flow-diagram.png
new file mode 100644
index 0000000..3494e26
Binary files /dev/null and b/docs/source/_static/flow-diagram.png differ
diff --git a/docs/source/api.rst b/docs/source/api.rst
new file mode 100644
index 0000000..91aa500
--- /dev/null
+++ b/docs/source/api.rst
@@ -0,0 +1,20 @@
+Application Programming Interface
+---------------------------------
+
+The main interface to controlling your TMS coil with localite-flow
+
+
+Localite Flow
+*************
+
+.. automodule:: localite.flow.mitm
+ :members: start, kill
+
+Controlling the Coil
+********************
+
+Before you can control the coil and read its parameters, make sure the localite-flow is running, e.g. with :meth:`~localite.flow.mitm.start` or using the command-line-interface.
+
+
+.. automodule:: localite.coil
+ :members: Coil
\ No newline at end of file
diff --git a/docs/source/cli.rst b/docs/source/cli.rst
new file mode 100644
index 0000000..2c9bace
--- /dev/null
+++ b/docs/source/cli.rst
@@ -0,0 +1,26 @@
+Command Line Interface
+----------------------
+
+Use ``localite-flow`` to interface with a real localite TMS Navigator.
+
+
+.. code-block:: none
+
+ usage: localite-flow [-h] [--host HOST] [--kill]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --host HOST The IP-Adress of the localite-PC
+ --kill
+
+
+Use ``localite-mock`` if you don't have access to a real TMS Navigator, but want to develop and tests tasks or experiments using the API.
+
+.. code-block:: none
+
+ usage: localite-mock [-h] [--kill]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --kill
+
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 57076dd..75781d3 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -67,7 +67,7 @@
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
-source_suffix = [".rst", ".md"]
+source_suffix = [".rst"]
# The master toctree document.
master_doc = "index"
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 1a54579..d71a066 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -6,23 +6,79 @@
Welcome to ctrl-localite's documentation!
=========================================
+This package allows you to stream the current settings and messages from your `localite TMS Navigator `_ as `LSL stream `_ Additionally, it allows you to control the TMS device connected to the localite software over an api.
+
+This package has been developed using MagVenture TMS devices connected with localite TMS Navigator, and with a beta version of TMS Navigator 4.0. It's current test and coverage status is:
+
+
+ .. image:: https://github.com/pyreiz/ctrl-localite/workflows/pytest/badge.svg
+ :target: https://github.com/pyreiz/ctrl-localite/actions
+
+ .. image:: https://coveralls.io/repos/github/pyreiz/ctrl-localite/badge.svg?branch=master
+ :target: https://coveralls.io/github/pyreiz/ctrl-localite?branch=master
+
+
+Installation
+------------
+
+.. code-block:: bash
+
+ git clone git@github.com:pyreiz/ctrl-localite.git
+ cd ctrl-localite
+ pip install .
+
+Basic Usage
+-----------
+
+Usage of the API depends on a running localite-flow Server. Start this server ideally from the command line using e.g. ``localite-flow --host HOST`` with HOST the ip-adress of your localite PC.
+
+.. code-block:: bash
+
+ usage: localite-flow [-h] [--host HOST] [--kill]
+
+ optional arguments:
+ -h, --help show this help message and exit
+ --host HOST The IP-Adress of the localite-PC
+ --kill
+
+
+
+After that, you can use the python API to access the stream and control TMS Navigator remotely.
+
+.. code-block:: python
+
+ from localite.api import Coil
+ coil = Coil(0) # initializes the api for coil 1 (of e.g. 2)
+
+ coil.amplitude = 30 # sets the amplitude of this coil to 30% MSO
+ coil.trigger() # triggers the coil
+
+ coil.push_marker("Experiment finished") # publishes a marker over LSL
+
+
.. toctree::
- :maxdepth: 2
- :caption: Contents:
+ cli
+ api
+
+Information Flow
+----------------
+
+Information flows within the server in a relatively complex fashion. There is an EXT listening to messsages sent over the API, which are queued to be delivered to LOC, where they are sent to the localite PC. Concurrently, LOC is constantly listening for messages from the localite PC and sends them indirectly to MRK, where these messages are pubklished in an LSL Marker StreamOutlet. This allows you to publish additional markers over the API, and additonally supports easy automated logging of any command sent to localite.
+
+.. image:: _static/flow-diagram.png
+ :width: 600
+
+The setup is based on
+
+
+
-API
----
-The main interface to controlling your TMS coil with localite-flow
-.. autosummary::
- :toctree: _autosummary
- :template: module.rst
- localite.api
Indices and tables
-==================
+******************
* :ref:`genindex`
* :ref:`modindex`
diff --git a/localite/api.py b/localite/api.py
index f89c447..6ca9d10 100644
--- a/localite/api.py
+++ b/localite/api.py
@@ -1,22 +1,3 @@
-"""
-Localite Flow
--------------
-
-.. automodule:: localite.flow.mitm
- :members: start, kill
-
-Controlling the Coil
---------------------
-
-Before you can control the coil and read its parameters, make sure the localite-flow is running, e.g. with :meth:`~localite.flow.mitm.start` or the command-line-interface.
-
-
-.. automodule:: localite.coil
- :members: Coil
-
-
-"""
-
from localite.flow.mitm import start, kill
from localite.coil import Coil
diff --git a/readme.md b/readme.md
index 873b07d..9f88d58 100644
--- a/readme.md
+++ b/readme.md
@@ -1,51 +1,51 @@
- [](https://en.wikipedia.org/wiki/MIT_License) [](https://github.com/pyreiz/ctrl-localite/actions) [](https://coveralls.io/github/pyreiz/ctrl-localite?branch=develop)
+ [](https://en.wikipedia.org/wiki/MIT_License) [](https://github.com/pyreiz/ctrl-localite/actions) [](https://coveralls.io/github/pyreiz/ctrl-localite?branch=master) [](https://ctrl-localite.readthedocs.io/en/latest/?badge=latest)
-### ctrl-localite
+ctrl-localite
+------------
-A repository to control localite 4.0
+This package allows you to stream the current settings and messages from your [localite TMS Navigator](https://www.localite.de/en/home/>) as [LSL stream](https://labstreaminglayer.readthedocs.io/) Additionally, it allows you to control the TMS device connected to the localite software over an api.
-### Command Line Tools
+This package has been developed using MagVenture TMS devices connected with localite TMS Navigator, and with a beta version of TMS Navigator 4.0.
-- localiteLSL
+Installation
+------------
-starts reading from localite TCP/IP-json and forwards all stimulation trigger
-events as LSL Marker stream
+``` bash
+ git clone git@github.com:pyreiz/ctrl-localite.git
+ cd ctrl-localite
+ pip install .
+```
-- localiteMock
+Basic Usage
+-----------
-mocks a localite TCP/IP-json server for testing and development
+Usage of the API depends on a running localite-flow Server. Start this server ideally from the command line using e.g. ``localite-flow --host HOST`` with HOST the ip-adress of your localite PC.
+ usage: localite-flow [-h] [--host HOST] [--kill]
-### Information Flow
+ optional arguments:
+ -h, --help show this help message and exit
+ --host HOST The IP-Adress of the localite-PC
+ --kill
-
-
-
-custom_mark10
- digraph Flow {
- rankdir=LR;
- {
- node [shape = circle]
- node [style=filled]
- rankdir=LR;
- QUEUE -> CTRL
- EXT -> QUEUE
- CTRL -> LOC
- CTRL -> MRK
- LOC -> QUEUE
- }
- fo[label="", shape=plaintext]
- fo -> EXT
- to[label="", shape=plaintext]
- lo[label="", shape=plaintext]
- MRK -> to
- LOC -> lo
- }
-custom_mark10
-
-The EXT receives a payload via JSON over TCP-IP. Payloads have to have the form
-`[:str, :str, :int]`. The fmt defines how the message will be distributed. Only the following targets for `fmt` are valid: `["cmd", "mrk", "loc"]`. Invalid fmts will not be forwarded, and their message ignored.
-Whether the message part of the payload is valid depends on the recipient and will be evaluated there.
+After that, you can use the python API to access the stream and control TMS Navigator remotely.
+``` python
+ from localite.api import Coil
+ coil = Coil(0) # initializes the api for coil 1 (of e.g. 2)
+
+ coil.amplitude = 30 # sets the amplitude of this coil to 30% MSO
+ coil.trigger() # triggers the coil
+
+ coil.push_marker("Experiment finished") # publishes a marker over LSL
+```
+
+
+Information Flow
+----------------
+
+Information flows within the server in a relatively complex fashion. There is an EXT listening to messsages sent over the API, which are queued to be delivered to LOC, where they are sent to the localite PC. Concurrently, LOC is constantly listening for messages from the localite PC and sends them indirectly to MRK, where these messages are pubklished in an LSL Marker StreamOutlet. This allows you to publish additional markers over the API, and additonally supports easy automated logging of any command sent to localite.
+
+
\ No newline at end of file