some documentation updates

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.

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.

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_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_jukebox.py --conf path/to/custom/config.yaml
 ```

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`.

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

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:
+$ cd src/jukebox
+
 # with default logger:
 $ ./run_jukebox.py
-
 # or with custom logger configuration:
-$ ./run_jukebox.py --logger ../path/to/logger.yaml
+$ ./run_jukebox.py --logger path/to/custom/logger.yaml
 ```
 
 ### Fallback configuration
@@ -77,6 +78,7 @@ Attention: This only emits messages to the console and does not write to the log
 This is more a fallback features:
 
 ``` bash
+$ cd src/jukebox
 $ ./run_jukebox.py -vv
 ```
 

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.
 

documentation/developers/coreapps.md

@@ -4,64 +4,59 @@ 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
+$ ./<scriptname> -h
 ```
 
-## Jukebox Core
 
-### `run_jukebox.py`
+## Jukebox Core
 
-[run_jukebox.py](../../src/jukebox/run_jukebox.py)
+**Scriptname:** [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).
 
 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`
-
-[run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
+### Audio
 
-Setup tool to register the PulseAudio sinks as primary and secondary audio outputs.
+**Scriptname:** [run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
 
-Will also setup equalizer and mono down mixer in the pulseaudio config file.
+Setup tool to register the PulseAudio sinks as primary and secondary audio outputs. 
 
-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).
+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.
+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).
 
 > [!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`
 
-[run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
-
-Command Line Interface to the Jukebox RPC Server.
+## Developer Tools
 
-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.
+### RPC
 
-The tool features auto-completion and command history.
+**Scriptname:** [run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)
 
-The list of available commands is fetched from the running Jukebox service.
+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`
+### Publicity Sniffer
 
- [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.

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
 ```
 

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).
 

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
 

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:

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

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

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)

src/jukebox/components/rfid/hardware/fake_reader_gui/requirements.txt

@@ -1,5 +1,6 @@
 # This GUI-based mock reader also requires: tkinter
 # tkinter is a standard Python package and needs not be installed separately
 # It is available on most Unix systems (but not on headless Raspbian RPi where running a GUI is difficult anyway)
+# You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`
 
 ttkthemes

src/jukebox/components/rfid/hardware/pn532_i2c_py532/requirements.txt

@@ -1,3 +1,4 @@
 # PN532 related requirements
 # You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`
+
 py532lib

src/jukebox/components/rfid/hardware/rdm6300_serial/requirements.txt

@@ -1 +1,4 @@
+# RDM6300 related requirements
+# You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`
+
 pyserial