Update versioning, installation, main README

README.md

@@ -6,33 +6,36 @@
 [![codecov](https://codecov.io/gh/galactic-forensics/DigOutBox/graph/badge.svg?token=R4VQOKG1IR)](https://codecov.io/gh/galactic-forensics/DigOutBox)
 [![tests](https://github.com/galactic-forensics/DigOutBox/actions/workflows/package_testing.yml/badge.svg)](https://github.com/galactic-forensics/DigOutBox/actions/workflows/package_testing.yml)
 
-This project provides instrument builders with an easy interface
-to control digital output pins to control other devices,
-e.g., laser shutters.
+The Digital Output Box (DigOutBox) provides instrument builders with a simple hard- and software interface
+to generate output signals for controlling instruments,
+e.g., to open/close laser shutters.
 The project makes use of an
 [Arduino Mega](https://store.arduino.cc/products/arduino-mega-2560-rev3)
-in order to have digital output pins available via
+and makes 16 digital output pins (channels) available via
 DSub-9 and BNC connectors.
-Each channel will have its own LED as an indication status
-if the channel is high (LED on) or low (LED off).
-The Arduino can be controlled via a serial using a standard set of
-[SCPI commands](https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments)
-in order to control the device.
+Each channel has its own LED on the front of the box
+to display the status of the channel (high/low).
+
+The Arduino can be controlled via a serial interface using a standard set of
+[SCPI commands](https://en.wikipedia.org/wiki/Standard_Commands_for_Programmable_Instruments).
 Furthermore,
-a Python communications class
-and a Python GUI (making use of this class)
-are provided for easy control of the DigOutBox.
+a Python interface
+and a GUI (making use of this interface)
+are provided for easy computer control of the DigOutBox.
 Finally,
-the Arduino can also take commands from an RF control at 433 MHz,
-which puts it in the allowable range in the US and in Europe,
-to drive digital outputs.
+the box can also take commands from an RF control at 433 MHz
+to activate/deactivate channels.
+The selected frequency
+is in the allowable range in the US and in Europe.
 The idea of the remote is to give the user direct control
 when attending to, e.g., a laser on the table.
-Depending on the number of channels the control has
-(the default is 8),
+Depending on the number channels/buttons the control has
+(the remote chosen here has 8 buttons)
+and depending on the configuration,
 multiple channels can be controlled.
 
 
+
 | [<img src="docs/img/boxes/gfl002_setup_small.jpeg" width="600"><br>Front and top of DigOutBox</img>](docs/img/boxes/gfl002_setup.jpeg) | [<img src="docs/img/boxes/gfl002_back_top.jpeg" width="600"><br>Back of DigOutBox</img>](docs/img/boxes/gfl002_back_top.jpeg) |
 |:--------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------------------------------------:|
 

docs/controller.md

@@ -11,9 +11,15 @@ The interface is currently tested on python 3.8-3.12.
 
 We do not provide a package hosted on PyPI for this interface.
 However,
-you can directly install the latest version of the interface from GitHub
+you can directly install the latest released version of the interface from GitHub
 via `pip` using the following command:
 
+```bash
+pip install https://github.com/galactic-forensics/DigOutBox/releases/latest/download/controller-source.tar.gz
+```
+
+If you would like to install the latest version from the `main` branch, run:
+
 ```bash
 pip install git+https://github.com/galactic-forensics/DigOutBox.git#subdirectory=controller
 ```

docs/versioning.md

@@ -6,16 +6,16 @@ The firmware,
 python interface (aka controller),
 and GUI (aka controller_gui)
 are versioned independently.
-The following tags are added
-to GitHub:
+Each one gets a version number as following:
 
-| Module          | Tag          | Example      |
-|-----------------|--------------|--------------|
-| firmware        | `fw_vXYZ`    | `fw_v020`    |
-| controller      | `cnt_vX.Y.Z` | `cnt_0.2.0`  |
-| controller_gui  | `gui_vX.Y.Z` | `gui_v0.2.0` |
+- Firmware: `vXYZ`
+- Controller: `vX.Y.Z`
+- GUI: `vX.Y.Z`
 
-Here, `X`, `Y`, and `Z`
+The overall project is also versioned and tagged on GitHub.
+Each tag is named `vX.Y.Z` and is associated with a release.
+
+In above examples, `X`, `Y`, and `Z`
 follow
 [semantic versioning](https://semver.org/)
 guidelines and are:
@@ -36,11 +36,12 @@ This means, e.g.,
 that the GUI depends on both,
 the firmware and the controller.
 
+Generally, major and minor versions for every part of the project should agree with each other.
+The patch version can and will differ.
+
 !!! note
-    The whole project is versioned as well with a GitHub tag,
-    e.g., `v0.2`.
-    The patch version is omitted in this tag,
-    since it is not relevant for the whole project.
+    The patch version for the whole project
+    is the sum of all the firmware, controller, and GUI patch versions.
 
 ## Major versions
 
@@ -53,13 +54,13 @@ or the software are incompatible with previous versions.
 
 Minor versions are reserved for non-breaking changes,
 where new features are added.
-A GUI version `gui_0.1.0` will be compatible
-with firmware versions `fw_v010` and `fw_v020`
-as well as with controllerversions
-`cnt_v0.1.0` and `cnt_v0.2.0`.
+A GUI version `v0.1.0` will be compatible
+with firmware versions `v010` and `v020`
+as well as with controller versions
+`v0.1.0` and `v0.2.0`.
 
 !!! warning
-    The GUI with version `gui_v0.2.0` however
+    The GUI with version `v0.2.0` however
     will not be compatible with
     firmware or controller versions that are lower than `v0.2.0`.
     The same holds true for the controller,

mkdocs.yml

@@ -39,6 +39,7 @@ markdown_extensions:
 
 plugins:
   - mermaid2
+  - search
 
 nav:
   - Home: index.md