Future3/documentation (MiczFlor#2127)

* fixed typo

* restored "rpc-commands"

* fixed broken links

* switched placed for leading documentation

* added docu for changing swap size

* unified links to source

documentation/README.md

@@ -6,7 +6,7 @@ The exciting, new Version 3 of the RPi Jukebox RFID. A complete rewrite of the J
 > This documentation applies to the Version 3 which is developed in the branches `future3/main` and `future3/develop`. Currently the default Version is 2.x
 
 To find out more about the RPi Jukebox RFID
-project check out the [documentation of Version 2](https://github.com/MiczFlor/RPi-Jukebox-RFID) or [www.phoniebox.de](https://www.phoniebox.de/).
+project check out the [documentation of Version 2](https://github.com/MiczFlor/RPi-Jukebox-RFID) or [www.phoniebox.de](https://phoniebox.de/).
 
 ## Quickstart
 

documentation/builders/README.md

@@ -21,4 +21,4 @@
 * [System](./system.md)
 * [Feature Status](../developers/status.md)
 * [Known Issues](../developers/known-issues.md)
-* [Developer Reference](../developers)
+* [Developer Reference](../developers/README.md)

documentation/builders/audio.md

@@ -99,7 +99,7 @@ Rerun the config tool to register the Bluetooth device with the Jukebox core app
 
 For other audio configuration options, please look at the `jukebox.yaml` for now.
 
-Directly edit `jukebox.yaml` following the steps: [Best practice procedure](configuraton.md#best-practice-procedure).
+Directly edit `jukebox.yaml` following the steps: [Best practice procedure](configuration.md#best-practice-procedure).
 
 ## Developer Information
 

documentation/builders/card-database.md

@@ -4,7 +4,7 @@ In the card database, an RPC command is assigned to every card.
 
 This RPC command is called every time when the card is swiped (or
 placed) on the reader. Every RPC callable function can be called. See
-[RPC Commands](builders/rpc_commands.md) for an introduction.
+[RPC Commands](rpc-commands.md) for an introduction.
 
 The card database is stored in `shared\settings\cards.yaml`. Here are
 some examples for RPC command assignments to cards \'0001\' to \'0003\'

documentation/builders/concepts.md

@@ -16,12 +16,10 @@ The Remote Procedure Call (RPC) server allows remotely triggering actions (e.g.,
 
 Why should you care? Because we use the same protocol when triggering actions from other inputs like a card swipe, a GPIO button press, etc. How that works is described in [RPC Commands](rpc-commands.md).
 
-You will find a full list of RPC callable functions in [RPC Command Reference](rpc-command-reference.md) and aliases for convenience in [RPC Command Alias Reference](rpc-command-alias-reference.md).
-
-We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](../../../src/jukebox/run_rpc_tool.py).
+We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](../developers/coreapps.md#run_rpc_toolpy)
 
 ## Publishing Message Queue
 
 The Publishing Message Queue is the complementary part to the RPC where the core application publishes its status and status updates. As a user, you need not worry about it.
 
-If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A sniffer tool exists which listens and prints the incoming status messages: [run_publicity_sniffer.py](../../../src/jukebox/run_rpc_tool.py).
+If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A sniffer tool exists which listens and prints the incoming status messages: [run_publicity_sniffer.py](../developers/coreapps.md#run_publicity_snifferpy).

documentation/builders/configuration.md

@@ -10,7 +10,7 @@ Don't fear (overly), they contain commentaries.
 For several aspects we have :ref:`developer/coreapps:Configuration Tools` and detailed guides:
 
 * [Audio Configuration](./audio.md#audio-configuration)
-* [RFID Reader Configuration](./rfid/basics.md#reader-configuration)
+* [RFID Reader Configuration](../developers/rfid/basics.md#reader-configuration)
 
 Even after running the tools, certain aspects can only be changed by modifying the configuration files directly.
 

documentation/builders/rpc-commands.md

@@ -0,0 +1,112 @@
+# RPC Commands
+
+
+We use the RPC commands when triggering actions from different inputs like a card swipe,
+a GPIO button press, etc. Triggering an action is equal to sending an RPC function call.
+In many places the command to send when an input is triggered is configurable in a YAML-file.
+
+## Basics
+
+Consequently, you need to know how to specify the RPC command in the YAML file.
+Here is the essence of what you need to know:
+
+An RPC command consists of up to three parts
+
+    #. the function to execute (e.g. play_folder, change_volume)
+    #. the positional arguments (optional)
+    #. the keyword arguments (optional)
+
+The function specification consists of two (e.g., ``host.shutdown``) or three terms (e.g., ``volume.ctrl.change_volume``).
+In configuration files, this will look like this:
+
+.. code-block:: yaml
+
+        package: host
+        plugin: shutdown
+
+Or like this for a three part function with the argument set to ``5``:
+
+.. code-block:: yaml
+
+        package: volume
+        plugin: ctrl
+        method: change_volume
+        args: [5]
+
+The keyword ``method`` is optional. If needs to be used depends on the function you want to call.
+
+## Aliases
+
+
+Not so complicated, right? It will get even easier. For common commands we have defined aliases. An alias simply maps
+to a pre-defined RPC command, e.g. ``play_card`` maps to ``player.ctrl.play_card``.
+
+Instead of
+
+.. code-block:: yaml
+
+    package: player
+    plugin: ctrl
+    method: play_card
+    args: [path/to/folder]
+
+you can simply specify instead :
+
+.. code-block:: yaml
+
+    alias: play_card
+    args: [path/to/folder]
+
+Using in alias is optional. But if the keyword is present in the configuration it takes precedence over an explicit
+specified RPC command.
+
+## Arguments
+
+Arguments can be specified in similar fashion to Python function arguments: as positional arguments and / or
+keyword arguments. Let's check out play_card, which is defined as:
+
+.. py:function:: play_card(...) -> player.ctrl.play_card(folder: str, recursive: bool = False)
+    :noindex:
+
+    :param folder: Folder path relative to music library path
+    :param recursive: Add folder recursively
+
+This means it takes two arguments:
+
+    * folder of type string
+    * recursive of type bool
+
+In the following examples, we will always use the alias for smaller configuration text. All three examples
+do exactly the same, but use different ways of specifying the command.
+
+.. code-block:: yaml
+
+    alias: play_card
+    args: [path/to/folder, True]
+
+.. code-block:: yaml
+
+    alias: play_card
+    args: [path/to/folder]
+    kwargs:
+        recursive: True
+
+.. code-block:: yaml
+
+    alias: play_card
+    kwargs:
+        folder: path/to/folder
+        recursive: True
+
+
+.. important:: *args* must be a **list** of arguments to be passed! Even if only a single argument is passed.
+    So, use *args: [value]*. We try catch mis-uses but that might not always work.
+
+
+You will find some more examples the configuration of the [Card Database](card-database.md)
+
+## For developers
+
+To send RPC commands for testing and debugging purpose you can use the CLI Tool [`run_rpc_tool.py`](../developers/coreapps.md#run_rpc_toolpy)
+Also here is a ready-to-use decoding functions which decodes an RPC command (with or without alias)
+from a YAML entry:func:`jukebox.utils.decode_rpc_command`.

documentation/developers/coreapps.md

@@ -11,6 +11,8 @@ $ ./run_app_name.py -h
 
 ### `run_jukebox.py`
 
+[run_jukebox.py](../../src/jukebox/run_jukebox.py)
+
 This is the main app and starts the Jukebox Core.
 
 Usually this runs as a service, which is started automatically after boot-up. At times, it may be necessary to restart the service. For example after a configuration change. Not all configuration changes can be applied on-the-fly. See [Jukebox Configuration](../builders/configuration.md#jukebox-configuration).
@@ -24,6 +26,8 @@ See [Best practice procedure](../builders/configuration.md#best-practice-procedu
 
 ### `run_configure_audio.py`
 
+[run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
+
 Setup tool to register the PulseAudio sinks as primary and secondary audio outputs.
 
 Will also setup equalizer and mono down mixer in the pulseaudio config file.
@@ -32,6 +36,8 @@ Run this once after installation. Can be re-run at any time to change the settin
 
 ### `run_register_rfid_reader.py`
 
+[run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)
+
 Setup tool to configure the RFID Readers.
 
 Run this once to register and configure the RFID readers with the Jukebox. Can be re-run at any time to change the settings. For more information see [RFID Readers](./rfid/README.md).
@@ -43,14 +49,19 @@ Run this once to register and configure the RFID readers with the Jukebox. Can b
 
 ### `run_rpc_tool.py`
 
-Command Line Interface to the Jukebox RPC Server
+[run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
+
+Command Line Interface to the Jukebox RPC Server.
 
 A command line tool for sending RPC commands to the running jukebox app. This uses the same interface as the WebUI. Can be used for additional control or for debugging.
 
 The tool features auto-completion and command history.
 
 The list of available commands is fetched from the running Jukebox service.
 
+
 ### `run_publicity_sniffer.py`
 
+ [run_publicity_sniffer.py](../../src/jukebox/run_publicity_sniffer.py)
+
 A command line tool that monitors all messages being sent out from the Jukebox via the publishing interface. Received messages are printed in the console. Mainly used for debugging.

documentation/developers/developer-issues.md

@@ -49,6 +49,18 @@ Alternatively, use the provided script, which sets the variable for you
 $ ./run_rebuild.sh
 ```
 
+**Changing Swap Size**
+
+This will set the swapsize to 1024 MB (and will deactivate swapfactor). Change accordingly if you have a SD Card with small capacity.
+
+```
+sudo dphys-swapfile swapoff
+sudo sed -i "s|.*CONF_SWAPSIZE=.*|CONF_SWAPSIZE=1024|g" /etc/dphys-swapfile 
+sudo sed -i "s|^\s*CONF_SWAPFACTOR=|#CONF_SWAPFACTOR=|g" /etc/dphys-swapfile
+sudo dphys-swapfile setup 
+sudo dphys-swapfile swapon
+```
+
 ### Process exited too early // kill -9
 
 ``` {.bash emphasize-lines="8,9"}

documentation/developers/rfid/basics.md

@@ -79,7 +79,7 @@ For place-capable RFID readers enable dual action mode: a start action (e.g. pla
 
 #### card_removal_action: Dictionary
 
-Executes the given function on card removal. Only relevant if place_not_swipe is true. The action is identical for all cards read on that reader. The removal-action can be set to ignored on a card-by-card basis. More on card action configurations in [RPC Commands](../builders/rpc-commands.md).
+Executes the given function on card removal. Only relevant if place_not_swipe is true. The action is identical for all cards read on that reader. The removal-action can be set to ignored on a card-by-card basis. More on card action configurations in [RPC Commands](../../builders/rpc-commands.md).
 
 > [!NOTE]
 > Developer's note: The reason for a unique removal action for all cards is that card triggering and card removal are happening in two separate threads. Removal needs to be in a time-out thread. Thus, we would need to transport information from one thread to another. This can be done of course but is not implemented (yet). Ignoring card removal is much easier and works for now.

documentation/developers/rfid/genericusb.md

@@ -4,7 +4,7 @@
 
 This module covers all types of USB-based RFID input readers. If you
 plan to connect multiple USB-based RFID readers to the Jukebox, make
-sure to connect all of them before running the registration tool [run_register_rfid_reader.py](../coreapps.md).
+sure to connect all of them before running the registration tool [run_register_rfid_reader.py](../coreapps.md#run_register_rfid_readerpy).
 
 > [!NOTE]
 > The user needs to be part of the group \'input\' for evdev to work. This should usually be the case. However, a user can be added with:

documentation/developers/rfid/mock_reader.md

@@ -6,7 +6,7 @@ machine - probably in a Python virtual environment.
 
 **place-capable**: yes
 
-If you [mock the GPIO pins](../builders/gpio.md), this GUI will show the GPIO devices.
+If you [mock the GPIO pins](../../../src/jukebox/components/gpio/gpioz/README.rst#use-mock-pins), this GUI will show the GPIO devices.
 
 ![image](mock_reader.png)
 

documentation/developers/rfid/template_reader.md

@@ -1,2 +1,42 @@
 
-For documentation see [src/jukebox/components/rfid/hardware/template_new_reader/README.md](../../../../src/jukebox/components/rfid/hardware/template_new_reader/README.md).
+# Template Reader
+
+*Template for creating and integrating a new RFID Reader*
+
+> [!NOTE]
+> For developers only
+
+This template provides the skeleton API for a new Reader. If you follow
+the conventions outlined below, your new reader will be picked up
+automatically There is no extra need to register the reader module with
+the Phoniebox. Just re-run `the reader config tool <developer/coreapps:run_register_rfid_reader.py>`.
+
+Follow the instructions in [template_new_reader.py]
+
+Also have a look at the other reader subpackages to see how stuff works
+with an example
+
+## File structure
+
+Your new reader is a python subpackage with these three mandatory files
+
+``` bash
+components/rfid/hardware/awesome_reader/
+  +- awesome_reader.py  <-- The actual reader module
+  +- description.py     <-- A description module w/o dependencies. Do not change the filename!
+  +- README.rst         <-- The Readme
+```
+
+The module documentation must go into a separate file, called README.ME.
+
+## Conventions
+
+-   Single reader per directory / subpackage
+-   reader module directory name and reader module file name must be
+    identical
+-   Obviously awesome_reader will be replaced with something more
+    descriptive. The naming scheme for the subpackage is
+    -   \<type_of_reader\>\_\<io_bus\>\_\<other_specials_like_special_lib\>
+    -   e.g. generic_usb/generic_usb.py
+    -   e.g. pn532_spi/pn532_spi.py
+    -   ...

src/jukebox/components/rfid/hardware/fake_reader_gui/README.md

@@ -1,2 +1,2 @@
 
-For documentation see [documentation/content/developers/rfid/mock_reader.md](../../../../../../documentation/content/developers/rfid/mock_reader.md).
+For documentation see [documentation/developers/rfid/mock_reader.md](../../../../../../documentation/developers/rfid/mock_reader.md).

src/jukebox/components/rfid/hardware/generic_usb/README.md

@@ -1,2 +1,2 @@
 
-For documentation see [documentation/content/developers/rfid/genericusb.md](../../../../../../documentation/content/developers/rfid/genericusb.md).
+For documentation see [documentation/developers/rfid/genericusb.md](../../../../../../documentation/developers/rfid/genericusb.md).

src/jukebox/components/rfid/hardware/pn532_i2c_py532/README.md

@@ -1,2 +1,2 @@
 
-For documentation see [documentation/content/developers/rfid/pn532_i2c.md](../../../../../../documentation/content/developers/rfid/pn532_i2c.md).
+For documentation see [documentation/developers/rfid/pn532_i2c.md](../../../../../../documentation/developers/rfid/pn532_i2c.md).

src/jukebox/components/rfid/hardware/rc522_spi/README.md

@@ -1,2 +1,2 @@
 
-For documentation see [documentation/content/developers/rfid/mfrc522_spi.md](../../../../../../documentation/content/developers/rfid/mfrc522_spi.md).
+For documentation see [documentation/developers/rfid/mfrc522_spi.md](../../../../../../documentation/developers/rfid/mfrc522_spi.md).

src/jukebox/components/rfid/hardware/rdm6300_serial/README.md

@@ -1,2 +1,2 @@
 
-For documentation see [documentation/content/developers/rfid/rdm6300.md](../../../../../../documentation/content/developers/rfid/rdm6300.md).
+For documentation see [documentation/developers/rfid/rdm6300.md](../../../../../../documentation/developers/rfid/rdm6300.md).

src/jukebox/components/rfid/hardware/template_new_reader/README.md

@@ -1,41 +1,2 @@
-# Template Reader
 
-*Template for creating and integrating a new RFID Reader*
-
-> [!NOTE]
-> For developers only
-
-This template provides the skeleton API for a new Reader. If you follow
-the conventions outlined below, your new reader will be picked up
-automatically There is no extra need to register the reader module with
-the Phoniebox. Just re-run `the reader config tool <developer/coreapps:run_register_rfid_reader.py>`.
-
-Follow the instructions in [template_new_reader.py]
-
-Also have a look at the other reader subpackages to see how stuff works
-with an example
-
-## File structure
-
-Your new reader is a python subpackage with these three mandatory files
-
-``` bash
-components/rfid/hardware/awesome_reader/
-  +- awesome_reader.py  <-- The actual reader module
-  +- description.py     <-- A description module w/o dependencies. Do not change the filename!
-  +- README.rst         <-- The Readme
-```
-
-The module documentation must go into a separate file, called README.ME.
-
-## Conventions
-
--   Single reader per directory / subpackage
--   reader module directory name and reader module file name must be
-    identical
--   Obviously awesome_reader will be replaced with something more
-    descriptive. The naming scheme for the subpackage is
-    -   \<type_of_reader\>\_\<io_bus\>\_\<other_specials_like_special_lib\>
-    -   e.g. generic_usb/generic_usb.py
-    -   e.g. pn532_spi/pn532_spi.py
-    -   ...
+For documentation see [documentation/developers/rfid/template_reader.md](../../../../../../documentation/developers/rfid/template_reader.md).