Finish userguide without references

docs/userguide/bluetooth.md

@@ -0,0 +1,63 @@
+# Bluetooth
+
+## Bluetooth Audio Buttons
+
+When a bluetooth sound device (headphone, speakers) connects attempt to
+automatically listen to it\'s buttons (play, next, etc.)
+
+The bluetooth input device name is matched automatically from the
+bluetooth sound card device name. During boot up, it is uncertain if the
+bluetooth device connects first, or the Jukebox service is ready first.
+Therefore, after service initialization, already connected bluetooth
+sound devices are scanned and an attempt is made to find their input
+buttons.
+
+> [!NOTE]
+> If the automatic matching fails, there currently is no manual configuration option. Open an issue ticket if you have problems with the automatic matching.
+
+Button key codes are standardized and by default the buttons play,
+pause, next song, previous song are recognized. Volume up/down is
+handled independently from this module by PulseAudio and the bluetooth
+audio transmission protocol.
+
+The module needs to be enabled in the main configuration file with:
+
+``` yaml
+bluetooth_audio_buttons:
+  enable: true
+```
+
+### Custom key bindings
+
+You may change or extend the actions assigned to a button in the
+configuration. If the configuration contains a block \'mapping\', the
+default button-action mapping is *completely* replaced with the new
+mapping. The definitions for each key looks like
+`key-code: {rpc_command_definition}`. The RPC command follows the
+regular RPC command rules as defined in
+[RPC Commands](userguide/rpc_commands.md).
+
+``` yaml
+bluetooth_audio_buttons:
+  enable: true
+  mapping:
+    # Play & pause both map to toggle which is also the usual behaviour of headsets
+    200:
+      alias: toggle
+    201:
+      alias: toggle
+    # Re-map next song button, to set defined output volume (for some fun)
+    163:
+      package: volume
+      plugin: ctrl
+      method: set_volume
+      args: [18]
+    # Re-map prev song button to shutdown
+    165:
+      alias: shutdown
+```
+
+Key codes can be found in the log files. Press the various buttons on
+your headset, while watching the logs with e.g.
+`tail -f shared/logs/app.log`. Look for entries like
+`No callback registered for button ...`.

docs/userguide/card-database.md

@@ -0,0 +1,101 @@
+# Card Database
+
+In the card database, an RPC command is assigned to every card.
+
+This RPC command is called every time when the card is swiped (or
+placed) on the reader. Every RPC callable function can be called. See
+[RPC Commands](userguide/rpc_commands.md) for an introduction.
+
+The card database is stored in `shared\settings\cards.yaml`. Here are
+some examples for RPC command assignments to cards \'0001\' to \'0003\'
+using the alias option:
+
+> [!IMPORTANT]
+> Card IDs **must** be strings! So, be sure to quote numbers!
+
+``` yaml
+'0001':
+    # A RPC command using the alias definition without any arguments
+    # Here: pause playback
+    alias: pause
+'0002':
+    # A RPC command using the alias definition with one arguments
+    # Here: Trigger music playback through the card interface
+    alias: play_card
+    args: [path/to/folder]
+'0003':
+    # A RPC command using keyword arguments. Args and kwargs can also be mixed.
+    # Args and Kwargs translate directly into the function python call
+    # Some as in '0002' but using kwargs
+    alias: play_card
+    kwargs:
+        folder: path/to/folder
+```
+
+> [!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
+passed. So, use *args: \[value\]*. We try catch mis-uses but that might
+not always work.
+
+## Additional options
+
+In addition to the RPC commands, these options may be specified for
+every card
+
+#### 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.
+
+Do not execute card removal action, when this card is removed from
+the reader. Useful for command card, that e.g. enable the shutdown
+timer
+
+``` yaml
+'0004':
+    alias: timer_shutdown
+    ignore_card_removal_action: true
+```
+
+#### 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
+as 0. This makes sense e.g., for an \"increase volume\" card in
+combination with a place-capable RFID reader. As long as the card is
+placed on the reader, the volume is increased.
+
+> [!NOTE]
+> This parameter causes *ignore_card_removal_action* to be treated as true
+
+``` yaml
+'0005':
+    alias: incr_volume
+    ignore_same_id_delay: true
+    ignore_card_removal_action: true
+```
+
+## Full RPC action specification
+
+You have seen some examples card actions using the *alias*
+configuration. A full RPC action can also be specified using the
+following syntax:
+
+``` yaml
+'0006':
+    # Option 1: Omit the keyword 'alias'
+    # Here: Set the volume to level 12
+    package: volume
+    plugin: ctrl
+    method: set_volume
+    args: [12]
+'0007':
+    # Option 2: Set 'alias' to custom
+    # Here: Set the volume to level 12
+    alias: custom
+    package: volume
+    plugin: ctrl
+    method: set_volume
+    args: [12]
+```