From 5484b610f1a9613f33fd0ebdc45f1f013616b2bc Mon Sep 17 00:00:00 2001 From: Simon Date: Thu, 21 Dec 2023 00:05:14 +0100 Subject: [PATCH 1/4] move GPIO docs and convert to markdown --- documentation/builders/README.md | 1 + .../builders/gpio.md | 235 ++++++++---------- 2 files changed, 100 insertions(+), 136 deletions(-) rename src/jukebox/components/gpio/gpioz/README.rst => documentation/builders/gpio.md (70%) diff --git a/documentation/builders/README.md b/documentation/builders/README.md index 86e98aca1..f9fef397e 100644 --- a/documentation/builders/README.md +++ b/documentation/builders/README.md @@ -10,6 +10,7 @@ * [Audio](./audio.md) * [RFID](./rfid.md) +* [GPIO Recipes](./gpio.md) * [Card Database](./card-database.md) * [Troubleshooting](./troubleshooting.md) diff --git a/src/jukebox/components/gpio/gpioz/README.rst b/documentation/builders/gpio.md similarity index 70% rename from src/jukebox/components/gpio/gpioz/README.rst rename to documentation/builders/gpio.md index 46ab0250a..feeb907ef 100644 --- a/src/jukebox/components/gpio/gpioz/README.rst +++ b/documentation/builders/gpio.md @@ -1,72 +1,60 @@ -.. RPI Jukebox RFID Version 3 -.. Copyright (c) See file LICENSE in project root folder +# GPIO Recipes -GPIO Recipes -************** - -Enabling GPIO ----------------- +## Enabling GPIO The GPIO module needs to be enabled in your main configuration file ``shared/settings/jukebox.yaml``. Look for the this entry and modify it accordingly: -.. code-block:: yaml - +```yml gpioz: enable: true config_file: ../../shared/settings/gpio.yaml +``` The GPIO configuration itself is stored in a separate file, in this case ``../../shared/settings/gpio.yaml``. -The GPIO module uses `GPIOZero `_ as a backend to access the RPi's GPIO pins. +The GPIO module uses [GPIOZero](https://gpiozero.readthedocs.io/) as a backend to access the RPi's GPIO pins. It's a wrapper to integrate GPIOZero into the Jukebox's API, allowing a YAML based configuration and providing helpful error messages on misconfiguration. -Pin Numbering ------------------ +## Pin Numbering The pin numbering is the BCM pin numbering, as is the -`default in GPIOZero `_. +[default in GPIOZero](https://gpiozero.readthedocs.io/en/stable/recipes.html#pin-numbering>). -Configuration -------------------- +## Configuration The GPIOZ configuration file has the following structure: -.. code-block:: yaml - +```yml pin_factory: type: rpigpio.RPiGPIOFactory output_devices: ... input_devices: ... +``` -There is no need to touch the header, but some `Developer options`_ can be found there. +There is no need to touch the header, but some `Developer options` can be found there. A file with examples can be found in ``resources/default-settings/gpio.yaml``. Below you will find easy to adapt recipes for various configuration snippets. - -Input devices ---------------- +## Input devices Configuring input devices consists of 2 aspects: - #. Define an input device and configure it's parameters. All available - input devices can be found in :class:`components.gpio.gpioz.core.input_devices`. - #. Assign an action to execute on input state change. - Actions are defined as :ref:`userguide/rpc_commands:RPC Commands`, - just the same as for assigning card actions. - +1. Define an input device and configure it's parameters. All available +input devices can be found in class `components.gpio.gpioz.core.input_devices`. +2. Assign an action to execute on input state change. +Actions are defined as [RPC Commands](rpc-commands.md), +just the same as for assigning card actions. -Button: Toggle Playback -^^^^^^^^^^^^^^^^^^^^^^^^ +### Button: Toggle Playback A button to toggle music playback on single press: -.. code-block:: yaml - +```yml input_devices: TogglePlayback: type: Button @@ -75,38 +63,37 @@ A button to toggle music playback on single press: actions: on_press: alias: toggle +``` Each device instantiation must be uniquely named, here ``TogglePlayback``. The name can be freely chosen, as long as it is unique. The parameter ``type`` directly matches the GPIO input device class, in this case -:class:`LED `. With ``kwargs`` you can set all the class initialization +class `LED `. With ``kwargs`` you can set all the class initialization parameters, which relate directly to the class' initialization parameters. -.. important:: You cannot set the class initialization parameters :attr:`pin_factory` or :attr:`name` +**Important:** You cannot set the class initialization parameters :attr:`pin_factory` or :attr:`name` from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. Usually, only the pin(s) are mandatory parameters. In the section ``actions``, the RPC commands are linked, -either as alias (i.e. shortcut) or full :ref:`userguide/rpc_commands:RPC Commands` specification. +either as alias (i.e. shortcut) or full [RPC Commands](rpc-commands.md) specification. The default configuration of the Button uses the internal pull-up resistor. So, the physical connection to the RPi looks: -.. code-block:: text - +```text ----+ | 1 kOhm Button 13| -----======------/ ----+ | | ----+ - GND +``` -Button: Increase volume -^^^^^^^^^^^^^^^^^^^^^^^^ +### Button: Increase volume A button to increase the volume by 5 steps every 0.75 seconds as long as it is pressed: -.. code-block:: yaml - +```yml input_devices: IncreaseVolume: type: Button @@ -118,14 +105,13 @@ A button to increase the volume by 5 steps every 0.75 seconds as long as it is p on_press: alias: change_volume args: +5 +``` -Button: Shutdown -^^^^^^^^^^^^^^^^^^^^^^^^ +### Button: Shutdown A button to shutdown the Jukebox if it is pressed for more than 3 seconds. Note the different ``type`` here! -.. code-block:: yaml - +```yml input_devices: IncreaseVolume: type: LongPressButton @@ -135,9 +121,9 @@ A button to shutdown the Jukebox if it is pressed for more than 3 seconds. Note actions: on_press: alias: shutdown +``` -Button: Dual Action -^^^^^^^^^^^^^^^^^^^^^^^^ +### Button: Dual Action A button to act differently on short and long presses. Go to previous song on single short press, start playlist from the beginning on press longer than 1 second. @@ -145,8 +131,7 @@ the beginning on press longer than 1 second. Note: the short press action is executed on button release since we don't not know how much longer somebody is going to press the button. The long press action is executed as soon as the hold time has been reached. -.. code-block:: yaml - +```yml input_devices: PreviousSong: type: ShortLongPressButton @@ -158,10 +143,9 @@ to press the button. The long press action is executed as soon as the hold time alias: prev_song on_long_press: alias: replay +``` - -TwinButton: Six function beast -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### TwinButton: Six function beast Use two buttons to encode up to six actions depending on single / dual press and also short / long press. Single button short presses skip to prev/next song, while long presses decrease/increase the volume. @@ -169,8 +153,7 @@ Here we also use make use of :attr:`hold_repeat`, to have the volume continue to down. Twin press toggle pause or changed the audio output sink from speakers to headset. The attribute :attr:`hold_repeat` only applies to single press actions, never to dual press actions. -.. code-block:: yaml - +```yml input_devices: SixActionBeast: type: TwinButton @@ -193,12 +176,12 @@ only applies to single press actions, never to dual press actions. args: 3 on_long_press_ab: alias: toggle_output +``` With a TwinButton not all functions need to be assigned. A button that only does prev/next song and causes as shutdown only on dual press with a minimum hold time of 2 seconds looks like this: -.. code-block:: yaml - +```yml input_devices: CombinationButton: type: TwinButton @@ -213,10 +196,9 @@ shutdown only on dual press with a minimum hold time of 2 seconds looks like thi alias: next_song on_long_press_ab: alias: toggle_output +``` - -Rotary Encoder: Volume Control -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Rotary Encoder: Volume Control A rotary encoder to change the volume: A common module is the KY-040, which can be picked up from numerous shops. It has four pins, typically labelled DT, CLK, SW, GND. Connect GND to ground. Connect DT and CLK to the @@ -225,8 +207,7 @@ direction does not match, simply swap the pins in the configuration file. The pi present. It is a button when the rotary encoder is pressed from the top. Configure a regular button entry separately for this button, e.g. `Button: Toggle Playback`_. -.. code-block:: yaml - +```yml input_devices: VolumeRotator: type: RotaryEncoder @@ -240,54 +221,51 @@ regular button entry separately for this button, e.g. `Button: Toggle Playback`_ on_rotate_counter_clockwise: alias: change_volume args: -5 +``` -Rotary Encoder: Previous/Next Song -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Rotary Encoder: Previous/Next Song From the previous recipe, simply replace the actions to have a rotary encoder to step through the playlist: -.. code-block:: yaml - +```yml ... actions: on_rotate_clockwise: alias: next_song on_rotate_counter_clockwise: alias: prev_song +``` - -Output devices --------------- +## Output devices Configuring output devices contains 2 aspects: - #. Define the the output device. Available output devices can be found in :class:`components.gpio.gpioz.core.output_devices`. - #. Connect the device to some Jukebox function which then - activates the device on e.g. RFID card read. There are many predefined connections - available. Check them all out in :class:`components.gpio.gpioz.plugin.connectivity` +1. Define the the output device. Available output devices can be found in class `components.gpio.gpioz.core.output_devices`. +2. Connect the device to some Jukebox function which then +activates the device on e.g. RFID card read. There are many predefined connections +available. Check them all out in class `components.gpio.gpioz.plugin.connectivity` -.. note:: There are two different types of buzzers: +**Note:** There are two different types of buzzers: - Active buzzer: - These buzzers make a single-frequency beep sound when a constant voltage is applied. A common module is - the KY-012. These buzzers must be mapped to :class:`Buzzer `. +_Active buzzer_ - Passive buzzer: - These buzzers must be used with a PWM signal but then can emit different frequency beeps. This is all handled - by us. A common module is the KY-006. These buzzers *must* be mapped to :class:`TonalBuzzer ` +These buzzers make a single-frequency beep sound when a constant voltage is applied. A common module is +the KY-012. These buzzers must be mapped to class `components.gpio.gpioz.core.output_devices.Buzzer`. - For many connection function is does not matter if a :class:`Buzzer ` - or a :class:`TonalBuzzer ` is connected. - The connection function takes care of the differences internally - as long as the class matches the physical - hardware device! +_Passive buzzer_ +These buzzers must be used with a PWM signal but then can emit different frequency beeps. This is all handled +by us. A common module is the KY-006. These buzzers _must_ be mapped to class `components.gpio.gpioz.core.output_devices.TonalBuzzer` -Status LED -^^^^^^^^^^^^^^ +For many connection function is does not matter if a class `components.gpio.gpioz.core.output_devices.Buzzer` +or a class `components.gpio.gpioz.core.output_devices.TonalBuzzer` is connected. +The connection function takes care of the differences internally - as long as the class matches the physical +hardware device! -An LED that lights up when the Jukebox service is operational. +### Status LED -.. code-block:: yaml +An LED that lights up when the Jukebox service is operational. +```yml output_devices: StatusLED: type: LED @@ -295,10 +273,11 @@ An LED that lights up when the Jukebox service is operational. - gpio.gpioz.plugin.connectivity.register_status_led_callback kwargs: pin: 17 +``` As with the input devices, every output device requires a unique, but freely chosen name - here ``StatusLED``. The parameter ``type`` directly matches the GPIO output device class, in this case -:class:`LED `. +class ``. The parameters in ``kwargs`` relate to the class initialization parameters. The ``connect`` option is a list of functions to call to connect this device with a function inside @@ -307,13 +286,11 @@ the Jukebox. An output device can be used by multiple functions. .. important:: You cannot set the class initialization parameters :attr:`pin_factory` or :attr:`name` from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. -Card Read Buzzer -^^^^^^^^^^^^^^^^^^ +### Card Read Buzzer Sound a Piezzo Buzzer once when a card swipe has been detected. For unknown cards, sound it 3 times. -.. code-block:: yaml - +```yml output_devices: RfidBuzzer: type: Buzzer @@ -321,17 +298,15 @@ Sound a Piezzo Buzzer once when a card swipe has been detected. For unknown card - gpio.gpioz.plugin.connectivity.register_rfid_callback kwargs: pin: 12 +``` -Card Read + Volume + Status Buzzer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Card Read + Volume + Status Buzzer Extend the card read buzzer to also sound one long beep after completed boot up and two beeps on shutdown. On top sound a short beep when minimum or maximum volume is reached. The only difference is the two additional connection functions. - -.. code-block:: yaml - +```yml output_devices: RfidBuzzer: type: Buzzer @@ -341,15 +316,14 @@ The only difference is the two additional connection functions. - gpio.gpioz.plugin.connectivity.register_volume_buzzer_callback kwargs: pin: 12 +``` -Tonal Status Buzzer -^^^^^^^^^^^^^^^^^^^^^^ +### Tonal Status Buzzer Have an active buzzer play a 4 note melody on startup and a 3 note melody on closing down. Use the same buzzer to beep on RFID card swipes. -.. code-block:: yaml - +```yml output_devices: RfidBuzzer: type: TonalBuzzer @@ -358,15 +332,13 @@ Use the same buzzer to beep on RFID card swipes. - gpio.gpioz.plugin.connectivity.register_rfid_callback kwargs: pin: 12 +``` +### Card Read LED -Card Read LED -^^^^^^^^^^^^^^^^^^ - -Just like `Card Read Buzzer`_, but flash a LED instead of buzzing a sound. The difference is the output device type. - -.. code-block:: yaml +Just like `Card Read Buzzer`, but flash a LED instead of buzzing a sound. The difference is the output device type. +```yml output_devices: RfidLED: type: LED @@ -374,48 +346,44 @@ Just like `Card Read Buzzer`_, but flash a LED instead of buzzing a sound. The d - gpio.gpioz.plugin.connectivity.register_rfid_callback kwargs: pin: 12 +``` -Volume LED -^^^^^^^^^^^^ +### Volume LED Have a LED change it's brightness to reflect the current volume level. It also flashes when minimum or maximum volume level is reached. -.. code-block:: yaml - +```yml output_devices: VolumeLED: type: PWMLED connect: gpio.gpioz.plugin.connectivity.register_volume_led_callback kwargs: pin: 18 +``` -Color Volume LED -^^^^^^^^^^^^^^^^^^ +### Color Volume LED Have an RGBLED change it's color to reflect the current volume level. It also flashes when minimum or maximum volume level is reached. RGBLED's can be found as modules, e.g. KY-016 or KY-009, or as individual components from any electronics shop. -.. code-block:: yaml - +```yml output_devices: VolumeLED: type: RGBLED connect: gpio.gpioz.plugin.connectivity.register_volume_rgbled_callback kwargs: pin: 18 +``` - -Bluetooth audio output LED -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +### Bluetooth audio output LED Indicates the current audio output sink. LED is off when audio sink is primary sink, and on when audio sink is secondary sink (e.g. a bluetooth headset). When sink toggle fails, LED blinks 3 times. -.. code-block:: yaml - +```yml output_devices: HeadsetConnected: type: LED @@ -423,42 +391,37 @@ on when audio sink is secondary sink (e.g. a bluetooth headset). When sink toggl - gpio.gpioz.plugin.connectivity.register_audio_sink_change_callback kwargs: pin: 27 +``` - -Developer options ---------------------- +## Developer options For developers there are 2 options. Both replace the pin factory used by GPIOZero. -Use Mock Pins -^^^^^^^^^^^^^^^ +### Use Mock Pins -Using GPIOZero `Mock pins `_, +Using GPIOZero [Mock pins](https://gpiozero.readthedocs.io/en/stable/api_pins.html#mock-pins), allows to do function development on an arbitrary machine. If you have -configured the :ref:`Mock RFID Reader `, +configured the [Mock RFID Reader](../developers/rfid/mock_reader.md), the GPIO input and output devices are added to the GUI. Simply change the header in the configuration file to: -.. code-block:: yaml - +```yml pin_factory: type: mock.MockFactory +``` -.. image:: mock_gpio.png - :width: 80 % - :align: center +![Mock GPIO](mock_gpio.png) -Use Remote Pins -^^^^^^^^^^^^^^^^^^ +### Use Remote Pins -Using `GPIOZero's remote pins `_ +Using [GPIOZero's remote pins](https://gpiozero.readthedocs.io/en/stable/remote_gpio.html) allows to run the Jukebox code on a single machine and have the GPIO happen on a RPi board. See the GPIOZero documentation how to set it up. Simply change the header in the configuration file to enable it. Host is the IP address of your RPi board. -.. code-block:: yaml - +```yml pin_factory: type: pigpio.PiGPIOFactory pigpio.PiGPIOFactory: kwargs: host: 192.168.178.32 +``` From a1c6a4aa1b5a29666f954d338324e480a8561421 Mon Sep 17 00:00:00 2001 From: Simon Date: Thu, 21 Dec 2023 00:05:53 +0100 Subject: [PATCH 2/4] add wsl --- .../developers/development-environment.md | 22 ++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/documentation/developers/development-environment.md b/documentation/developers/development-environment.md index 9abefbee0..249f6263c 100644 --- a/documentation/developers/development-environment.md +++ b/documentation/developers/development-environment.md @@ -1,12 +1,13 @@ # Development Environment - - You have 3 development options. Each option has its pros and cons. To interact with GPIO or other hardware, it's required to develop directly on a Raspberry Pi. For general development of Python code (Jukebox) or JavaScript (Webapp), we recommend Docker. Developing on your local machine (Linux, Mac, Windows) works as well and requires all dependencies to be installed locally. -* [Develop in Docker](#develop-in-docker) -* [Develop on Raspberry Pi](#develop-on-raspberry-pi) -* [Develop on local machine](#develop-on-local-machine) +- [Development Environment](#development-environment) + - [Develop in Docker](#develop-in-docker) + - [Develop on Raspberry Pi](#develop-on-raspberry-pi) + - [Steps to install](#steps-to-install) + - [Develop on local machine](#develop-on-local-machine) + - [Using WSL](#using-wsl) ## Develop in Docker @@ -55,3 +56,14 @@ pip install pyzmq ``` You will have to start Jukebox core application and the WebUI separately. The MPD usually runs as a service. + +### Using WSL + +You can also use WSL on Windows 10 or 11. This section describes how to use WSL with Visual Studio Code. + +1. Install a Debian or Ubuntu image from Microsoft Store +2. Install the extension [Remote Explorer](https://marketplace.visualstudio.com/items?itemName=ms-vscode.remote-explorer) in Visual Studio Code +3. Select Remote Explorer +4. Select "WSL Targets" +5. Right-click on the previously installed WSL image and select "Connect in Current/New Window" +6. Follow the instructions from above From e264a2850e5f60371b91d01c3423251176dbf914 Mon Sep 17 00:00:00 2001 From: Simon Date: Thu, 21 Dec 2023 00:06:53 +0100 Subject: [PATCH 3/4] fix markdown warnings --- documentation/builders/audio.md | 2 +- documentation/builders/card-database.md | 5 +++-- documentation/builders/configuration.md | 1 + documentation/builders/installation.md | 2 +- documentation/builders/troubleshooting.md | 2 +- documentation/developers/coreapps.md | 1 - documentation/developers/developer-issues.md | 12 ++++++------ documentation/developers/docker.md | 11 +++++------ documentation/developers/known-issues.md | 2 +- documentation/developers/status.md | 2 +- 10 files changed, 20 insertions(+), 20 deletions(-) diff --git a/documentation/builders/audio.md b/documentation/builders/audio.md index 4fd82e457..54bfe72bf 100644 --- a/documentation/builders/audio.md +++ b/documentation/builders/audio.md @@ -105,7 +105,7 @@ Directly edit `jukebox.yaml` following the steps: [Best practice procedure](conf The optional processing stages *Equalizer* and *Mono down mix* are realized by PulseAudio plugins. The processing chain is -``` +```text player --> mono mix --> equalizer --> hardware sink ``` diff --git a/documentation/builders/card-database.md b/documentation/builders/card-database.md index 67dbf5dae..340933750 100644 --- a/documentation/builders/card-database.md +++ b/documentation/builders/card-database.md @@ -33,6 +33,7 @@ using the alias option: ``` > [!NOTE] +> > * Remember card ids must be strings! So, quote them! > * *args* must be a **list** of arguments to be passed! Even if ony a single argument is @@ -44,7 +45,7 @@ not always work. In addition to the RPC commands, these options may be specified for every card -#### ignore_card_removal_action: true \| false (default: false) +### ignore_card_removal_action: true \| false (default: false) Only applies when using a place-capable reader and *place_not_swipe* is *true*. This option is ignored otherwise, so it does not hurt. @@ -58,7 +59,7 @@ timer ignore_card_removal_action: true ``` -#### ignore_same_id_delay: true \| false (default: false) +### ignore_same_id_delay: true \| false (default: false) Override the `same_id_delay` parameter from the reader configuration for this card. If true, the `same_id_delay` for this card is treated diff --git a/documentation/builders/configuration.md b/documentation/builders/configuration.md index f09e8098d..dba2da7dc 100644 --- a/documentation/builders/configuration.md +++ b/documentation/builders/configuration.md @@ -11,6 +11,7 @@ For several aspects we have [configuration tools](../developers/coreapps.md#conf * [Audio Configuration](./audio.md#audio-configuration) * [RFID Reader Configuration](../developers/rfid/basics.md#reader-configuration) +* [GPIO Recipes](./gpio.md) Even after running the tools, certain aspects can only be changed by modifying the configuration files directly. diff --git a/documentation/builders/installation.md b/documentation/builders/installation.md index 756e2a03c..945368480 100644 --- a/documentation/builders/installation.md +++ b/documentation/builders/installation.md @@ -59,7 +59,7 @@ You will need a terminal, like PuTTY for Windows or the Terminal app for Mac to 6. Insert the following content, update your country, Wifi credentials and save the file. - ``` + ```text country=DE ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev update_config=1 diff --git a/documentation/builders/troubleshooting.md b/documentation/builders/troubleshooting.md index a83384ec5..d68230f81 100644 --- a/documentation/builders/troubleshooting.md +++ b/documentation/builders/troubleshooting.md @@ -25,7 +25,7 @@ shutdown of the service. The logs are also available via the Web Server: -``` +```text http://ip.of.your.box/logs ``` diff --git a/documentation/developers/coreapps.md b/documentation/developers/coreapps.md index 1b5b746aa..f1402683d 100644 --- a/documentation/developers/coreapps.md +++ b/documentation/developers/coreapps.md @@ -58,7 +58,6 @@ The list of available commands is fetched from the running Jukebox service. The tool can also be used to send commands directly, when passing a `-c` argument, e.g. `./run_rpc_tool.py -c host.shutdown`. - ### Publicity Sniffer **Scriptname:** [run_publicity_sniffer.py](../../src/jukebox/run_publicity_sniffer.py) diff --git a/documentation/developers/developer-issues.md b/documentation/developers/developer-issues.md index c8dd3b6c3..bcb4d491a 100644 --- a/documentation/developers/developer-issues.md +++ b/documentation/developers/developer-issues.md @@ -21,11 +21,11 @@ Creating an optimized production build... FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory ``` -**Reason** +#### Reason Not enough memory for Node -**Solution** +#### Solution Prior to building set the node memory environment variable. @@ -50,11 +50,11 @@ $ cd src/webapp $ ./run_rebuild.sh ``` -**Changing Swap Size** +#### 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. -``` +```bash 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 @@ -76,11 +76,11 @@ The build failed because the process exited too early. This probably means the system ran out of memory or someone called 'kill -9' on the process. ``` -**Reason** +#### Reason Node tried to allocate more memory than available on the system. -**Solution** +#### Solution Adjust the node memory variable as described in [JavaScript heap out of memory](#javascript-heap-out-of-memory). But make sure to allocate less memory than the available memory. If that is not sufficient, increase the swap file size of your system and try again. diff --git a/documentation/developers/docker.md b/documentation/developers/docker.md index 39518e248..79c2ada2a 100644 --- a/documentation/developers/docker.md +++ b/documentation/developers/docker.md @@ -139,7 +139,6 @@ Error starting userland proxy: listen tcp4 0.0.0.0:6600: bind: address already i Read these threads for details: [thread 1](https://unix.stackexchange.com/questions/456909/socket-already-in-use-but-is-not-listed-mpd) and [thread 2](https://stackoverflow.com/questions/5106674/error-address-already-in-use-while-binding-socket-with-address-but-the-port-num/5106755#5106755) - ## Test & Develop The Dockerfile is defined to start all Phoniebox related services. @@ -236,31 +235,31 @@ $ docker run -it --rm \ ### Resources -**Mac** +#### Mac * * * -**Windows** +#### Windows * * * * -**Audio** +#### Audio * * * -**MPD** +#### MPD * * * -**ZMQ** +#### ZMQ * diff --git a/documentation/developers/known-issues.md b/documentation/developers/known-issues.md index 1460c1cb4..817298c60 100644 --- a/documentation/developers/known-issues.md +++ b/documentation/developers/known-issues.md @@ -6,7 +6,7 @@ To speed up the Docker build process, we are distributing pre-build versions of Add `build-essential` to be installed additionally with `apt-get`. Additionally, replace the command to download the pre-built library with the following command. -``` +```docker # Compile ZMQ RUN cd ${HOME} && mkdir ${ZMQ_TMP_DIR} && cd ${ZMQ_TMP_DIR}; \ wget https://github.com/zeromq/libzmq/releases/download/v${ZMQ_VERSION}/zeromq-${ZMQ_VERSION}.tar.gz -O libzmq.tar.gz; \ diff --git a/documentation/developers/status.md b/documentation/developers/status.md index eac874608..2fb92897f 100644 --- a/documentation/developers/status.md +++ b/documentation/developers/status.md @@ -227,7 +227,7 @@ Topics marked _in progress_ are already in the process of implementation by comm - [x] Enable/Disable Auto-Hotspot - [x] `run_npm_build` script - [x] Must consider `export NODE_OPTIONS=--max-old-space-size=512` -- [ ] Upload audio files via WebUI https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/2138 +- [ ] Upload audio files via WebUI ## Installation Procedure From 682ba8a5fd7e78d9acc6ea63c750398eb209bb10 Mon Sep 17 00:00:00 2001 From: Simon Date: Thu, 21 Dec 2023 23:24:56 +0100 Subject: [PATCH 4/4] improve docs (remove rst stuff) --- documentation/README.md | 8 +- documentation/builders/gpio.md | 373 +++++++++--------- documentation/builders/rpc-commands.md | 101 ++--- documentation/builders/system.md | 6 +- documentation/builders/troubleshooting.md | 6 +- documentation/developers/rfid/basics.md | 20 +- documentation/developers/rfid/mfrc522_spi.md | 17 +- documentation/developers/rfid/mock_reader.md | 12 +- documentation/developers/rfid/pn532_i2c.md | 4 +- .../developers/rfid/template_reader.md | 18 +- 10 files changed, 286 insertions(+), 279 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index 71ef9010f..b10941a55 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -39,8 +39,12 @@ project check out the [documentation of Version 2](https://github.com/MiczFlor/R ### Where are we? Help wanted! -The initial proof-of-concept phase has been left behind and there is quite some functionality available already. -This is still an ongoing process but the WebUI and RFID-triggered playback of local files work. +Version 3 has reached a mature state and will soon be the default version. +However, some features may still be missing. Please check the [Feature Status](./developers/status.md), if YOUR feature is already implemented. + +> ![NOTE] If version 3 has all the features you need, we recommend using Version 3. + +If there is a feature missing, please open an issue. Features/files from version 2.X will only be copied/merged once they can be integrated and tested. If you don't find your v2.X contributions, it doesn't mean they are obsolete. Things will be integrated step by step. diff --git a/documentation/builders/gpio.md b/documentation/builders/gpio.md index feeb907ef..37622edc0 100644 --- a/documentation/builders/gpio.md +++ b/documentation/builders/gpio.md @@ -6,16 +6,15 @@ The GPIO module needs to be enabled in your main configuration file ``shared/set this entry and modify it accordingly: ```yml - gpioz: - enable: true - config_file: ../../shared/settings/gpio.yaml +gpioz: + enable: true + config_file: ../../shared/settings/gpio.yaml ``` The GPIO configuration itself is stored in a separate file, in this case ``../../shared/settings/gpio.yaml``. The GPIO module uses [GPIOZero](https://gpiozero.readthedocs.io/) as a backend to access the RPi's GPIO pins. -It's a wrapper to integrate GPIOZero into the Jukebox's API, allowing a YAML based configuration and providing -helpful error messages on misconfiguration. +It's a wrapper to integrate GPIOZero into the Jukebox's API, allowing a YAML based configuration and providing helpful error messages on misconfiguration. ## Pin Numbering @@ -27,15 +26,15 @@ The pin numbering is the BCM pin numbering, as is the The GPIOZ configuration file has the following structure: ```yml - pin_factory: - type: rpigpio.RPiGPIOFactory - output_devices: - ... - input_devices: - ... +pin_factory: + type: rpigpio.RPiGPIOFactory +output_devices: + ... +input_devices: + ... ``` -There is no need to touch the header, but some `Developer options` can be found there. +There is no need to touch the header, but some [Developer options](#developer-options) can be found there. A file with examples can be found in ``resources/default-settings/gpio.yaml``. Below you will find easy to adapt recipes for various configuration snippets. @@ -55,14 +54,14 @@ just the same as for assigning card actions. A button to toggle music playback on single press: ```yml - input_devices: - TogglePlayback: - type: Button - kwargs: - pin: 13 - actions: - on_press: - alias: toggle +input_devices: + TogglePlayback: + type: Button + kwargs: + pin: 13 + actions: + on_press: + alias: toggle ``` Each device instantiation must be uniquely named, here ``TogglePlayback``. The name can be freely chosen, as @@ -72,8 +71,9 @@ The parameter ``type`` directly matches the GPIO input device class, in this cas class `LED `. With ``kwargs`` you can set all the class initialization parameters, which relate directly to the class' initialization parameters. -**Important:** You cannot set the class initialization parameters :attr:`pin_factory` or :attr:`name` - from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. +> [!IMPORTANT] +> You cannot set the class initialization parameters attribute `pin_factory` or attribute `name` +> from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. Usually, only the pin(s) are mandatory parameters. In the section ``actions``, the RPC commands are linked, either as alias (i.e. shortcut) or full [RPC Commands](rpc-commands.md) specification. @@ -94,17 +94,17 @@ the RPi looks: A button to increase the volume by 5 steps every 0.75 seconds as long as it is pressed: ```yml - input_devices: - IncreaseVolume: - type: Button - kwargs: - pin: 13 - hold_time: 0.75 - hold_repeat: True - actions: - on_press: - alias: change_volume - args: +5 +input_devices: + IncreaseVolume: + type: Button + kwargs: + pin: 13 + hold_time: 0.75 + hold_repeat: True + actions: + on_press: + alias: change_volume + args: +5 ``` ### Button: Shutdown @@ -112,15 +112,15 @@ A button to increase the volume by 5 steps every 0.75 seconds as long as it is p A button to shutdown the Jukebox if it is pressed for more than 3 seconds. Note the different ``type`` here! ```yml - input_devices: - IncreaseVolume: - type: LongPressButton - kwargs: - pin: 3 - hold_time: 3 - actions: - on_press: - alias: shutdown +input_devices: + IncreaseVolume: + type: LongPressButton + kwargs: + pin: 3 + hold_time: 3 + actions: + on_press: + alias: shutdown ``` ### Button: Dual Action @@ -128,74 +128,75 @@ A button to shutdown the Jukebox if it is pressed for more than 3 seconds. Note A button to act differently on short and long presses. Go to previous song on single short press, start playlist from the beginning on press longer than 1 second. -Note: the short press action is executed on button release since we don't not know how much longer somebody is going -to press the button. The long press action is executed as soon as the hold time has been reached. +> [!NOTE] +> the short press action is executed on button release since we don't not know how much longer somebody is going +> to press the button. The long press action is executed as soon as the hold time has been reached. ```yml - input_devices: - PreviousSong: - type: ShortLongPressButton - kwargs: - pin: 13 - hold_time: 1 - actions: - on_short_press: - alias: prev_song - on_long_press: - alias: replay +input_devices: + PreviousSong: + type: ShortLongPressButton + kwargs: + pin: 13 + hold_time: 1 + actions: + on_short_press: + alias: prev_song + on_long_press: + alias: replay ``` ### TwinButton: Six function beast Use two buttons to encode up to six actions depending on single / dual press and also short / long press. Single button short presses skip to prev/next song, while long presses decrease/increase the volume. -Here we also use make use of :attr:`hold_repeat`, to have the volume continue to change for as long as we hold the button -down. Twin press toggle pause or changed the audio output sink from speakers to headset. The attribute :attr:`hold_repeat` +Here we also use make use of attribute `hold_repeat`, to have the volume continue to change for as long as we hold the button +down. Twin press toggle pause or changed the audio output sink from speakers to headset. The attribute attribute `hold_repeat` only applies to single press actions, never to dual press actions. ```yml - input_devices: - SixActionBeast: - type: TwinButton - kwargs: - a: 12 - b: 13 - hold_repeat: true - actions: - on_short_press_a: - alias: prev_song - on_short_press_b: - alias: next_song - on_short_press_ab: - alias: toggle - on_long_press_a: - alias: change_volume - args: -3 - on_long_press_b: - alias: change_volume - args: 3 - on_long_press_ab: - alias: toggle_output +input_devices: + SixActionBeast: + type: TwinButton + kwargs: + a: 12 + b: 13 + hold_repeat: true + actions: + on_short_press_a: + alias: prev_song + on_short_press_b: + alias: next_song + on_short_press_ab: + alias: toggle + on_long_press_a: + alias: change_volume + args: -3 + on_long_press_b: + alias: change_volume + args: 3 + on_long_press_ab: + alias: toggle_output ``` With a TwinButton not all functions need to be assigned. A button that only does prev/next song and causes as shutdown only on dual press with a minimum hold time of 2 seconds looks like this: ```yml - input_devices: - CombinationButton: - type: TwinButton - kwargs: - a: 12 - b: 13 - hold_time: 2 - actions: - on_short_press_a: - alias: prev_song - on_short_press_b: - alias: next_song - on_long_press_ab: - alias: toggle_output +input_devices: + CombinationButton: + type: TwinButton + kwargs: + a: 12 + b: 13 + hold_time: 2 + actions: + on_short_press_a: + alias: prev_song + on_short_press_b: + alias: next_song + on_long_press_ab: + alias: toggle_output ``` ### Rotary Encoder: Volume Control @@ -205,22 +206,22 @@ It has four pins, typically labelled DT, CLK, SW, GND. Connect GND to ground. Co RPi with a 1 kOhm resistor each - these are pins ``a`` in ``b`` in the configuration. If later the rotation direction does not match, simply swap the pins in the configuration file. The pin SW (for switch) is not always present. It is a button when the rotary encoder is pressed from the top. Configure a -regular button entry separately for this button, e.g. `Button: Toggle Playback`_. +regular button entry separately for this button, e.g. [Button Toggle Playback](#button-toggle-playback). ```yml - input_devices: - VolumeRotator: - type: RotaryEncoder - kwargs: - a: 5 - b: 6 - actions: - on_rotate_clockwise: - alias: change_volume - args: 5 - on_rotate_counter_clockwise: - alias: change_volume - args: -5 +input_devices: + VolumeRotator: + type: RotaryEncoder + kwargs: + a: 5 + b: 6 + actions: + on_rotate_clockwise: + alias: change_volume + args: 5 + on_rotate_counter_clockwise: + alias: change_volume + args: -5 ``` ### Rotary Encoder: Previous/Next Song @@ -245,59 +246,64 @@ Configuring output devices contains 2 aspects: activates the device on e.g. RFID card read. There are many predefined connections available. Check them all out in class `components.gpio.gpioz.plugin.connectivity` -**Note:** There are two different types of buzzers: +### Buzzers + +There are two different types of buzzers: -_Active buzzer_ +#### Active buzzer These buzzers make a single-frequency beep sound when a constant voltage is applied. A common module is the KY-012. These buzzers must be mapped to class `components.gpio.gpioz.core.output_devices.Buzzer`. -_Passive buzzer_ +#### Passive buzzer + These buzzers must be used with a PWM signal but then can emit different frequency beeps. This is all handled by us. A common module is the KY-006. These buzzers _must_ be mapped to class `components.gpio.gpioz.core.output_devices.TonalBuzzer` +#### General + For many connection function is does not matter if a class `components.gpio.gpioz.core.output_devices.Buzzer` or a class `components.gpio.gpioz.core.output_devices.TonalBuzzer` is connected. -The connection function takes care of the differences internally - as long as the class matches the physical -hardware device! +The connection function takes care of the differences internally - as long as the class matches the physical hardware device! ### Status LED An LED that lights up when the Jukebox service is operational. ```yml - output_devices: - StatusLED: - type: LED - connect: - - gpio.gpioz.plugin.connectivity.register_status_led_callback - kwargs: - pin: 17 +output_devices: + StatusLED: + type: LED + connect: + - gpio.gpioz.plugin.connectivity.register_status_led_callback + kwargs: + pin: 17 ``` As with the input devices, every output device requires a unique, but freely chosen name - here ``StatusLED``. The parameter ``type`` directly matches the GPIO output device class, in this case -class ``. +class `components.gpio.gpioz.core.output_devices.LED`. The parameters in ``kwargs`` relate to the class initialization parameters. The ``connect`` option is a list of functions to call to connect this device with a function inside the Jukebox. An output device can be used by multiple functions. -.. important:: You cannot set the class initialization parameters :attr:`pin_factory` or :attr:`name` - from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. +> [!IMPORTANT] +> You cannot set the class initialization parameters attribute `pin_factory` or attribute `name` +> from inside ``kwargs``. The name is automatically assigned from the unique name of configuration entry. ### Card Read Buzzer Sound a Piezzo Buzzer once when a card swipe has been detected. For unknown cards, sound it 3 times. ```yml - output_devices: - RfidBuzzer: - type: Buzzer - connect: - - gpio.gpioz.plugin.connectivity.register_rfid_callback - kwargs: - pin: 12 +output_devices: + RfidBuzzer: + type: Buzzer + connect: + - gpio.gpioz.plugin.connectivity.register_rfid_callback + kwargs: + pin: 12 ``` ### Card Read + Volume + Status Buzzer @@ -307,15 +313,15 @@ On top sound a short beep when minimum or maximum volume is reached. The only difference is the two additional connection functions. ```yml - output_devices: - RfidBuzzer: - type: Buzzer - connect: - - gpio.gpioz.plugin.connectivity.register_rfid_callback - - gpio.gpioz.plugin.connectivity.register_status_buzzer_callback - - gpio.gpioz.plugin.connectivity.register_volume_buzzer_callback - kwargs: - pin: 12 +output_devices: + RfidBuzzer: + type: Buzzer + connect: + - gpio.gpioz.plugin.connectivity.register_rfid_callback + - gpio.gpioz.plugin.connectivity.register_status_buzzer_callback + - gpio.gpioz.plugin.connectivity.register_volume_buzzer_callback + kwargs: + pin: 12 ``` ### Tonal Status Buzzer @@ -324,14 +330,14 @@ Have an active buzzer play a 4 note melody on startup and a 3 note melody on clo Use the same buzzer to beep on RFID card swipes. ```yml - output_devices: - RfidBuzzer: - type: TonalBuzzer - connect: - - gpio.gpioz.plugin.connectivity.register_status_tonalbuzzer_callback - - gpio.gpioz.plugin.connectivity.register_rfid_callback - kwargs: - pin: 12 +output_devices: + RfidBuzzer: + type: TonalBuzzer + connect: + - gpio.gpioz.plugin.connectivity.register_status_tonalbuzzer_callback + - gpio.gpioz.plugin.connectivity.register_rfid_callback + kwargs: + pin: 12 ``` ### Card Read LED @@ -339,58 +345,55 @@ Use the same buzzer to beep on RFID card swipes. Just like `Card Read Buzzer`, but flash a LED instead of buzzing a sound. The difference is the output device type. ```yml - output_devices: - RfidLED: - type: LED - connect: - - gpio.gpioz.plugin.connectivity.register_rfid_callback - kwargs: - pin: 12 +output_devices: + RfidLED: + type: LED + connect: + - gpio.gpioz.plugin.connectivity.register_rfid_callback + kwargs: + pin: 12 ``` ### Volume LED -Have a LED change it's brightness to reflect the current volume level. It also flashes when minimum or maximum -volume level is reached. +Have a LED change it's brightness to reflect the current volume level. It also flashes when minimum or maximum volume level is reached. ```yml - output_devices: - VolumeLED: - type: PWMLED - connect: gpio.gpioz.plugin.connectivity.register_volume_led_callback - kwargs: - pin: 18 +output_devices: + VolumeLED: + type: PWMLED + connect: gpio.gpioz.plugin.connectivity.register_volume_led_callback + kwargs: + pin: 18 ``` ### Color Volume LED Have an RGBLED change it's color to reflect the current volume level. It also flashes when minimum or maximum -volume level is reached. RGBLED's can be found as modules, e.g. KY-016 or KY-009, or as individual components from any -electronics shop. +volume level is reached. RGBLED's can be found as modules, e.g. KY-016 or KY-009, or as individual components from any electronics shop. ```yml - output_devices: - VolumeLED: - type: RGBLED - connect: gpio.gpioz.plugin.connectivity.register_volume_rgbled_callback - kwargs: - pin: 18 +output_devices: + VolumeLED: + type: RGBLED + connect: gpio.gpioz.plugin.connectivity.register_volume_rgbled_callback + kwargs: + pin: 18 ``` ### Bluetooth audio output LED Indicates the current audio output sink. LED is off when audio sink is primary sink, and -on when audio sink is secondary sink (e.g. a bluetooth headset). When sink toggle fails, LED blinks -3 times. +on when audio sink is secondary sink (e.g. a bluetooth headset). When sink toggle fails, LED blinks 3 times. ```yml - output_devices: - HeadsetConnected: - type: LED - connect: - - gpio.gpioz.plugin.connectivity.register_audio_sink_change_callback - kwargs: - pin: 27 +output_devices: + HeadsetConnected: + type: LED + connect: + - gpio.gpioz.plugin.connectivity.register_audio_sink_change_callback + kwargs: + pin: 27 ``` ## Developer options @@ -405,8 +408,8 @@ configured the [Mock RFID Reader](../developers/rfid/mock_reader.md), the GPIO input and output devices are added to the GUI. Simply change the header in the configuration file to: ```yml - pin_factory: - type: mock.MockFactory +pin_factory: + type: mock.MockFactory ``` ![Mock GPIO](mock_gpio.png) @@ -419,9 +422,9 @@ happen on a RPi board. See the GPIOZero documentation how to set it up. Simply change the header in the configuration file to enable it. Host is the IP address of your RPi board. ```yml - pin_factory: - type: pigpio.PiGPIOFactory - pigpio.PiGPIOFactory: - kwargs: - host: 192.168.178.32 +pin_factory: + type: pigpio.PiGPIOFactory + pigpio.PiGPIOFactory: + kwargs: + host: 192.168.178.32 ``` diff --git a/documentation/builders/rpc-commands.md b/documentation/builders/rpc-commands.md index 374c27d97..181034f4a 100644 --- a/documentation/builders/rpc-commands.md +++ b/documentation/builders/rpc-commands.md @@ -11,26 +11,26 @@ 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) +1. the function to execute (e.g. play_folder, change_volume) +2. the positional arguments (optional) +3. 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 +```yml +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] +```yml +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. @@ -41,63 +41,64 @@ 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] +```yml +package: player +plugin: ctrl +method: play_card +args: [path/to/folder] +``` -you can simply specify instead : +you can simply specify instead: -.. code-block:: yaml +```yml +alias: play_card +args: [path/to/folder] +``` - 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. +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) +```python +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 +* 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. +```yml +alias: play_card +args: [path/to/folder, True] +``` + +```yml +alias: play_card +args: [path/to/folder] +kwargs: + recursive: True +``` + +```yml +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) diff --git a/documentation/builders/system.md b/documentation/builders/system.md index e981678c0..2f7df8888 100644 --- a/documentation/builders/system.md +++ b/documentation/builders/system.md @@ -10,8 +10,8 @@ The system consists of 4. [Web UI](system.md#web-ui) which is served through an Nginx web server 5. A set of [Configuration Tools](../developers/coreapps.md#configuration-tools) and a set of [Developer Tools](../developers/coreapps.md#developer-tools) -.. note:: The default install puts everything into the users home folder `~/RPi-Jukebox-RFID`. - Another folder might work, but is certainly not tested. +> [!NOTE] The default install puts everything into the users home folder `~/RPi-Jukebox-RFID`. +> Another folder might work, but is certainly not tested. ## Music Player Daemon (MPD) @@ -34,7 +34,7 @@ $ systemctl --user start mpd $ systemctl --user stop mpd ``` -.. important:: Never start or enable the system-wide MPD service with `sudo systemctl start mpd`! +> [!IMPORTANT] Never start or enable the system-wide MPD service with `sudo systemctl start mpd`! To check if MPD is running or has issues, use diff --git a/documentation/builders/troubleshooting.md b/documentation/builders/troubleshooting.md index d68230f81..2f34af083 100644 --- a/documentation/builders/troubleshooting.md +++ b/documentation/builders/troubleshooting.md @@ -58,7 +58,7 @@ shared/logs/errors.log : Only Errors and Warnings For debugging, it is usually very helpful to observe the apps output directly on the console log. -``` bash +```bash # Make sure the Jukebox service is stopped: $ systemctl --user stop jukebox-daemon @@ -77,7 +77,7 @@ It is possible to start the Jukebox with a catch-all debug enabler with a logger Attention: This only emits messages to the console and does not write to the log files! This is more a fallback features: -``` bash +```bash $ cd src/jukebox $ ./run_jukebox.py -vv ``` @@ -94,6 +94,6 @@ gone pear-shaped. Services are restarted automatically when they fail. Things are just not behaving as expected? Time to check the system logs: -``` bash +```bash $ journalctl --user -b -u jukebox-daemon ``` diff --git a/documentation/developers/rfid/basics.md b/documentation/developers/rfid/basics.md index 7d557ed06..27464924b 100644 --- a/documentation/developers/rfid/basics.md +++ b/documentation/developers/rfid/basics.md @@ -16,7 +16,7 @@ behavior can be deactivated for individual cards. ## Reader Types -#### place-capable: +### Place-capable Some readers give a single event signal when the card is placed on the reader. This is sufficient to build a fully-featured Jukebox. @@ -28,7 +28,7 @@ Generally, **not** all [USB-based RFID readers](genericusb.md) are place-capable The known place-capable readers are [RDM6300 Reader](rdm6300.md), [MFRC522 SPI Reader](mfrc522_spi.md) or [PN532 I2C Reader](pn532_i2c.md). -#### Frequency: +### Frequency Readers operate on one of two different frequencies: 125kHz or 13.56 MHz. Make sure to buy compatible cards, RFID stickers or key fobs working with the same frequency as the reader. @@ -44,7 +44,7 @@ settings any time. Some options are not covered by the tool. You may change the file manually. -``` yaml +```yaml rfid: readers: read_00: @@ -60,33 +60,33 @@ rfid: For each reader, there is an entry `read_XX`. -#### module: +### module Indicates the Python package used for this reader. Filled by the RFID configuration tool. -#### config: +### config 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 +### same_id_delay: float \| integer Minimum delay in seconds between 2 card detections before triggering a new action. This is to prevent double triggering or bouncing. -#### place_not_swipe: true \| false +### place_not_swipe: true \| false For place-capable RFID readers enable dual action mode: a start action (e.g. playing) on card placement and card removal action (e.g. pause). -#### card_removal_action: Dictionary +### 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). > [!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. -#### log_ignored_cards: true \| false +### log_ignored_cards: true \| false Log all cards that are ignored due to same_id_delay. This is a option for developers. Don't use it unless you need it for debugging as it has the potential to spam your log files. -#### Second Swipe +### Second Swipe Looking for 'Second Swipe' option? That is part of the Player configuration and not part of the RFID configuration, as the 'Second Swipe' action needs to take into account the player state, which can also be altered through the WebUI. diff --git a/documentation/developers/rfid/mfrc522_spi.md b/documentation/developers/rfid/mfrc522_spi.md index 5dc46aab6..8a04f729e 100644 --- a/documentation/developers/rfid/mfrc522_spi.md +++ b/documentation/developers/rfid/mfrc522_spi.md @@ -6,8 +6,7 @@ RC522 RFID reader via SPI connection. ## Installation -Run the [RFID reader configuration tool](../coreapps.md#RFID-Reader) for guided -installation. +Run the [RFID reader configuration tool](../coreapps.md#RFID-Reader) for guided installation. ## Options @@ -18,11 +17,11 @@ are just routed through to spidev. Have a look at the spidev documentation for details if you really want to use a different SPI bus. The default setup makes most sense for almost everyone. -#### spi_bus *(default=0)* +### spi_bus *(default=0)* The SPI Bus ID. The default bus is 0. For other bus IDs, the RPi also needs to re-configured. For that reason we set this to zero. -#### spi_ce *(default=0)* +### spi_ce *(default=0)* SPI chip enable pin. On default SPI bus 0, this can be @@ -31,26 +30,26 @@ SPI chip enable pin. On default SPI bus 0, this can be For other SPI buses refer to RPi documentation. -#### pin_irq +### pin_irq Mandatory IRQ pin. This can be any GPIO pin. -#### pin_rst *(default=0)* +### pin_rst *(default=0)* Reset pin for hardware reset. This is an optional pin. If not used, - hardware reset will only be performed by power-on-reset. This has been tested on works fine. - you **must** tie the reset pin of the MFRC522 board **high**! -#### mode_legacy *(default=false)* +### mode_legacy *(default=false)* 4-byte-only legacy mode: previously the pirc522 library could only read the lower 4 bytes of a card UID. It can now read 4-byte and full 7-byte UIDs. Legacy mode turns back to the old behaviour. This only makes sense, if you already have an large RFID collection and do not want to re-assign every card. -#### antenna_gain *(default=4)* +### antenna_gain *(default=4)* Antenna gain factor of the RFID reader chip on the MFRC522 board. -#### log_all_cards *(default=false)* +### log_all_cards *(default=false)* If true all card read-outs will be logged, even when card is permanently on reader. Only for debugging. diff --git a/documentation/developers/rfid/mock_reader.md b/documentation/developers/rfid/mock_reader.md index 5daee0ab5..4d5a3ea36 100644 --- a/documentation/developers/rfid/mock_reader.md +++ b/documentation/developers/rfid/mock_reader.md @@ -17,10 +17,10 @@ If you [mock the GPIO pins](../../../src/jukebox/components/gpio/gpioz/README.rs > Replacing the TK lib in Anaconda's environment with the system `libtk`. > However, this depends on an exact version match of the `libtk`. > ->``` bash ->cd /path/to/anaconda3/envs/rpi/lib ->mv ./libtk8.6.so ./libtk8.6.so.bak ->ln -s /usr/lib/x86_64-linux-gnu/libtk8.6.so libtk8.6.so ->``` +> ``` bash +> cd /path/to/anaconda3/envs/rpi/lib +> mv ./libtk8.6.so ./libtk8.6.so.bak +> ln -s /usr/lib/x86_64-linux-gnu/libtk8.6.so libtk8.6.so +> ``` > ->An alternative is to simply use Python's `venv` module to create a virtual environment. This uses your systems Python version and thus will work with your system `libtk`. It might not be the RPi's Python version - but that should not matter in most cases. +> An alternative is to simply use Python's `venv` module to create a virtual environment. This uses your systems Python version and thus will work with your system `libtk`. It might not be the RPi's Python version - but that should not matter in most cases. diff --git a/documentation/developers/rfid/pn532_i2c.md b/documentation/developers/rfid/pn532_i2c.md index 819f051f3..d60cb2e54 100644 --- a/documentation/developers/rfid/pn532_i2c.md +++ b/documentation/developers/rfid/pn532_i2c.md @@ -24,8 +24,8 @@ range and no problem with various types of cards and stickers. You can usually pick up a board at -> - -> - +* +* ## Board Connections diff --git a/documentation/developers/rfid/template_reader.md b/documentation/developers/rfid/template_reader.md index 6a7a8b0c3..5b8458691 100644 --- a/documentation/developers/rfid/template_reader.md +++ b/documentation/developers/rfid/template_reader.md @@ -24,19 +24,19 @@ Your new reader is a python subpackage with these three mandatory files 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 + +- README.md <-- The Readme ``` -The module documentation must go into a separate file, called README.ME. +The module documentation must go into a separate file, called README.md. ## Conventions -- Single reader per directory / subpackage -- reader module directory name and reader module file name must be +- 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 +- Obviously awesome_reader will be replaced with something more descriptive. The naming scheme for the subpackage is - - \\_\\_\ - - e.g. generic_usb/generic_usb.py - - e.g. pn532_spi/pn532_spi.py - - ... + - \\_\\_\ + - e.g. generic_usb/generic_usb.py + - e.g. pn532_spi/pn532_spi.py + - ...