Update docs (#2216)

* minor fixes * add "Pre-install preparation / workarounds" section add "Workaround for network related features on bookworm" * add "Workaround for 64-bit Kernels" harmonize and update description / message * minor fix * Update warning block as alerts are not supported inside of "details" * minor fix * fix Raspberry Pi OS name Co-authored-by: s-martin <[email protected]> * fix Raspberry Pi OS name * fix typo * added link to installation * updates from reviews * fix file for synchronisation doc. moved to components * add docs for samba * Apply suggestions from code review Co-authored-by: s-martin <[email protected]> * restructure builders readme --------- Co-authored-by: s-martin <[email protected]>
MiczFlor · Jan 24, 2024 · f6db160 · f6db160
1 parent 6f09764
commit f6db160
Show file tree

Hide file tree

Showing 13 changed files with 93 additions and 37 deletions.
diff --git a/documentation/README.md b/documentation/README.md
@@ -42,7 +42,8 @@ project check out the [documentation of Version 2](https://github.com/MiczFlor/R
 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.
+> [!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.
 

diff --git a/documentation/builders/README.md b/documentation/builders/README.md
@@ -6,24 +6,28 @@
 * [Update](./update.md)
 * [Configuring Phoniebox](./configuration.md)
 
-## Configuration
+## Features
 
-* [Audio](./audio.md)
-* [RFID](./rfid.md)
+* Audio
+    * [Audio Output](./audio.md)
+    * [Bluetooth audio buttons](./bluetooth-audio-buttons.md)
 * [GPIO Recipes](./gpio.md)
 * [Card Database](./card-database.md)
-* [Troubleshooting](./troubleshooting.md)
+    * [RFID Cards synchronisation](./components/synchronisation/rfidcards.md)
+* [Auto Hotspot](./autohotspot.md)
+* File Management
+    * [Network share / Samba](./samba.md)
+
+## Hardware Components
 
-## Components
 * [Power](./components/power/)
     * [OnOff SHIM for safe power on/off](./components/power/onoff-shim.md)
 * [Soundcards](./components/soundcards/)
     * [HiFiBerry Boards](./components/soundcards/hifiberry.md)
-
+* [RFID Readers](./../developers/rfid/README.md)
+
 ## Advanced
-
-* [Bluetooth (and audio buttons)](./bluetooth-audio-buttons.md)
-* [Auto Hotspot](./autohotspot.md)
+* [Troubleshooting](./troubleshooting.md)
 * [Concepts](./concepts.md)
 * [System](./system.md)
 * [RPC Commands](./rpc-commands.md)

diff --git a/documentation/builders/rfid.md → ...s/components/synchronisation/rfidcards.md b/documentation/builders/rfid.md → ...s/components/synchronisation/rfidcards.md
@@ -1,6 +1,4 @@
-# RFID
-
-## Syncronisation RFID Cards
+# Synchronisation RFID Cards
 
 This component handles the synchronisation of RFID cards (audiofolder
 and card database entries).
@@ -15,7 +13,7 @@ RFID card to the command. For the \"RFID scan sync\" feature, activate
 the option in the configuration or bind a RFID card to the command for
 dynamic activation or deactivation.
 
-### Synchronisation
+## Synchronisation
 
 The synchronisation will be FROM a server TO the Phoniebox, overriding
 existing files. A local configuration will be lost after the
@@ -26,7 +24,7 @@ To access the files on the server, 2 modes are supported: SSH or MOUNT.
 Please make sure you have the correct access rights to the source and
 use key-based authentication for SSH.
 
-#### RFID scan sync
+### RFID scan sync
 
 If the feature \"RFID scan sync\" is activated, there will be a check on
 every RFID scan against the server if a matching card entry and audiofolder is available. If so, changes will be synced. The playback
@@ -40,7 +38,7 @@ deleted on remote. This is also true for changed card entries (the old
 audiofolder / -files will remain). To remove not existing items us a
 \"sync-all\".
 
-### Configuration
+## Configuration
 
 Set the corresponding setting in `shared\settings\jukebox.yaml` to
 activate this feature.

diff --git a/documentation/builders/configuration.md b/documentation/builders/configuration.md
@@ -7,11 +7,7 @@ The majority of configuration options is only available by editing the config fi
 *when the service is not running!*
 Don't fear (overly), they contain commentaries.
 
-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)
-* [GPIO Recipes](./gpio.md)
+For several aspects we have [configuration tools](../developers/coreapps.md#configuration-tools) and [detailed guides](./README.md#features).
 
 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
@@ -10,7 +10,9 @@ Before you can install the Phoniebox software, you need to prepare your Raspberr
 1. Connect a Micro SD card to your computer (preferable an SD card with high read throughput)
 2. Download the [Raspberry Pi Imager](https://www.raspberrypi.com/software/) and run it
 3. Click on "Raspberry Pi Device" and select "No filtering"
-4. Select **Raspberry Pi OS Lite (32-bit)** (without desktop environment) as the operating system. `future3` does not support 64bit kernels (`aarch64`).
+4. As operating system select **Raspberry Pi OS (other)** and then **Raspberry Pi OS Lite (Legacy, 32-bit)** (no desktop environment). *64-bit is currently not supported*.
+    * Bookworm support is partly broken, see [here](#workaround-for-network-related-features-on-bookworm).
+    * For Pi 4 and newer also check [this](#workaround-for-64-bit-kernels-pi-4-and-newer).
 5. Select your Micro SD card (your card will be formatted)
 6. After you click `Next`, a prompt will ask you if you like to customize the OS settings
     * Click `Edit Settings`
@@ -26,12 +28,12 @@ Before you can install the Phoniebox software, you need to prepare your Raspberr
 8. Confirm the next warning about erasing the SD card with `Yes`
 9. Wait for the imaging process to be finished (it'll take a few minutes)
 
+
+### Pre-boot preparation
 <details>
 
 <summary>In case you forgot to customize the OS settings, follow these instructions after RPi OS has been written to the SD card.</summary>
 
-### Pre-boot preparation
-
 You will need a terminal, like PuTTY for Windows or the Terminal app for Mac to proceed with the next steps.
 
 1. Open a terminal of your choice.
@@ -77,6 +79,42 @@ You will need a terminal, like PuTTY for Windows or the Terminal app for Mac to
 
 </details>
 
+### Pre-install preparation / workarounds
+
+#### Workaround for network related features on Bookworm
+<details>
+With Bookworm the network settings have changed. Now "NetworkManager" is used instead of "dhcpcd".
+This breaks breaks network related features like "Static IP", "Wifi Setup" and "Autohotspot".
+Before running the installation, the network config has to be changed via raspi-config, to use the "old" dhcpcd network settings.
+
+:warning:
+If the settings are changed, your network will reset and Wifi will not be configured, so you lose ssh access via wireless connection.
+So make sure you use a wired connection or perform the following steps in a local terminal with a connected monitor and keyboard.
+
+Change network config
+* run `sudo raspi-config`
+* select `6 - Advanced Options`
+* select `AA - Network Config`
+* select `dhcpcd`
+
+If you need Wifi, add the information now
+* select `1 - System Options`
+* select `1 - Wireless LAN`
+* enter Wifi information
+</details>
+
+#### Workaround for 64-bit Kernels (Pi 4 and newer)
+<details>
+
+The installation process checks if a 32-bit OS is running, as 64-bit is currently not supported.
+This check also fails if the kernel is running in 64-bit mode. This is the default for Raspberry Pi models 4 and newer.
+
+To be able to run the installation, you have to switch to the 32-bit mode by modifying the `config.txt` and add/change the line `arm_64bit=0`. 
+Up to Bullseye, the `config.txt` file is located at `/boot/`. Since Bookworm, the location changed to `/boot/firmware/` ([see here](https://www.raspberrypi.com/documentation/computers/config_txt.html)).
+
+Reboot before you proceed.
+</details>
+
 ## Install Phoniebox software
 
 Choose a version, run the corresponding install command in your SSH terminal and follow the instructions.

diff --git a/documentation/builders/samba.md b/documentation/builders/samba.md
@@ -0,0 +1,18 @@
+# Samba
+
+To conveniently copy files to your Phoniebox via network `samba` can be configured during the installation. The folder `./shared/` will be exposed as network share `phoniebox`, giving you access to the audio and config folders.
+
+## Connect
+
+To access the share open your OS network environment and select your Phoniebox device. 
+Alternatively directly access it via url with the file explorer (e.g. Windows `\\<ip-address-of-your-phoniebox>`, MacOS `smb://<ip-address-of-your-phoniebox>`).
+
+See also
+* [MacOS](https://support.apple.com/lt-lt/guide/mac-help/mchlp1140/mac)
+
+## User name / Password
+
+As login credentials use the same username you used to run the installation with. The password is `raspberry`.
+You can change the password anytime using the command `sudo smbpasswd -a "<your-username>"`.
+
+
diff --git a/documentation/builders/update.md b/documentation/builders/update.md
@@ -35,7 +35,8 @@ $ ./run_rebuild.sh -u
 ## Migration Path from Version 2
 
 There is no update path coming from Version 2.x of the Jukebox.
-You need to do a fresh install of Version 3 on a fresh Raspian Bullseye image.
+You need to do a fresh install of Version 3 on a fresh Raspberry Pi OS image.
+See [Installing Phoniebox future3](./installation.md).
 
 > [!IMPORTANT]
 > Do start with a fresh SD card image!

diff --git a/documentation/developers/README.md b/documentation/developers/README.md
@@ -9,7 +9,7 @@
 
 * [Jukebox Apps](./coreapps.md)
 * [Web App](./webapp.md)
-* [RFID Readers](./rfid)
+* [RFID Readers](./rfid/README.md)
 * [Docstring API Docs (from py files)](./docstring/README.md)
 * [Plugin Reference](./docstring/README.md#jukeboxplugs)
 * [Feature Status](./status.md)

diff --git a/documentation/developers/docstring/README.md b/documentation/developers/docstring/README.md
@@ -1245,7 +1245,7 @@ This means must also run as user process, as described in
 ## Misc
 
 PulseAudio may switch the sink automatically to a connecting bluetooth device depending on the loaded module
-with name module-switch-on-connect. On RaspianOS Bullseye, this module is not part of the default configuration
+with name module-switch-on-connect. On Raspberry Pi OS Bullseye, this module is not part of the default configuration
 in ``/usr/pulse/default.pa``. So, we don't need to worry about it.
 If the module gets loaded it conflicts with the toggle on connect and the selected primary / secondary outputs
 from the Jukebox. Remove it from the configuration!

diff --git a/installation/includes/02_helpers.sh b/installation/includes/02_helpers.sh
@@ -75,7 +75,7 @@ get_architecture() {
     echo $arch
 }
 
-is_raspian() {
+is_raspbian() {
     if [[ $( . /etc/os-release; printf '%s\n' "$ID"; ) == *"raspbian"* ]]; then
         echo true
     else
@@ -89,7 +89,7 @@ get_debian_version_number() {
 }
 
 get_boot_config_path() {
-    if [ "$(is_raspian)" = true ]; then
+    if [ "$(is_raspbian)" = true ]; then
         local debian_version_number=$(get_debian_version_number)
 
         # Bullseye and lower

diff --git a/installation/install-jukebox.sh b/installation/install-jukebox.sh
@@ -86,9 +86,9 @@ Check install log for details:"
   exit 1
 }
 
-# Check if current distro is a 32 bit version
-# Support for 64 bit Distros has not been checked (or precisely: is known not to work)
-# All RaspianOS versions report as machine "armv6l" or "armv7l", if 32 bit (even the ARMv8 cores!)
+# Check if current distro is a 32-bit version
+# Support for 64-bit Distros has not been checked (or precisely: is known not to work)
+# All Raspberry Pi OS versions report as machine "armv6l" or "armv7l", if 32-bit (even the ARMv8 cores!)
 _check_os_type() {
   local os_type=$(uname -m)
 
@@ -97,8 +97,8 @@ _check_os_type() {
   if [[ $os_type == "armv7l" || $os_type == "armv6l" ]]; then
     print_lc "  ... OK!\n"
   else
-    print_lc "ERROR: Only 32 bit operating systems supported. Please use a 32bit version of RaspianOS!"
-    print_lc "You can fix this problem for 64bit kernels: https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/2041"
+    print_lc "ERROR: Only 32-bit operating systems are supported. Please use a 32-bit version of Raspberry Pi OS!"
+    print_lc "For Pi 4 models or newer running a 64-bit kernels, also see this: https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/2041"
     exit 1
   fi
 }

diff --git a/src/jukebox/components/rfid/hardware/fake_reader_gui/requirements.txt b/src/jukebox/components/rfid/hardware/fake_reader_gui/requirements.txt
@@ -1,6 +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)
+# It is available on most Unix systems (but not on headless Raspberry Pi OS 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
diff --git a/src/jukebox/components/volume/__init__.py b/src/jukebox/components/volume/__init__.py
@@ -33,7 +33,7 @@
 ## Misc
 
 PulseAudio may switch the sink automatically to a connecting bluetooth device depending on the loaded module
-with name module-switch-on-connect. On RaspianOS Bullseye, this module is not part of the default configuration
+with name module-switch-on-connect. On Raspberry Pi OS Bullseye, this module is not part of the default configuration
 in ``/usr/pulse/default.pa``. So, we don't need to worry about it.
 If the module gets loaded it conflicts with the toggle on connect and the selected primary / secondary outputs
 from the Jukebox. Remove it from the configuration!
@@ -635,7 +635,7 @@ def finalize():
     global pulse_control
     # Set default output and start-up volume
     # Note: PulseAudio may switch the sink automatically to a connecting bluetooth device depending on the loaded module
-    # with name module-switch-on-connect. On RaspianOS Bullseye, this module is not part of the default configuration.
+    # with name module-switch-on-connect. On Raspberry Pi OS Bullseye, this module is not part of the default configuration.
     # So, we shouldn't need to worry about it. Still, set output and startup volume close to each other
     # to minimize bluetooth connection in between
     global pulse_control