Merge branch 'future3/develop' into future3/feature/workflowCI

README.md

@@ -9,7 +9,7 @@ project check out the [documentation of Version 2](<https://github.com/MiczFlor/
 
 ## Where are the Help pages?
 
-The documentation can be found [here](./documentation)
+The documentation can be found [here](./documentation/README.md)
 
 ## Installation?
 

documentation/README.md

@@ -6,16 +6,18 @@ 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
 
-* [Installing Phoniebox future3](./content/userguide/installation.md)
-* [Update](./content/userguide/update.md)
-* [Feature Status](./content/developers/status.md)
-* [Known Issues](./content/developers/known-issues.md)
-* [User Guide](./content/userguide/)
-* [Developer Reference](./content/developers)
+* For Builders: Building a Phoniebox
+  * [Installing Phoniebox future3](./builders/installation.md)
+  * [Builder Guides](./builders/README.md)
+  * [Update](./builders/update.md)
+* For Developers: Add features or fix bugs
+  * [Developer Guides](./developers/README.md)
+  * [Feature Status](./developers/status.md)
+  * [Known Issues](./developers/known-issues.md)
 
 ## future3
 

documentation/content/userguide/README.md → documentation/builders/README.md

@@ -1,4 +1,4 @@
-# User Guide
+# Builder Guides
 
 ## Getting started
 
@@ -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/content/userguide/audio.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/content/userguide/card-database.md → 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](userguide/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/content/userguide/concepts.md → 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/content/userguide/configuration.md → 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/content/userguide/installation.md → documentation/builders/installation.md

@@ -3,7 +3,7 @@
 ## Install Raspberry Pi OS Lite
 
 > [!IMPORTANT]
-> Currently, the installation does only work on Raspberry Pi's with ARMv7 and ARMv8 architecture, so 2, 3 and 4! Pi 1 and Zero's are currently unstable and will require a bit more work!
+> Currently, the installation does only work on Raspberry Pi's with ARMv7 and ARMv8 architecture, so 2, 3 and 4! Pi 1 and Zero's are currently unstable and will require a bit more work! Pi 4 and 5 are an excess ;-)
 
 Before you can install the Phoniebox software, you need to prepare your Raspberry Pi.
 

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/content/developers/README.md → documentation/developers/README.md

@@ -1,4 +1,4 @@
-# Developers
+# Developer Guides
 
 ## Getting started
 

documentation/content/developers/coreapps.md → documentation/developers/coreapps.md

@@ -11,27 +11,33 @@ $ ./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](../userguide/configuration.md#jukebox-configuration).
+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).
 
-For debugging, it is usually desirable to run the Jukebox directly from the console rather than as service. This gives direct logging info in the console and allows changing command line parameters. See [Troubleshooting](../userguide/troubleshooting.md).
+For debugging, it is usually desirable to run the Jukebox directly from the console rather than as service. This gives direct logging info in the console and allows changing command line parameters. See [Troubleshooting](../builders/troubleshooting.md).
 
 ## Configuration Tools
 
 Before running the configuration tools, stop the Jukebox Core service.
-See [Best practice procedure](../userguide/configuration.md#best-practice-procedure).
+See [Best practice procedure](../builders/configuration.md#best-practice-procedure).
 
 ### `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.
 
-Run this once after installation. Can be re-run at any time to change the settings. For more information see [Audio Configuration](../userguide/audio.md).
+Run this once after installation. Can be re-run at any time to change the settings. For more information see [Audio Configuration](../builders/audio.md).
 
 ### `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/content/developers/developer-issues.md → 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/content/developers/development-environment.md → documentation/developers/development-environment.md

@@ -16,7 +16,7 @@ developing.
 
 1. Install the latest Pi OS on a SD card.
 2. Boot up your Raspberry Pi.
-3. [Install](../userguide/installation.md) the Jukebox software as if you were building a
+3. [Install](../builders/installation.md) the Jukebox software as if you were building a
     Phoniebox. You can install from your own fork and feature branch if
     you wish which can be changed later as well. The original repository
     will be set as `upstream`.