Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release v3.4.0 #2137

Merged
merged 31 commits into from
Dec 11, 2023
Merged
Changes from 1 commit
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
234cc3c
Add installation checks + CI Workflow (#2119)
AlvinSchiller Dec 2, 2023
dbfd58a
Bump libzmq version to 4.3.5 for armv7
pabera Dec 3, 2023
f1558a2
Add badges to future3 (#2133)
s-martin Dec 4, 2023
cf5aa6c
allow custom username (#2132)
AlvinSchiller Dec 4, 2023
01ec0bc
Allow download of prebuild libzmq-v4.3.5 for Docker
pabera Dec 5, 2023
935a6d4
Merge branch 'future3/develop' into future3/bump-libzmq
pabera Dec 5, 2023
8ea49cf
Remove unnecessary build-essentials from apt-get in Dockerfile
pabera Dec 5, 2023
a32b771
Fix a few typos
pabera Dec 5, 2023
78eb0c4
Use wget to download pre-built libzmq from github
pabera Dec 5, 2023
5a875b8
Remove unused constants
pabera Dec 5, 2023
54681da
Make variable local to its function
pabera Dec 5, 2023
ade2894
Install webapp from release build if Node.JS download is aborted
pabera Dec 7, 2023
c3d0897
Use GH release downloads for webapp
pabera Dec 7, 2023
3ffe8a3
Bugfix: wrong variable assignment
pabera Dec 7, 2023
bdb1dd1
Static release download url
pabera Dec 8, 2023
caf4a55
Fix version funtion return value
pabera Dec 8, 2023
554c0ed
fix local libzmq build
AlvinSchiller Dec 8, 2023
435bd6f
add CI test for local libzmq build
AlvinSchiller Dec 8, 2023
23cf06c
update var names and docs
AlvinSchiller Dec 8, 2023
55b1c9e
add platform in scope and description
AlvinSchiller Dec 8, 2023
93212d0
Merge pull request #1 from AlvinSchiller/future3/bump-libzmq
pabera Dec 8, 2023
4b0860f
Merge pull request #2135 from pabera/future3/bump-libzmq
pabera Dec 8, 2023
c00cde6
Add file upload via WebUI
s-martin Dec 8, 2023
18857d7
[Bugfix] Webapp allows to assign single song to card (#2143)
pabera Dec 10, 2023
02c63ed
[Docs] Inform about Python venv (#2147)
pabera Dec 10, 2023
dd7f6e9
Add running pytest to GitHub action (#2146)
s-martin Dec 10, 2023
afc3067
[Bugfix] setup_autohotspot.sh for multiple wifi country codes, use fi…
ben0r33 Dec 11, 2023
bd34521
some documentation updates (#2151)
AlvinSchiller Dec 11, 2023
50e8446
Better logging functions for Installation script (#2152)
pabera Dec 11, 2023
7250211
Minor doc improvements (#2149)
s-martin Dec 11, 2023
b8b68c8
Add coverage badge (#2153)
s-martin Dec 11, 2023
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
some documentation updates (#2151)
harmonize paths
updated doc for coreapps and references
fix execution docs for run_jukebox.py
  • Loading branch information
AlvinSchiller authored Dec 11, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit bd345213496bd2288b3feb86d71e7c4d215464f7
14 changes: 5 additions & 9 deletions documentation/builders/audio.md
Original file line number Diff line number Diff line change
@@ -10,14 +10,14 @@ Stream transfer happens on user input or automatically on the connection of an a
This is mainly targeted at Bluetooth Headsets/Speakers.

Audio outputs run via PulseAudio and the basic configuration should be easy.
There is a [configuration tool](../developers/coreapps.md#run_configure_audio.py),
There is a [configuration tool](../developers/coreapps.md#Audio),
to setup the configuration for the Jukebox Core App.

To set up the audio

1. Follow the setup steps according to your sound card
2. Check that the sound output works [as described below](audio.md#checking-system-sound-output)
3. Run the the tool [run_configure_audio](../developers/coreapps.md#run_configure_audio.py)
3. Run the [audio configuration tool](../developers/coreapps.md#Audio)
4. [Fine-tune audio parameters](audio.md#additional-options)

## Checking system sound output
@@ -31,7 +31,7 @@ $ pactl list sinks short
1 bluez_sink.C4_FB_20_63_CO_FE.a2dp_sink module-bluez5-device.c s16le 2ch 44100Hz

# Set the default sink (this will be reset at reboot)
$ pactl set-default-sink sink_name
$ pactl set-default-sink <sink_name>

# Check default sink is correctly set
$ pactl info
@@ -50,7 +50,7 @@ You can also try different PulseAudio sinks without setting the default sink. In
volume level for this sink:

```bash
$ paplay -d sink_name /usr/share/sounds/alsa/Front_Center.wav
$ paplay -d <sink_name> /usr/share/sounds/alsa/Front_Center.wav
```

# Bluetooth
@@ -134,8 +134,4 @@ You are, of course, free to modify the PulseAudio configuration to your needs. R
1. [PulseAudio Documentation](https://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User)
2. [PulseAudio Examples](https://wiki.archlinux.org/title/PulseAudio/Examples)

In this case, run the configuration tool with below parameter to avoid touching the PulseAudio configuration file.

```bash
$ ./run_configure_audio.py --ro_pulse
```
In this case, run the [audio configuration tool](../developers/coreapps.md#Audio) with the parameter `--ro_pulse` to avoid touching the PulseAudio configuration file.
4 changes: 2 additions & 2 deletions documentation/builders/concepts.md
Original file line number Diff line number Diff line change
@@ -16,10 +16,10 @@ The Remote Procedure Call (RPC) server allows remotely triggering actions (e.g.,

Why should you care? Because we use the same protocol when triggering actions from other inputs like a card swipe, a GPIO button press, etc. How that works is described in [RPC Commands](rpc-commands.md).

We also have a tool to send RPC commands to the running Jukebox application: [run_rpc_tool.py](../developers/coreapps.md#run_rpc_toolpy)
We also have a [tool to send RPC commands](../developers/coreapps.md#RPC) to the running Jukebox application.

## Publishing Message Queue

The Publishing Message Queue is the complementary part to the RPC where the core application publishes its status and status updates. As a user, you need not worry about it.

If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A sniffer tool exists which listens and prints the incoming status messages: [run_publicity_sniffer.py](../developers/coreapps.md#run_publicity_snifferpy).
If you want to interact with the Jukebox from your own application, this is where you get the current state from. Details about the protocol can be found here (TBD). A [sniffer tool](../developers/coreapps.md#Publicity-Sniffer) exists which listens and prints the incoming status messages.
10 changes: 6 additions & 4 deletions documentation/builders/configuration.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# Jukebox Configuration

The Jukebox configuration is managed by set of files located in `../shared/settings`.
The Jukebox configuration is managed by a set of files located in `shared/settings`.
Some configuration changes can be made through the WebUI and take immediate effect.

The majority of configuration options is only available by editing the config files -
*when the service is not running!*
Don't fear (overly), they contain commentaries.

For several aspects we have :ref:`developer/coreapps:Configuration Tools` and detailed guides:
For several aspects we have [configuration tools](../developers/coreapps.md#configuration-tools) and detailed guides:

* [Audio Configuration](./audio.md#audio-configuration)
* [RFID Reader Configuration](../developers/rfid/basics.md#reader-configuration)
@@ -24,7 +24,8 @@ $ systemctl --user stop jukebox-daemon
$ nano ./shared/settings/jukebox.yaml

# Start Jukebox in console and check the log output (optional)
$ ./src/jukebox/run_jukebox.py
$ cd src/jukebox
$ ./run_jukebox.py
# and if OK, press Ctrl-C and restart the service

# Restart the service
@@ -36,5 +37,6 @@ This could be useful if you want your Jukebox to only allow a lower volume when
at night time when there is time to go to bed :-)

```bash
$./run_jukebox.py --conf ../path/to/custom/config.yaml
$ cd src/jukebox
$ ./run_jukebox.py --conf path/to/custom/config.yaml
```
2 changes: 1 addition & 1 deletion documentation/builders/rpc-commands.md
Original file line number Diff line number Diff line change
@@ -107,6 +107,6 @@ You will find some more examples the configuration of the [Card Database](card-d

## For developers

To send RPC commands for testing and debugging purpose you can use the CLI Tool [`run_rpc_tool.py`](../developers/coreapps.md#run_rpc_toolpy)
To send RPC commands for testing and debugging purpose you can use the [CLI Tool](../developers/coreapps.md#RPC).
Also here is a ready-to-use decoding functions which decodes an RPC command (with or without alias)
from a YAML entry:func:`jukebox.utils.decode_rpc_command`.
4 changes: 2 additions & 2 deletions documentation/builders/system.md
Original file line number Diff line number Diff line change
@@ -70,7 +70,7 @@ Service control and service configuration file location is identical to MPD.

## Jukebox Core Service

The :ref:`developer/coreapps:Jukebox Core` runs as a *user-local* service with the name `jukebox-daemon`.
The [Jukebox Core Service](../developers/coreapps.md#Jukebox-Core) runs as a *user-local* service with the name `jukebox-daemon`.
Similar to MPD, it's important that it does run as system-wide service to be able to interact with PulseAudio.

The service can be controlled with the `systemctl`-command by adding the parameter `--user`
@@ -101,7 +101,7 @@ Starting and stopping the service can be useful for debugging or configuration c
The Web UI is served using nginx. Nginx runs as a system service. The home directory is localed at

```
~/RPi-Jukebox-RFID/src/webapp/build
./src/webapp/build
```

The Nginx configuration is located at
18 changes: 10 additions & 8 deletions documentation/builders/troubleshooting.md
Original file line number Diff line number Diff line change
@@ -15,8 +15,8 @@ Debugging your setup runs in several steps
## The short answer

```bash
../shared/logs/app.log : Complete Debug Messages
../shared/logs/errors.log: Only Errors and Warnings
shared/logs/app.log : Complete Debug Messages
shared/logs/errors.log: Only Errors and Warnings
```

These files always contain the messages of the current run only.
@@ -33,9 +33,9 @@ http://ip.of.your.box/logs

## The long answer: A few more details

If started without parameters, the Jukebox checks for the existence of `../shared/settings/logger.yaml`
If started without parameters, the Jukebox checks for the existence of `shared/settings/logger.yaml`
and if present, uses that configuration for logging. This file is created by the installation process.
The default configuration file is also provided in `../resources/default-settings/logger.default.yaml`.
The default configuration file is also provided in `resources/default-settings/logger.default.yaml`.
We use Python's logging module to provide the debug messages which is configured through this file.

**We are still in the Pre-Release phase which means full debug logging is enabled by default.**
@@ -47,8 +47,8 @@ The default logging config does 2 things:
1. It writes 2 log files:

```bash
../shared/logs/app.log : Complete Debug Messages
../shared/logs/errors.log : Only Errors and Warnings
shared/logs/app.log : Complete Debug Messages
shared/logs/errors.log : Only Errors and Warnings
```

2. Prints logging messages to the console. If run as a service, only error messages are emitted to console to avoid spamming the system log files.
@@ -63,11 +63,12 @@ on the console log.
$ systemctl --user stop jukebox-daemon

# Start the Jukebox in debug mode:
$ cd src/jukebox

# with default logger:
$ ./run_jukebox.py

# or with custom logger configuration:
$ ./run_jukebox.py --logger ../path/to/logger.yaml
$ ./run_jukebox.py --logger path/to/custom/logger.yaml
```

### Fallback configuration
@@ -77,6 +78,7 @@ Attention: This only emits messages to the console and does not write to the log
This is more a fallback features:

``` bash
$ cd src/jukebox
$ ./run_jukebox.py -vv
```

6 changes: 6 additions & 0 deletions documentation/builders/update.md
Original file line number Diff line number Diff line change
@@ -2,6 +2,12 @@

## Updating your Jukebox Version 3

### Update from v3.2.1 and prior

As there are some significant changes in the installation, a new setup on a fresh image is required.

### General

Things on Version 3 are moving fast and you may want to keep up with recent changes. Since we are in Alpha Release stage,
a fair number of fixes are expected to be committed in the near future.

43 changes: 19 additions & 24 deletions documentation/developers/coreapps.md
Original file line number Diff line number Diff line change
@@ -4,64 +4,59 @@ The Jukebox\'s core apps are located in `src/jukebox`. Run the following
command to learn more about each app and its parameters:

``` bash
$ ./run_app_name.py -h
$ cd src/jukebox
$ ./<scriptname> -h
```

## Jukebox Core

### `run_jukebox.py`
## Jukebox Core

[run_jukebox.py](../../src/jukebox/run_jukebox.py)
**Scriptname:** [run_jukebox.py](../../src/jukebox/run_jukebox.py)

This is the main app and starts the Jukebox Core.

Usually this runs as a service, which is started automatically after boot-up. At times, it may be necessary to restart the service. For example after a configuration change. Not all configuration changes can be applied on-the-fly. See [Jukebox Configuration](../builders/configuration.md#jukebox-configuration).

For debugging, it is usually desirable to run the Jukebox directly from the console rather than as service. This gives direct logging info in the console and allows changing command line parameters. See [Troubleshooting](../builders/troubleshooting.md).


## Configuration Tools

Before running the configuration tools, stop the Jukebox Core service.
See [Best practice procedure](../builders/configuration.md#best-practice-procedure).

### `run_configure_audio.py`

[run_configure_audio.py](../../src/jukebox/run_configure_audio.py)
### Audio

Setup tool to register the PulseAudio sinks as primary and secondary audio outputs.
**Scriptname:** [run_configure_audio.py](../../src/jukebox/run_configure_audio.py)

Will also setup equalizer and mono down mixer in the pulseaudio config file.
Setup tool to register the PulseAudio sinks as primary and secondary audio outputs.

Run this once after installation. Can be re-run at any time to change the settings. For more information see [Audio Configuration](../builders/audio.md).
Will also setup equalizer and mono down mixer in the pulseaudio config file. Run this once after installation. Can be re-run at any time to change the settings. For more information see [Audio Configuration](../builders/audio.md).

### `run_register_rfid_reader.py`
### RFID Reader

[run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)
**Scriptname:** [run_register_rfid_reader.py](../../src/jukebox/run_register_rfid_reader.py)

Setup tool to configure the RFID Readers.
Setup tool to configure the RFID Readers.

Run this once to register and configure the RFID readers with the Jukebox. Can be re-run at any time to change the settings. For more information see [RFID Readers](./rfid/README.md).

> [!NOTE]
> This tool will always write a new configurations file. Thus, overwrite the old one (after checking with the user). Any manual modifications to the settings will have to be re-applied

## Developer Tools

### `run_rpc_tool.py`

[run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)

Command Line Interface to the Jukebox RPC Server.
## Developer Tools

A command line tool for sending RPC commands to the running jukebox app. This uses the same interface as the WebUI. Can be used for additional control or for debugging.
### RPC

The tool features auto-completion and command history.
**Scriptname:** [run_rpc_tool.py](../../src/jukebox/run_rpc_tool.py)

The list of available commands is fetched from the running Jukebox service.
Command Line Interface to the Jukebox RPC Server.

A command line tool for sending RPC commands to the running jukebox app. This uses the same interface as the WebUI. Can be used for additional control or for debugging.The tool features auto-completion and command history. The list of available commands is fetched from the running Jukebox service.

### `run_publicity_sniffer.py`
### Publicity Sniffer

[run_publicity_sniffer.py](../../src/jukebox/run_publicity_sniffer.py)
**Scriptname:** [run_publicity_sniffer.py](../../src/jukebox/run_publicity_sniffer.py)

A command line tool that monitors all messages being sent out from the Jukebox via the publishing interface. Received messages are printed in the console. Mainly used for debugging.
1 change: 1 addition & 0 deletions documentation/developers/developer-issues.md
Original file line number Diff line number Diff line change
@@ -46,6 +46,7 @@ Alternatively, use the provided script, which sets the variable for you
(provided your swap size is large enough):

``` bash
$ cd src/webapp
$ ./run_rebuild.sh
```

2 changes: 1 addition & 1 deletion documentation/developers/docker.md
Original file line number Diff line number Diff line change
@@ -33,7 +33,7 @@ need to adapt some of those commands to your needs.
* Override/Merge the values from the following [Override file](https://github.com/MiczFlor/RPi-Jukebox-RFID/blob/future3/develop/docker/config/jukebox.overrides.yaml) in your `jukebox.yaml`.
* **\[Currently required\]** Update all relative paths (`../..`) in to `/home/pi/RPi-Jukebox-RFID`.

4. Change directory into the `./RPi-Jukebox-RFID/shared/audiofolders`
4. Change directory into the `./shared/audiofolders`
and copy a set of MP3 files into this folder (for more fun when
testing).

5 changes: 2 additions & 3 deletions documentation/developers/rfid/basics.md
Original file line number Diff line number Diff line change
@@ -35,8 +35,7 @@ Readers operate on one of two different frequencies: 125kHz or 13.56 MHz. Make s
## Reader Configuration

During the installation process, you can already configure a RFID
reader. To manually configure RFID reader(s),
[please run the tool](../coreapps.md#run_register_rfid_reader.py), (`src/jukebox/run_register_rfid_reader.py`).
reader. To manually configure RFID reader(s) run the [RFID reader configuration tool](../coreapps.md#RFID-Reader).

It will generate a reader configuration file at
`shared/settings/rfid.yaml`. You can re-run the tool to change the
@@ -67,7 +66,7 @@ Indicates the Python package used for this reader. Filled by the RFID configurat

#### config:

Filled by the [RFID configuration tool](../coreapps.md#run_register_rfid_reader.py) (`src/jukebox/run_register_rfid_reader.py`) based on default values and user input. After running the tool, you may manually change some settings here, as not everything can be configured through the tool. Note that re-running the tool will completely rewrite the configuration file.
Filled by the [RFID reader configuration tool](../coreapps.md#RFID-Reader) based on default values and user input. After running the tool, you may manually change some settings here, as not everything can be configured through the tool. Note that re-running the tool will completely rewrite the configuration file.

#### same_id_delay: float \| integer

2 changes: 1 addition & 1 deletion documentation/developers/rfid/genericusb.md
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@

This module covers all types of USB-based RFID input readers. If you
plan to connect multiple USB-based RFID readers to the Jukebox, make
sure to connect all of them before running the registration tool [run_register_rfid_reader.py](../coreapps.md#run_register_rfid_readerpy).
sure to connect all of them before running the [RFID reader configuration tool](../coreapps.md#RFID-Reader).

> [!NOTE]
> The user needs to be part of the group \'input\' for evdev to work. This should usually be the case. However, a user can be added with:
2 changes: 1 addition & 1 deletion documentation/developers/rfid/mfrc522_spi.md
Original file line number Diff line number Diff line change
@@ -6,7 +6,7 @@ RC522 RFID reader via SPI connection.

## Installation

Run the [run_register_rfid_reader.py](../coreapps.md#run_register_rfid_reader.py) tool for guided
Run the [RFID reader configuration tool](../coreapps.md#RFID-Reader) for guided
installation.

## Options
4 changes: 2 additions & 2 deletions documentation/developers/rfid/template_reader.md
Original file line number Diff line number Diff line change
@@ -9,9 +9,9 @@
This template provides the skeleton API for a new Reader. If you follow
the conventions outlined below, your new reader will be picked up
automatically There is no extra need to register the reader module with
the Phoniebox. Just re-run `the reader config tool <developer/coreapps:run_register_rfid_reader.py>`.
the Phoniebox. Just re-run [RFID reader configuration tool](../coreapps.md#RFID-Reader).

Follow the instructions in [template_new_reader.py]
Follow the instructions in [template_new_reader.py](../../../src/jukebox/components/rfid/hardware/template_new_reader/template_new_reader.py)

Also have a look at the other reader subpackages to see how stuff works
with an example
2 changes: 1 addition & 1 deletion resources/default-settings/jukebox.default.yaml
Original file line number Diff line number Diff line change
@@ -30,7 +30,7 @@ pulse:
toggle_on_connect: true
# Limit maximum volume range to XX % - can be changed through the UI (for temporary use)
soft_max_volume: 70
# Run the tool run_configure_audio.py to configure the pulseaudio sinks
# Run the audio configuration tool to configure the pulseaudio sinks
#
# After startup, the audio output defaults to primary
# Any Bluetooth device should be the secondary (as it may not always be available directly after boot)
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# This GUI-based mock reader also requires: tkinter
# tkinter is a standard Python package and needs not be installed separately
# It is available on most Unix systems (but not on headless Raspbian RPi where running a GUI is difficult anyway)
# You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`

ttkthemes
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
# PN532 related requirements
# You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`

py532lib
Original file line number Diff line number Diff line change
@@ -1 +1,4 @@
# RDM6300 related requirements
# You need to install these with `python -m pip install --upgrade --force-reinstall -q -r requirements.txt`

pyserial