Added GSI Online to intro doc, fixed some issues

Author: MrClock8163

docs/introduction.rst

@@ -36,10 +36,13 @@ low level serial communication.
     conn.close()  # Closes the wrapped serial port
 
 .. caution::
+    :class: warning
 
     It is strongly recommended to set a ``timeout`` on the connection. Without
     a ``timeout`` set, the connection may end up in a perpetual waiting state
-    if the instrument becomes unresponsive.
+    if the instrument becomes unresponsive. A too small value however might
+    result in premature timeout issues when using slow commands (e.g.
+    motorized functions, measurements).
 
 The :class:`~geocompy.communication.SerialConnection` can also be used as a
 context manager, that automatically closes the serial port when the context
@@ -115,7 +118,7 @@ connection. The connection is tested during the initialization, and some
 communication parameters are syncronized.
 
 .. code-block:: python
-    :caption: Initializing instrument connection
+    :caption: Initializing instrument connection with GeoCom
     :linenos:
 
     from geocompy.communication import open_serial
@@ -125,11 +128,18 @@ communication parameters are syncronized.
     with open_serial("COM1", timeout=10) as conn:
         tps = TPS1200P(conn)
 
+.. note::
+
+    If the instrument is not turned on when the connection is initiated,
+    the process will try to wake it up. Since some instruments must be
+    manually put into GeoCom mode, the initialization might not be successful
+    from a completely shutdown state.
+
 Once the connection is verified, the commands can be executed through the
 various subsystems.
 
 .. code-block:: python
-    :caption: Querying the system software version through the Central Services
+    :caption: Querying the system software version through Central Services
     :linenos:
 
     resp = tps.csv.get_sw_version()
@@ -148,5 +158,77 @@ GSI Online
 ^^^^^^^^^^
 
 The GSI Online protocol is a command system that is older than GeoCom. Many
-older instruments either only support this system. Some support both (e.g. 
+older instruments only support this system. Some support both (e.g. 
 TPS1100 series).
+
+The commands fall into two groups:
+
+- instrument settings (CONF and SET commands)
+- measurements (GET and PUT commands)
+
+Instrument settings are set and queried with the ``SET`` and ``CONF`` commands.
+The values are communicated with simple enumerations of the valid settings.
+
+.. code-block::
+    :caption: GSI Online settings exchange example
+
+    CONF/30   # Query command
+    0030/0001 # Response
+
+    SET/30/2  # Setting beeping to loud
+    ?         # Success confirmation
+
+Measurement related ``PUT`` and ``GET`` commands on the other hand use GSI data
+words to exchange the necessary information.
+
+.. code-block::
+    :caption: GSI Online measurements exchange example
+
+    GET/M/WI11                # Query current point ID
+    11....+000000A1           # Response if format is GSI8
+    *11....+00000000000000A1  # Response if format is GSI16
+
+    PUT/11....+000000A2       # Setting new point ID
+    ?                         # Success confirmation
+
+The GSI Online based implementations mainly consist of 3 parts. The instrument
+object implements the basic request functions. The ``settings`` and the
+``measurements`` subsystems provide the individual commands.
+
+The connection to an instrument is identical to the GeoCom versions. The
+connection is tested during the initialization, and some communication
+parameters are syncronized.
+
+.. code-block:: python
+    :caption: Initializing instrument connection with GSI Online
+    :linenos:
+
+    from geocompy.communication import open_serial
+    from geocompy.dna import DNA
+
+
+    with open_serial("COM1", timeout=10) as conn:
+        level = DNA(conn)
+
+.. note::
+
+    If the instrument is not turned on when the connection is initiated,
+    the process will try to wake it up.
+
+Once the connection is live, the commands can be executed.
+
+.. code-block:: python
+    :caption: Turning off beeping and getting a staff reading
+    :linenos:
+
+    level.settings.set_beep(level.settings.BEEPINTENSITY.OFF)
+    resp = level.measurements.get_reading()
+    print(resp)  # GsiOnlineResponse(Reading) success, value: ...
+
+All GSI Online commands return a :class:`~geocompy.protocols.GsiOnlineResponse`
+object, that encapsulates command metadata and the result of the request.
+
+.. tip::
+
+    The complete list of available commands and their documentations are
+    available in their respective API documentation categories.

docs/overview.rst

@@ -57,6 +57,7 @@ GeoComPy is hosted on PyPI, therefore it can be installed with ``pip``.
 Package dependencies are automatically handled.
 
 .. code-block:: shell
+    :caption: Installing from PyPI
 
     pip install geocompy
 
@@ -70,5 +71,6 @@ Unpack the archive to a suitable place, and enter the ``geocompy-x.y.z``
 directory. Build and install the package with the following command:
 
 .. code-block:: shell
+    :caption: Building and installing locally
 
     python -m pip install .