MiczFlor · AlvinSchiller · Dec 9, 2023 · Dec 9, 2023 · Dec 10, 2023 · Dec 10, 2023
diff --git a/.githooks/post-merge b/.githooks/post-merge
@@ -43,7 +43,7 @@ warn_python_requirements() {
   echo "ATTENTION: Python requirements have changed since last pull!"
   echo ""
   echo "To update python requirements on the RPi run"
-  echo "$ python -m pip install --upgrade -r requirements.txt"
+  echo "$ ./run_python.sh pip install --upgrade -r requirements.txt"
   echo "************************************************************"
   echo -e "\n"
 }
@@ -81,4 +81,4 @@ if [[ -n $githooks_changed ]]; then
 fi
 
 echo -e "\nTo see a summary of what happened since your last pull, do:"
-echo -e "git show --oneline -s ORIG_HEAD..HEAD\n"
+echo -e "git show --oneline -s ORIG_HEAD..HEAD\n"
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
@@ -21,7 +21,7 @@ if [[ -n $PY_FILES ]]; then
   echo -e "\n**************************************************************"
   echo "Modified Python source files. Running flake8 ... "
   echo -e "**************************************************************\n"
-  ./run_flake8.sh $PY_FILES
+  ./run_python.sh ./run_flake8.sh $PY_FILES
   flake8_code=$?
   echo "Flake8 return code: $flake8_code"
 fi

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -123,7 +123,7 @@ It contains out setup file.
 
 ~~~bash
 cd ~/RPi-Jukebox-RFID
-./run_flake8.sh
+./run_python.sh ./run_flake8.sh
 ~~~
 
 If you are convinced some issue should not apply to your case or would require extensive re-coding, that could be OK.
@@ -136,7 +136,7 @@ them.
 
 ~~~bash
 cd ~/RPi-Jukebox-RFID/
-./run_pytest.sh
+./run_python.sh ./run_pytest.sh
 ~~~
 
 ## Submitting Changes

diff --git a/documentation/builders/audio.md b/documentation/builders/audio.md
@@ -10,14 +10,14 @@ Stream transfer happens on user input or automatically on the connection of an a
 This is mainly targeted at Bluetooth Headsets/Speakers.
 
 Audio outputs run via PulseAudio and the basic configuration should be easy.
