Merge branch 'future3/develop' into future3/fix-docker-windows

MiczFlor · Feb 20, 2024 · 4eb3c69 · 4eb3c69
2 parents b1b321c + 07208e6
commit 4eb3c69
Show file tree

Hide file tree

Showing 14 changed files with 686 additions and 108 deletions.
diff --git a/.github/workflows/bundle_webapp_and_release_v3.yml b/.github/workflows/bundle_webapp_and_release_v3.yml
@@ -101,7 +101,7 @@ jobs:
           tar -czvf ${{ steps.vars.outputs.webapp_bundle_name }} build
 
       - name: Artifact Upload
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
           name: ${{ steps.vars.outputs.webapp_bundle_name }}
           path: ${{ steps.build-webapp.outputs.webapp-root-path }}/${{ steps.vars.outputs.webapp_bundle_name }}
@@ -119,7 +119,7 @@ jobs:
 
     steps:
       - name: Artifact Download
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v4
         with:
           name: ${{ needs.build.outputs.webapp_bundle_name }}
 

diff --git a/.github/workflows/test_docker_debian_codename_sub_v3.yml b/.github/workflows/test_docker_debian_codename_sub_v3.yml
@@ -134,7 +134,7 @@ jobs:
           BASE_TEST_IMAGE=${{ steps.vars.outputs.image_tag_name_local_base }}
 
     - name: Artifact Upload Docker Image
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: ${{ steps.vars.outputs.image_file_name }}
         path: ${{ steps.vars.outputs.image_file_path }}
@@ -159,7 +159,7 @@ jobs:
       uses: docker/setup-buildx-action@v3.0.0
 
     - name: Artifact Download Docker Image
-      uses: actions/download-artifact@v3
+      uses: actions/download-artifact@v4
       with:
         name: ${{ needs.build.outputs.image_file_name }}
 
@@ -177,15 +177,15 @@ jobs:
         args: |
           ./${{ matrix.test_script }}
 
-  # cleanup after test execution
-  cleanup:
-    # run only if tests didn't fail: keep the artifact to make job reruns possible
-    if: ${{ !failure() }}
-    needs: [build, test]
-    runs-on: ${{ inputs.runs_on }}
-
-    steps:
-        - name: Artifact Delete Docker Image
-          uses: geekyeggo/delete-artifact@v2
-          with:
-            name: ${{ needs.build.outputs.image_file_name }}
+  ## cleanup after test execution
+  #cleanup:
+  #  # run only if tests didn't fail: keep the artifact to make job reruns possible
+  #  if: ${{ !failure() }}
+  #  needs: [build, test]
+  #  runs-on: ${{ inputs.runs_on }}
+  #
+  #  steps:
+  #      - name: Artifact Delete Docker Image
+  #        uses: geekyeggo/delete-artifact@v4
+  #        with:
+  #          name: ${{ needs.build.outputs.image_file_name }}
diff --git a/docker/armv7/jukebox.Dockerfile b/docker/armv7/jukebox.Dockerfile
@@ -65,7 +65,7 @@ WORKDIR ${HOME}
 COPY --chown=${USER}:${USER} . ${INSTALLATION_PATH}/
 
 RUN pip install --no-cache-dir -r ${INSTALLATION_PATH}/requirements.txt
-RUN pip install --no-cache-dir --pre --no-binary pyzmq pyzmq
+RUN pip install --no-cache-dir --no-binary pyzmq pyzmq
 
 EXPOSE 5555 5556
 

diff --git a/documentation/builders/README.md b/documentation/builders/README.md
@@ -26,6 +26,7 @@
 * [Soundcards](./components/soundcards/)
   * [HiFiBerry Boards](./components/soundcards/hifiberry.md)
 * [RFID Readers](./../developers/rfid/README.md)
+* [Event devices (USB and other buttons)](./event-devices.md)
 
 ## Web Application
 

