docs - added script and updated setup documentation

docs/source/conf.py

@@ -1,5 +1,5 @@
 project = 'GrowAutomation'
-copyright = '2021, Superstes'
+copyright = '2022, Superstes'
 author = 'Superstes'
 extensions = ['sphinx_rtd_theme']
 templates_path = ['_templates']

docs/source/config/area.rst

@@ -1,7 +1,6 @@
 .. _config-area:
 
 .. include:: ../includes/tip_links.rst
-.. include:: ../includes/warn_in_progress.rst
 
 ====
 Area
@@ -10,3 +9,5 @@ Area
 Description
 ***********
 How to configure areas to limit actors and/or conditions.
+
+.. include:: ../includes/warn_in_progress.rst

docs/source/config/dashboard.rst

@@ -4,7 +4,6 @@
    :class: ga-img-basic ga-img-center
 
 .. include:: ../includes/tip_links.rst
-.. include:: ../includes/warn_in_progress.rst
 
 =========
 Dashboard
@@ -19,19 +18,27 @@ Dashboards
 
 How to create a dashboard and configure its grid-system.
 
+.. include:: ../includes/warn_in_progress.rst
+
 Elements
 ********
 
 |element|
 
 How to create a dashboard element.
 
+.. include:: ../includes/warn_in_progress.rst
+
 Graphs
 ======
 
 How to create a graph prototype.
 
+.. include:: ../includes/warn_in_progress.rst
+
 Datasets
 ========
 
 How to create a dataset.
+
+.. include:: ../includes/warn_in_progress.rst

docs/source/config/device.rst

@@ -1,7 +1,6 @@
 .. _config-device:
 
 .. include:: ../includes/tip_links.rst
-.. include:: ../includes/warn_in_progress.rst
 
 ======
 Device
@@ -18,6 +17,8 @@ Basic
 
 How the basic device config is structured.
 
+.. include:: ../includes/warn_in_progress.rst
+
 ----
 
 .. _config-device-input:
@@ -29,6 +30,8 @@ Input
 
 Special config for input devices.
 
+.. include:: ../includes/warn_in_progress.rst
+
 ----
 
 .. _config-device-output:
@@ -40,6 +43,8 @@ Output
 
 Special config for output devices.
 
+.. include:: ../includes/warn_in_progress.rst
+
 ----
 
 .. _config-device-connection:
@@ -50,3 +55,5 @@ Connection
 :ref:`What are connection devices <device-connection>`
 
 Special config for connection devices.
+
+.. include:: ../includes/warn_in_progress.rst

docs/source/config/script.rst

@@ -1,12 +1,182 @@
 .. _config-script:
 
+.. |list| image:: ../_static/img/config/script/list.png
+   :class: ga-img-basic ga-img-center
+
 .. include:: ../includes/tip_links.rst
-.. include:: ../includes/warn_in_progress.rst
 
 ======
 Script
 ======
 
 Description
 ***********
-How add and manage custom scripts.
+How to add and manage custom scripts.
+
+Manage
+******
+
+The 'System - Scripts' site allows you to:
+
+* list existing scripts
+
+* delete existing scripts
+
+* show/read the content of existing scripts
+
+* upload new scripts and/or update existing ones
+
+|list|
+
+Writing scripts
+***************
+
+How your own scripts can be integrated into the GrowAutomation core.
+
+Basics
+======
+
+Binary
+------
+
+You are able to run your script with any given binary so that you can use your favorite scripting/programming language.
+
+It's also possible to just run a binary and leave the script empty - in case you want to use compiled code.
+
+Either way - the script/binary will be expected in the device-script directories.
+
+Script directories
+------------------
+
+With the default config, the directories are the following:
+
+.. code-block:: none
+
+  /var/lib/ga/device/input
+  /var/lib/ga/device/output
+  /var/lib/ga/device/connection
+
+Data output
+===========
+
+When using a script for an input-device you must return some data to the core.
+
+This is done by simply writing it to STDOUT. In Python you can just 'print' it.
+
+The core will expect the output to be formatted as JSON with the key 'data'.
+
+Per example:
+
+.. code-block:: bash
+
+  python3 cpu_temp.py
+  > {"data": "12.60"}
+
+In python3 this can be done like this:
+
+.. code-block:: python3
+
+  from json import dumps as json_dumps
+
+  output = get_data()
+  output_dict = {'data': output}
+  print(json_dumps(output_dict))
+
+
+Receiving config
+================
+
+There are basically two ways your script can receive configuration from the GrowAutomation core.
+
+Script arguments
+----------------
+
+If you need a:
+
+* simple 'switch' argument
+
+* that is shared across all of the devices of a type/model
+
+You can use a **script argument**.
+
+This argument is passed as-is to the script as argument #1.
+
+Per example:
+
+.. code-block:: none
+
+  # configured script: 'dht22.py'
+  # configured argument: 'temperature'
+
+  # command to be executed by the core:
+  python3 dht22.py temperature
+
+If you use an **output-device** that can be reversed - it is also possible to set a specific **reverse argument**!
+
+Per example:
+
+.. code-block:: none
+
+  # configured script: 'L298N.py'
+  # configured argument: 'forward'
+  # configured reverse-argument: 'reverse'
+
+  # command to be executed by the core to activate the actor:
+  python3 L298N.py forward
+
+  # command to be executed to stop the actor:
+  python3 L298N.py reverse
+
+Device connection
+-----------------
+
+Whenever you need to pass:
+
+* more settings
+
+* device-specific settings
+
+You can use the **device-connection** setting.
+
+This setting can be either hold one **single value** or **key-value pairs** and will be passed as JSON to the script.
+
+Single value
+^^^^^^^^^^^^
+
+Per example:
+
+.. code-block:: none
+
+  # configured script: 'dht22.py'
+  # configured argument: 'temperature'
+
+  # command to be executed by the core:
+  python3 dht22.py temperature "{\"connection\": 4}"
+
+Key-Value pairs
+^^^^^^^^^^^^^^^
+
+Per example:
+
+.. code-block:: none
+
+  # configured script: 'L298N.py'
+  # configured argument: 'forward'
+  # configured reverse-argument: 'reverse'
+  # configured device-connection: 'ga_json[fwd=19,rev=26,time=20]'
+
+  # command to be executed by the core to activate the actor:
+  python3 L298N.py forward "{\"connection\": {\"fwd\": \"19\", \"rev\": \"26\", \"time\": \"20\"}}"
+
+  # command to be executed to stop the actor:
+  python3 L298N.py reverse "{\"connection\": {\"fwd\": \"19\", \"rev\": \"26\", \"time\": \"20\"}}"
+
+The script can then load that config - in python3 this can be done like this:
+
+.. code-block:: python3
+
+  from sys import argv as sys_argv
+  from json import dumps as json_loads
+
+  CONFIG = json_loads(sys_argv[2])
+  get_data(CONFIG['my_setting'])