-There is a [configuration tool](../developers/coreapps.md#run_configure_audio.py),
+There is a [configuration tool](../developers/coreapps.md#Audio),
 to setup the configuration for the Jukebox Core App.
 
 To set up the audio
 
 1. Follow the setup steps according to your sound card
 2. Check that the sound output works [as described below](audio.md#checking-system-sound-output)
-3. Run the the tool [run_configure_audio](../developers/coreapps.md#run_configure_audio.py)
+3. Run the [audio configuration tool](../developers/coreapps.md#Audio)
 4. [Fine-tune audio parameters](audio.md#additional-options)
 
 ## Checking system sound output
@@ -31,7 +31,7 @@ $ pactl list sinks short
 1	bluez_sink.C4_FB_20_63_CO_FE.a2dp_sink	        module-bluez5-device.c	s16le 2ch 44100Hz
 
 # Set the default sink (this will be reset at reboot)
-$ pactl set-default-sink sink_name
+$ pactl set-default-sink <sink_name>
 
 # Check default sink is correctly set
 $ pactl info
@@ -50,7 +50,7 @@ You can also try different PulseAudio sinks without setting the default sink. In
 volume level for this sink:
 
 ```bash
-$ paplay -d sink_name /usr/share/sounds/alsa/Front_Center.wav
+$ paplay -d <sink_name> /usr/share/sounds/alsa/Front_Center.wav
 ```
 
 # Bluetooth
@@ -134,8 +134,4 @@ You are, of course, free to modify the PulseAudio configuration to your needs. R
 1. [PulseAudio Documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User)
 2. [PulseAudio Examples](https://wiki.archlinux.org/title/PulseAudio/Examples)
 
-In this case, run the configuration tool with below parameter to avoid touching the PulseAudio configuration file.
-
-```bash
-$ ./run_configure_audio.py --ro_pulse
-```
+In this case, run the [audio configuration tool](../developers/coreapps.md#Audio) with the parameter `--ro_pulse` to avoid touching the PulseAudio configuration file.
diff --git a/documentation/builders/concepts.md b/documentation/builders/concepts.md
@@ -16,10 +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).
 
-We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](../developers/coreapps.md#run_rpc_toolpy)
+We also have a [tool to send RPC commands](../developers/coreapps.md#RPC) to the running Jukebox application.
 
 ## 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](../developers/coreapps.md#run_publicity_snifferpy).
+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](../developers/coreapps.md#Publicity-Sniffer) exists which listens and prints the incoming status messages.
diff --git a/documentation/builders/configuration.md b/documentation/builders/configuration.md
@@ -1,13 +1,13 @@
 # Jukebox Configuration
 
-The Jukebox configuration is managed by set of files located in `../shared/settings`.
+The Jukebox configuration is managed by a set of files located in `shared/settings`.
 Some configuration changes can be made through the WebUI and take immediate effect.
 
 The majority of configuration options is only available by editing the config files -
 *when the service is not running!*
 Don't fear (overly), they contain commentaries.
 
-For several aspects we have :ref:`developer/coreapps:Configuration Tools` and detailed guides:
+For several aspects we have [configuration tools](../developers/coreapps.md#configuration-tools) and detailed guides:
 
 * [Audio Configuration](./audio.md#audio-configuration)
 * [RFID Reader Configuration](../developers/rfid/basics.md#reader-configuration)
@@ -24,7 +24,8 @@ $ systemctl --user stop jukebox-daemon
 $ nano ./shared/settings/jukebox.yaml
 
 # Start Jukebox in console and check the log output (optional)
-$ ./src/jukebox/run_jukebox.py
+$ cd src/jukebox
+$ ../../run_python.sh ./run_jukebox.py 
 # and if OK, press Ctrl-C and restart the service
 
 # Restart the service
@@ -36,5 +37,6 @@ This could be useful if you want your Jukebox to only allow a lower volume when
 at night time when there is time to go to bed :-)
 
 ```bash
-$./run_jukebox.py --conf ../path/to/custom/config.yaml
+$ cd src/jukebox
+$ ../../run_python.sh ./run_jukebox.py --conf path/to/custom/config.yaml
 ```
diff --git a/documentation/builders/rpc-commands.md b/documentation/builders/rpc-commands.md
@@ -107,6 +107,6 @@ You will find some more examples the configuration of the [Card Database](card-d
 
 ## 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)
+To send RPC commands for testing and debugging purpose you can use the [CLI Tool](../developers/coreapps.md#RPC).
 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`.
diff --git a/documentation/builders/system.md b/documentation/builders/system.md
@@ -70,7 +70,7 @@ Service control and service configuration file location is identical to MPD.
 
 ## Jukebox Core Service
 
-The :ref:`developer/coreapps:Jukebox Core` runs as a *user-local* service with the name `jukebox-daemon`.
+The [Jukebox Core Service](../developers/coreapps.md#Jukebox-Core) runs as a *user-local* service with the name `jukebox-daemon`.
 Similar to MPD, it's important that it does run as system-wide service to be able to interact with PulseAudio.
 
 The service can be controlled with the `systemctl`-command by adding the parameter `--user`
@@ -101,7 +101,7 @@ Starting and stopping the service can be useful for debugging or configuration c
 The Web UI is served using nginx. Nginx runs as a system service. The home directory is localed at
 
 ```
-~/RPi-Jukebox-RFID/src/webapp/build
+./src/webapp/build
 ```
 
 The Nginx configuration is located at

diff --git a/documentation/builders/troubleshooting.md b/documentation/builders/troubleshooting.md
@@ -15,8 +15,8 @@ Debugging your setup runs in several steps
 ## The short answer
 
 ```bash
-../shared/logs/app.log   : Complete Debug Messages
-../shared/logs/errors.log: Only Errors and Warnings
+shared/logs/app.log   : Complete Debug Messages
+shared/logs/errors.log: Only Errors and Warnings
 ```
 
 These files always contain the messages of the current run only.
@@ -33,9 +33,9 @@ http://ip.of.your.box/logs
 
 ## The long answer: A few more details
 
-If started without parameters, the Jukebox checks for the existence of `../shared/settings/logger.yaml`
+If started without parameters, the Jukebox checks for the existence of `shared/settings/logger.yaml`
 and if present, uses that configuration for logging. This file is created by the installation process.
-The default configuration file is also provided in `../resources/default-settings/logger.default.yaml`.
+The default configuration file is also provided in `resources/default-settings/logger.default.yaml`.
 We use Python's logging module to provide the debug messages which is configured through this file.
 
 **We are still in the Pre-Release phase which means full debug logging is enabled by default.**
@@ -47,8 +47,8 @@ The default logging config does 2 things:
 1. It writes 2 log files:
 
 ```bash
-../shared/logs/app.log    : Complete Debug Messages
-../shared/logs/errors.log : Only Errors and Warnings
+shared/logs/app.log    : Complete Debug Messages
+shared/logs/errors.log : Only Errors and Warnings
 ```
 
 2. Prints logging messages to the console. If run as a service, only error messages are emitted to console to avoid spamming the system log files.
@@ -63,11 +63,12 @@ on the console log.
 $ systemctl --user stop jukebox-daemon
 
 # Start the Jukebox in debug mode:
-# with default logger:
-$ ./run_jukebox.py
+$ cd src/jukebox
 
+# with default logger:
+$ ../../run_python.sh ./run_jukebox.py
 # or with custom logger configuration:
-$ ./run_jukebox.py --logger ../path/to/logger.yaml
+$ ../../run_python.sh ./run_jukebox.py --logger path/to/custom/logger.yaml
 ```
 
 ### Fallback configuration
@@ -77,7 +78,8 @@ Attention: This only emits messages to the console and does not write to the log
 This is more a fallback features:
 
 ``` bash
-$ ./run_jukebox.py -vv
+$ cd src/jukebox
+$ ../../run_python.sh ./run_jukebox.py -vv
 ```
 
 ### Extreme cases

diff --git a/documentation/builders/update.md b/documentation/builders/update.md
@@ -2,6 +2,12 @@
 
 ## Updating your Jukebox Version 3
 
+### Update from v3.2.1 and prior
+
+As there are some significant changes in the installation, a new setup on a fresh image is required.
+
+### General
+
 Things on Version 3 are moving fast and you may want to keep up with recent changes. Since we are in Alpha Release stage,
 a fair number of fixes are expected to be committed in the near future.
 

diff --git a/documentation/developers/coreapps.md b/documentation/developers/coreapps.md
@@ -4,12 +4,12 @@ The Jukebox\'s core apps are located in `src/jukebox`. Run the following
 command to learn more about each app and its parameters:
 
 ``` bash
-$ ./run_app_name.py -h
+$ cd src/jukebox
+$ ../../run_python.sh ./<app_scriptname.py> -h
 ```
 
-## Jukebox Core
 
-### `run_jukebox.py`
+## Jukebox Core
 
 [run_jukebox.py](../../src/jukebox/run_jukebox.py)
 
@@ -19,24 +19,25 @@ Usually this runs as a service, which is started automatically after boot-up. At
 
 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](../builders/configuration.md#best-practice-procedure).
 
-### `run_configure_audio.py`
+### Audio
 
-[run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
+Scriptname: [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](../builders/audio.md).
 
-### `run_register_rfid_reader.py`
+### RFID Reader
 
-[run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)
+Scriptname: [run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)
 
 Setup tool to configure the RFID Readers.
 
@@ -45,11 +46,12 @@ Run this once to register and configure the RFID readers with the Jukebox. Can b
 > [!NOTE]
 > This tool will always write a new configurations file. Thus, overwrite the old one (after checking with the user). Any manual modifications to the settings will have to be re-applied
 
+
 ## Developer Tools
 
-### `run_rpc_tool.py`
+### RPC
 
-[run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
+Scriptname: [run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
 
 Command Line Interface to the Jukebox RPC Server.
 
@@ -59,9 +61,8 @@ The tool features auto-completion and command history.
 
 The list of available commands is fetched from the running Jukebox service.
 
+### Publicity Sniffer
 
-### `run_publicity_sniffer.py`
-
- [run_publicity_sniffer.py](../../src/jukebox/run_publicity_sniffer.py)
+Scriptname: [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.
diff --git a/documentation/developers/developer-issues.md b/documentation/developers/developer-issues.md
@@ -46,6 +46,7 @@ Alternatively, use the provided script, which sets the variable for you
 (provided your swap size is large enough):
 
 ``` bash
+$ cd src/webapp
 $ ./run_rebuild.sh
 ```
 

diff --git a/documentation/developers/development-environment.md b/documentation/developers/development-environment.md
@@ -61,7 +61,7 @@ Github, which is taken care of by the installation script. For regular
 machines, the normal package can be installed:
 
 ``` bash
-pip install pyzmq
+./run_python.sh pip install pyzmq
 ```
 
 You will have to start Jukebox core application and the WebUI

diff --git a/documentation/developers/docker.md b/documentation/developers/docker.md
@@ -33,7 +33,7 @@ need to adapt some of those commands to your needs.
     * Override/Merge the values from the following [Override file](https://github.com/MiczFlor/RPi-Jukebox-RFID/blob/future3/develop/docker/config/jukebox.overrides.yaml) in your `jukebox.yaml`.
     * **\[Currently required\]** Update all relative paths (`../..`) in to `/home/pi/RPi-Jukebox-RFID`.
 
-4. Change directory into the `./RPi-Jukebox-RFID/shared/audiofolders`
+4. Change directory into the `./shared/audiofolders`
     and copy a set of MP3 files into this folder (for more fun when
     testing).
 

diff --git a/documentation/developers/rfid/basics.md b/documentation/developers/rfid/basics.md
@@ -35,8 +35,7 @@ Readers operate on one of two different frequencies: 125kHz or 13.56 MHz. Make s
 ## Reader Configuration
 
 During the installation process, you can already configure a RFID
-reader. To manually configure RFID reader(s),
-[please run the tool](../coreapps.md#run_register_rfid_reader.py), (`src/jukebox/run_register_rfid_reader.py`).
+reader. To manually configure RFID reader(s) run the [RFID reader configuration tool](../coreapps.md#RFID-Reader).
 
 It will generate a reader configuration file at
 `shared/settings/rfid.yaml`. You can re-run the tool to change the
@@ -67,7 +66,7 @@ Indicates the Python package used for this reader. Filled by the RFID configurat
 
 #### config:
 
-Filled by the [RFID configuration tool](../coreapps.md#run_register_rfid_reader.py) (`src/jukebox/run_register_rfid_reader.py`) based on default values and user input. After running the tool, you may manually change some settings here, as not everything can be configured through the tool. Note that re-running the tool will completely rewrite the configuration file.
+Filled by the [RFID reader configuration tool](../coreapps.md#RFID-Reader) based on default values and user input. After running the tool, you may manually change some settings here, as not everything can be configured through the tool. Note that re-running the tool will completely rewrite the configuration file.
 
 #### same_id_delay: float \| integer
 

diff --git a/documentation/developers/rfid/genericusb.md b/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#run_register_rfid_readerpy).
+sure to connect all of them before running the [RFID reader configuration tool](../coreapps.md#RFID-Reader).
 
 > [!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:

diff --git a/documentation/developers/rfid/mfrc522_spi.md b/documentation/developers/rfid/mfrc522_spi.md
@@ -6,7 +6,7 @@ RC522 RFID reader via SPI connection.
 
 ## Installation
 
-Run the [run_register_rfid_reader.py](../coreapps.md#run_register_rfid_reader.py) tool for guided
+Run the [RFID reader configuration tool](../coreapps.md#RFID-Reader) for guided
 installation.
 
 ## Options

diff --git a/documentation/developers/rfid/template_reader.md b/documentation/developers/rfid/template_reader.md
@@ -9,9 +9,9 @@
 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>`.
+the Phoniebox. Just re-run [RFID reader configuration tool](../coreapps.md#RFID-Reader).
 
-Follow the instructions in [template_new_reader.py]
+Follow the instructions in [template_new_reader.py](../../../src/jukebox/components/rfid/hardware/template_new_reader/template_new_reader.py)
 
 Also have a look at the other reader subpackages to see how stuff works
 with an example

diff --git a/requirements.txt b/requirements.txt
@@ -1,5 +1,5 @@
 # Common python packages
-# You need to install these with `python -m pip install --no-cache-dir -r requirements.txt`
+# You need to install these with `./run_python.sh pip install --upgrade --force-reinstall -q -r path/to/requirements.txt`
 
 setuptools
 wheel

diff --git a/resources/default-settings/jukebox.default.yaml b/resources/default-settings/jukebox.default.yaml
@@ -30,7 +30,7 @@ pulse:
   toggle_on_connect: true
   # Limit maximum volume range to XX % - can be changed through the UI (for temporary use)
   soft_max_volume: 70
-  # Run the tool run_configure_audio.py to configure the pulseaudio sinks
+  # Run the audio configuration tool to configure the pulseaudio sinks
   #
   # After startup, the audio output defaults to primary
   # Any Bluetooth device should be the secondary (as it may not always be available directly after boot)