diff --git a/documentation/builders/event-devices.md b/documentation/builders/event-devices.md
@@ -0,0 +1,120 @@
+# Event devices
+
+## Background
+Event devices are generic input devices that are exposed in `/dev/input`.
+This includes USB peripherals (Keyboards, Controllers, Joysticks or Mouse) as well as potentially bluetooth devices.
+
+A specific usecase for this could be, if a Zero Delay Arcade USB Encoder is used to wire arcade buttons instead of using GPIO pins.
+
+These device interface support various kinds of input events, such as press, movements and potentially also outputs (eg. rumble, led lights, ...). Currently only the usage of button presses as input is supported.
+
+This functionality was previously implemented under the name of [USB buttons](https://github.com/MiczFlor/RPi-Jukebox-RFID/blob/develop/components/controls/buttons_usb_encoder/README.md).
+
+The devices and their button mappings need to be mapped in the configuration file.
+
+## Configuration
+
+To configure event devices, first add the plugin as an entry to the module list of your main configuration file ``shared/settings/jukebox.yaml``:
+
+``` yaml
+modules:
+  named:
+    event_devices: controls.event_devices
+```
+
+And add the following section with the plugin specific configuration:
+``` yaml
+evdev:
+  enabled: true
+  config_file: ../../shared/settings/evdev.yaml
+```
+
+The actual configuration itself is stored in a separate file. In this case in ``../../shared/settings/evdev.yaml``.
+
+The configuration is structured akin to the configuration of the [GPIO devices](./gpio.md).
+
+In contrast to `gpio`, multiple devices (eg arcade controllser, keyboards, joysticks, mice, ...) are supported, each with their own `input_devices` (=buttons). `output_devices` or actions other than `on_press` are currently not yet supported.
+
+``` yaml
+devices: # list of devices to listen for
+  {device nickname}: # config for a specific device
+    device_name: {device_name} # name of the device
+    exact: False/True # optional to require exact match. Otherwise it is sufficient that a part of the name matches
+    input_devices: # list of buttons to listen for for this device
+      {button nickname}:
+        type: Button
+        kwargs:
+          key_code: {key-code}: # evdev event id
+        actions:
+          on_press: # Currently only the on_press action is supported
+            {rpc_command_definition} # eg `alias: toggle`
+```
+The `{device nickname}` is only for your own orientation and can be choosen freely.
+For each device you need to figure out the `{device_name}` and the `{event_id}` corresponding to key strokes, as indicated in the sections below.
+
+### Identifying the `{device_name}`
+
+The `{device_name}` can be identified using the following Python snippet:
+
+``` Python
+import evdev
+devices = [evdev.InputDevice(path) for path in evdev.list_devices()]
+for device in devices:
+    print(device.path, device.name, device.phys)
+```
+
+The output could be in the style of:
+
+```
+/dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
+/dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0
+```
+
+In this example, the `{device_name}` could be `DELL USB Optical Mouse`.
+Note that if you use the option `exact: False`, it would be sufficient to add a substring such as `USB Keyboard`.
+
+### Identifying the `{key-code}`
+
+The key code for a button press can be determined using the following code snippet:
+
+``` Python
+import evdev
+device = evdev.InputDevice('/dev/input/event0')
+device.capabilities(verbose=True)[('EV_KEY', evdev.ecodes.EV_KEY)]
+```
+
+With the `InputDevice` corresponding to the path from the output of the section `{device_name}` (eg. in the example `/dev/input/event0`
+would correspond to `Dell Dell USB Keyboard`).
+
+If the naming is not clear, it is also possible to empirically check for the key code by listening for events:
+
+``` Python
+from evdev import InputDevice, categorize, ecodes
+dev = InputDevice('/dev/input/event1')
+print(dev)
+for event in dev.read_loop():
+  if event.type == ecodes.EV_KEY:
+    print(categorize(event))
+```
+The output could be of the form:
+```
+device /dev/input/event1, name "DragonRise Inc.   Generic   USB  Joystick  ", phys "usb-3f980000.usb-1.2/input0"
+key event at 1672569673.124168, 297 (BTN_BASE4), down
+key event at 1672569673.385170, 297 (BTN_BASE4), up
+```
+
+In this example output, the `{key-code}` would be `297`
+
+Alternatively, the device could also be setup without a mapping.
+Afterwards, when pressing keys, the key codes can be found in the log files. Press various buttons on your device,
+while watching the logs with `tail -f shared/logs/app.log`.
+Look for entries like `No callback registered for button ...`.
+
+### Specifying the `{rpc_command_definition}`
+
+The RPC command follows the regular RPC command rules as defined in the [following documentation](./rpc-commands.md).
+
+
+## Full example config
+
+A complete configuration example for a USB Joystick controller can be found in the [examples](../../resources/default-settings/evdev.example.yaml).
diff --git a/documentation/developers/docker.md b/documentation/developers/docker.md
@@ -291,6 +291,20 @@ $ docker run -it --rm \
     --name jukebox jukebox
 ```
 
+## Testing EVDEV devices in Linux
+To test the [event device capabilities](../builders/event-devices.md) in docker, the device needs to be made available to the container.
+
+### Linux
+Mount the device into the container by configuring the appropriate device in a `devices` section of the `jukebox` service in the docker compose file. For example:
+
+```yaml
+  jukebox:
+    ...
+    devices:
+      - /dev/input/event3:/dev/input/event3
+```
+
+
 ### Resources
 
 #### Mac

diff --git a/documentation/developers/docstring/README.md b/documentation/developers/docstring/README.md
@@ -104,6 +104,12 @@
   * [pbox\_set\_state](#components.rfid.hardware.fake_reader_gui.gpioz_gui_addon.pbox_set_state)
   * [que\_set\_pbox](#components.rfid.hardware.fake_reader_gui.gpioz_gui_addon.que_set_pbox)
   * [create\_outputs](#components.rfid.hardware.fake_reader_gui.gpioz_gui_addon.create_outputs)
+* [components.rfid.hardware.generic\_nfcpy.description](#components.rfid.hardware.generic_nfcpy.description)
+* [components.rfid.hardware.generic\_nfcpy.generic\_nfcpy](#components.rfid.hardware.generic_nfcpy.generic_nfcpy)
+  * [ReaderClass](#components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass)
+    * [cleanup](#components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.cleanup)
+    * [stop](#components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.stop)
+    * [read\_card](#components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.read_card)
 * [components.rfid.hardware.generic\_usb.description](#components.rfid.hardware.generic_usb.description)
 * [components.rfid.hardware.generic\_usb.generic\_usb](#components.rfid.hardware.generic_usb.generic_usb)
 * [components.rfid.hardware.rc522\_spi.description](#components.rfid.hardware.rc522_spi.description)
@@ -1948,6 +1954,61 @@ Add all output devices to the GUI
 
 List of all added GUI objects
 
+<a id="components.rfid.hardware.generic_nfcpy.description"></a>
+
+# components.rfid.hardware.generic\_nfcpy.description
+
+List of supported devices https://nfcpy.readthedocs.io/en/latest/overview.html
+
+
+<a id="components.rfid.hardware.generic_nfcpy.generic_nfcpy"></a>
+
+# components.rfid.hardware.generic\_nfcpy.generic\_nfcpy
+
+<a id="components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass"></a>
+
+## ReaderClass Objects
+
+```python
+class ReaderClass(ReaderBaseClass)
+```
+
+The reader class for nfcpy supported NFC card readers.
+
+
+<a id="components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.cleanup"></a>
+
+#### cleanup
+
+```python
+def cleanup()
+```
+
+The cleanup function: free and release all resources used by this card reader (if any).
+
+
+<a id="components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.stop"></a>
+
+#### stop
+
+```python
+def stop()
+```
+
+This function is called to tell the reader to exit its reading function.
+
+
+<a id="components.rfid.hardware.generic_nfcpy.generic_nfcpy.ReaderClass.read_card"></a>
+
+#### read\_card
+
+```python
+def read_card() -> str
+```
+
+Blocking or non-blocking function that waits for a new card to appear and return the card's UID as string
+
+
 <a id="components.rfid.hardware.generic_usb.description"></a>
 
 # components.rfid.hardware.generic\_usb.description
@@ -2659,7 +2720,7 @@ def stop_autohotspot()
 
 Stop auto hotspot functionality
 
-Basically disabling the cronjob and running the script one last time manually
+Stopping and disabling the timer and running the service one last time manually
 
 
 <a id="components.hostif.linux.start_autohotspot"></a>
@@ -2671,9 +2732,9 @@ Basically disabling the cronjob and running the script one last time manually
 def start_autohotspot()
 ```
 
-start auto hotspot functionality
+Start auto hotspot functionality
 
-Basically enabling the cronjob and running the script one time manually
+Enabling and starting the timer (timer will start the service)
 
 
 <a id="components.misc"></a>
@@ -2966,35 +3027,7 @@ class battmon_ads1015(BatteryMonitorBase.BattmonBase)
 
 Battery Monitor based on a ADS1015
 
-> [!CAUTION]
-> Lithium and other batteries are dangerous and must be treated with care.
-> Rechargeable Lithium Ion batteries are potentially hazardous and can
-> present a serious **FIRE HAZARD** if damaged, defective or improperly used.
-> Do not use this circuit to a lithium ion battery without expertise and
-> training in handling and use of batteries of this type.
-> Use appropriate test equipment and safety protocols during development.
-> There is no warranty, this may not work as expected or at all!
-
-This script is intended to read out the Voltage of a single Cell LiIon Battery using a CY-ADS1015 Board:
-
-                                                  3.3V
-                                                   +
-                                                   |
-                                              .----o----.
-                        ___                   |         |  SDA
-              .--------|___|---o----o---------o AIN0    o------
-              |         2MΩ    |    |         |         |  SCL
-              |               .-.   |         | ADS1015 o------
-             ---              | |  ---        |         |
-     Battery  -          1.5MΩ| |  ---100nF   '----o----'
-     2.9V-4.2V|               '-'   |              |
-              |                |    |              |
-             ===              ===  ===            ===
-
-Attention:
-* the circuit is constantly draining the battery! (leak current up to: 2.1µA)
-* the time between sample needs to be a minimum 1sec with this high impedance voltage divider
-      don't use the continuous conversion method!
+See [Battery Monitor documentation](../../builders/components/power/batterymonitor.md)
 
 
 <a id="components.gpio.gpioz.plugin"></a>

diff --git a/documentation/developers/rfid/mock_reader.md b/documentation/developers/rfid/mock_reader.md
@@ -6,7 +6,7 @@ machine - probably in a Python virtual environment.
 
 **place-capable**: yes
 
-If you [mock the GPIO pins](../../../src/jukebox/components/gpio/gpioz/README.rst#use-mock-pins), this GUI will show the GPIO devices.
+If you [mock the GPIO pins](../../builders/gpio.md#use-mock-pins), this GUI will show the GPIO devices.
 
 ![image](mock_reader.png)
 

diff --git a/installation/routines/setup_jukebox_core.sh b/installation/routines/setup_jukebox_core.sh
@@ -86,7 +86,7 @@ _jukebox_core_build_and_install_pyzmq() {
     fi
 
     ZMQ_PREFIX="${JUKEBOX_ZMQ_PREFIX}" ZMQ_DRAFT_API=1 \
-      pip install -v --no-binary pyzmq --pre pyzmq
+      pip install -v --no-binary pyzmq pyzmq
   else
     print_lc "    Skipping. pyzmq already installed"
   fi