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