Skip to content

Commit

Permalink
Update docs (#2216)
Browse files Browse the repository at this point in the history
* 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]>
  • Loading branch information
AlvinSchiller and s-martin committed Jan 24, 2024
1 parent 6f09764 commit f6db160
Show file tree
Hide file tree
Showing 13 changed files with 93 additions and 37 deletions.
3 changes: 2 additions & 1 deletion documentation/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
22 changes: 13 additions & 9 deletions documentation/builders/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
@@ -1,6 +1,4 @@
# RFID

## Syncronisation RFID Cards
# Synchronisation RFID Cards

This component handles the synchronisation of RFID cards (audiofolder
and card database entries).
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand Down
6 changes: 1 addition & 5 deletions documentation/builders/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
44 changes: 41 additions & 3 deletions documentation/builders/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
18 changes: 18 additions & 0 deletions documentation/builders/samba.md
Original file line number Diff line number Diff line change
@@ -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>"`.


3 changes: 2 additions & 1 deletion documentation/builders/update.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
2 changes: 1 addition & 1 deletion documentation/developers/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
2 changes: 1 addition & 1 deletion documentation/developers/docstring/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down
4 changes: 2 additions & 2 deletions installation/includes/02_helpers.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down
10 changes: 5 additions & 5 deletions installation/install-jukebox.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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
}
Expand Down
Original file line number Diff line number Diff line change
@@ -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
4 changes: 2 additions & 2 deletions src/jukebox/components/volume/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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!
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit f6db160

Please sign in to comment.