docs/source/config/system.rst

@@ -1,7 +1,6 @@
 .. _config-system:
 
 .. include:: ../includes/tip_links.rst
-.. include:: ../includes/warn_in_progress.rst
 
 ======
 System
@@ -10,3 +9,5 @@ System
 Description
 ***********
 How to configure the controller system.
+
+.. include:: ../includes/warn_in_progress.rst

docs/source/index.rst

@@ -36,3 +36,6 @@ Index
    :maxdepth: 1
 
    setup/*
+
+
+.. include:: ./includes/tip_links.rst

docs/source/setup/4-connect.rst

@@ -112,14 +112,14 @@ We had good experiences with these ones:
   * `TPLink TL-WA860RE <https://www.amazon.de/dp/B00K11UHVA/ref=emc_b_5_i>`_
 
 LAN
-===
+---
 
 The easiest and hardest way => *just* bury a network cable and connect the raspberry directly to your existing network.
 
 This will be much work but it will work like a charm and won't make any problems.
 
 SIM/LTE
-=======
+-------
 
 We have planned that the GrowAutomation setup should be able to work with a sim card. It should be accessible via dyn-dns over the mobile network.
 

docs/source/setup/6-post-setup.rst

@@ -1,7 +1,7 @@
 .. _setup-post-setup:
 
 .. |users| image:: ../_static/img/setup/post-setup/users.png
-   :width: 100%
+   :class: ga-img-center
 
 .. include:: ../includes/tip_links.rst
 
@@ -48,4 +48,4 @@ Basic tasks
 
 6. Now you can configure your devices and start using the GrowAutomation software!
 
-  More information to the configuration can be found :ref:`here <config-device-input>`.
+  More information to the configuration can be found :ref:`here <config-device>`.

setup/ReadMe.md

@@ -16,23 +16,8 @@ To install the pre-configured raspberry image you need to:
 
 * Download the image: <a href="https://drive.google.com/file/d/1MIoagaB4rKUwSbUtUW5E5ZUCCDU3k30S/view?usp=sharing">Google Drive</a>
 * Download and install the <a href="https://www.raspberrypi.com/software/">Raspberry Pi Imager</a> software on your computer (_or any other tool to flash images on a sd card_)
-* Flash the image on a sd card or <a href="https://docs.growautomation.eu/en/latest/setup/raspberry.html#ssd">ssd</a>
-* <a href="https://docs.growautomation.eu/en/latest/setup/find.html">Find the device on your network</a>
-* Connect to the device over ssh => the default **password** is: '**Gr0w21736!**'
-* Run the password-randomization-script for more security:
-  * ```bash
-    sudo bash /var/lib/ga/setup/randomize_pwds.sh
-    ```
-  * After that it will ask you for a 'BECOME password' => this is the password you used to connect to the device (_see above_)!
-
-* Get the configured passwords:
-  * ```bash
-    sudo cat /etc/.ga_setup
-    # sudo rm /etc/.ga_setup  # to delete the file
-    ```
-    The '**user**' password is for the web-ui login!
-  * **You should delete this file** after you saved your passwords safely!
-* Look into the <a href="https://docs.growautomation.eu/en/latest/setup/raspberry.html#ssd">post-setup guide</a> for further ToDos.
+* Flash the image on a sd card or <a href="https://docs.growautomation.eu/en/latest/setup/2-raspberry.html#ssd">ssd</a>
+* Look into the <a href="https://docs.growautomation.eu/en/latest/setup/6-post-setup.html">post-setup guide</a> for further ToDos.
 
 
 ----
@@ -91,4 +76,4 @@ After that it will ask you for a 'BECOME password' => you need to **provide the
 
 ##### Post install
 
-* Look into the <a href="https://docs.growautomation.eu/en/latest/setup/raspberry.html#ssd">post-setup guide</a> for further ToDos.
+* Look into the <a href="https://docs.growautomation.eu/en/latest/setup/6-post-setup.html">post-setup guide</a> for further ToDos.