CONFIGURE

Important

Please use the One line install command for installation. It will also automatically configure the Phoniebox and already includes most of these steps.

Some parts are outdated and must be adapt, e.g. to new filenames or lib versions.

This is only for manual configuration or if you encounter problems. Make sure to go through the installation first.

• Configure RPi OS
• Configure your Phoniebox on RPi OS
• Connecting the hardware
• Phoniebox manual

Configure RPi OS

Configure your keyboard

Only needed if not set in the Raspberry Pi Imager settings!

In the dropdown menu at the top of the home screen, select:

'Berry' > Preferences > Mouse and Keyboard Settings

Now select the tab Keyboard and then click Keyboard Layout... at the bottom right of the window. From the list, select your language layout.

Access over SSH

Only needed if not set in the Raspberry Pi Imager settings!

SSH will allow you to log into the RPi from any machine in the network. This is useful because once the Phoniebox is up and running, it won't have a keyboard, mouse or monitor attached to it. Via SSH you can still configure the system and make changes - if you must.

Open a terminal to start the RPi configuration tool.

sudo raspi-config

Select Interface Options and then SSH Enable/Disable remote command line... to enable the remote access.

You should also change your password at this stage in raspi-config. The default password after a fresh install is raspberry.

Find out more about how to connect over SSH from Windows, Mac, Linux or Android on the official RPi page.

Configure the WiFi

Only needed if not set in the Raspberry Pi Imager settings!

At the top right of the home screen, in the top bar, you find an icon for Wireless & Wired Network Settings. Clicking on this icon will bring up a list of available WiFi networks. Select the one you want to connect with and set the password.

Note: Follow this link if you have trouble with a USB Wifi card.

Important: Check the country code of your WiFi.

Disable WiFi power management

This is already included in the one-line-install script!

Make sure the WiFi power management is disabled to avoid dropouts. Firstly, check if it is switched on, type in the terminal:

iwconfig

This should return something like the following:

lo        no wireless extensions.

eth0      no wireless extensions.

wlan0     IEEE 802.11  ESSID:
          Mode:Managed  Frequency:2.437 GHz  Access Point: 34:31:C4:0A:8F:83   
          Bit Rate=72.2 Mb/s   Tx-Power=31 dBm
          Retry short limit:7   RTS thr:off   Fragment thr:off
          Power Management:on
          Link Quality=63/70  Signal level=-47 dBm  
          Rx invalid nwid:0  Rx invalid crypt:0  Rx invalid frag:0
          Tx excessive retries:2  Invalid misc:0   Missed beacon:0

The line Power Management:on is important: out of the box, it seems to be switched on, so let's switch it off, type:

sudo iwconfig wlan0 power off

And then check again with iwconfig that the line now says: Power Management:off.

Set a static IP address for your RPi

This is already included in the one-line-install script! This configuration works only for dhcpcd. Since Raspberry Pi OS Bookworm NetworkManager is the new default.

To be able to log into your RPi over SSH from any machine in the network, you need to give your machine a static IP address.

Check if the DHCP client daemon (DHCPCD) is active.

sudo service dhcpcd status

If you don't get any status, you should start the dhcpcd daemon:

sudo service dhcpcd start
sudo systemctl enable dhcpcd

Check the IP address the RPi is running on at the moment:

$ ifconfig

wlan0     Link encap:Ethernet  HWaddr 74:da:38:28:72:72  
          inet addr:192.168.178.82  Bcast:192.168.178.255  Mask:255.255.255.0
          ...

You can see that the IP address is 192.168.178.82. We want to assign a static address 192.168.178.199.

Note: assigning a static address can create conflict with other devices on the same network which might get the same address assigned. Therefore, if you can, check your router configuration and see if you can assign a range of IP addresses for static use.

Change the IPv4 configuration inside the file /etc/dhcpcd.conf.

sudo nano /etc/dhcpcd.conf

Don't be surprised, if the file is empty. Then only add the lines below. In my case, I added the following lines to assign the static IP. You need to adjust this to your network needs:

interface wlan0
static ip_address=192.168.178.201/24
static routers=192.168.178.1
static domain_name_servers=192.168.178.1

Save the changes with Ctrl & O then Enter then Ctrl & X.

Installation and configuration via SSH / headless installation

Only needed if not set in the Raspberry Pi Imager settings! This configuration works only for dhcpcd. Since Raspberry Pi OS Bookworm NetworkManager is the new default.

Setting up the Phoniebox via a SSH connection saves the need for a monitor and a mouse.

• Install a RPi OS 'lite'-Version as described here

• Eject the card and insert it again to your computer. This should get the boot partition mounted.

• In the boot partition, create a new empty file called ssh (no file extension). This will enable the SSH server later.

• Create another file in the same place called wpa_supplicant.conf. Set the file content according to the following example:

  ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
  update_config=1
  country=DE
  network={
     ssid="YOUR_NETWORK_NAME"
     psk="YOUR_PASSWORD"
     key_mgmt=WPA-PSK
  }
  

  Replace DE with your 2-letter ISO code for your country The mentioned ISO code is DE for Germany, US for USA... Complete list can be found here.

  Note: This works for WPA-secured wifi networks, which should be the vast majority.

• Save the file

• Unmount and eject the card, insert it into the Raspy, boot.

• Find out the IP address of the raspberry. Most Wifi routers have a user interface that lists all devices in the network with the IP address they got assigned.

• Connect via ssh with username pi and password raspberry.

Sources

• how-to-set-up-wifi-on-your-raspberry-pi-without-ethernet
• how-to-enable-ssh-on-raspbian-without-a-screen
• Connect to WiFi in Linux using NMCLI command

Configure your Phoniebox on RPi OS

Identify and configure your RFID reader

MUST READ: if you encounter problems, please read this page in the wiki: RFID Reader Special

The RFID reader is connected to your RPi via USB. As you plug it in, it should have made a 'beep'. And each time you swipe a keyring or card across the card reader, it should also make a 'beep'.

Let's see if your reader is probably connected and recognised by your RPi. Check the following:

1. The LED on the reader is on.
2. When swiping a card or keyring, you hear a 'beep' noise.

If you can answer both with yes, you can be 90% sure all is working well. Just to be 100% sure, here are a few command to type on the command line which should list your reader.

ls -la /dev/input/by-id/

In my case, this will list the Barcode Reader and show that the system can interact with the device under event0:

lrwxrwxrwx 1 root root   9 Apr 30 09:55 usb-Sycreader_USB_Reader_08FF20150112-event-kbd -> ../event1

Register your USB device for the Phoniebox

Now we know a lot about the RFID reader attached to our RPi. In order to use it as a controller for our Phoniebox, the software needs to know which device to listen to.

To register your device, go to the directory containing all the scripts and run the file RegisterDevice.py.

cd /home/pi/RPi-Jukebox-RFID/scripts/
python3 RegisterDevice.py

This will bring up a list of one or more devices. Spot the device you are using as a RFID reader, type the number (in this case 2) and hit Enter.

Choose the reader from list
0 Chicony USB Keyboard
1 Chicony USB Keyboard
2 Sycreader USB Reader
3 Logitech USB-PS/2 Optical Mouse 

You can check if your device was registered properly by taking a look inside the file that was just generated, called deviceName.txt.

cat deviceName.txt

Now your Phoniebox knows which device to listen to when you are swiping your cards or keyrings.

Copy the RFID chip configuration file

Inside the directory /home/pi/RPi-Jukebox-RFID/settings/ you find the file rfid_trigger_play.conf.sample You need to make a copy of this files, to avoid overwriting changes if the content might change in the git repo.

Inside this conf file, you can add IDs from RFID cards to control the functionality of the Phoniebox. See the content of the file for more explanation.

cd /home/pi/RPi-Jukebox-RFID/settings/
cp rfid_trigger_play.conf.sample rfid_trigger_play.conf
sudo chown pi:pi rfid_trigger_play.conf
sudo chmod 665 rfid_trigger_play.conf

Create settings for audio playout

Creating files for the settings folder which contain the short name of the amixer iface used and the percentage the volume increase or decreases when using the volumeup and volumedown function.

Troubleshooting:

• Inside settings/Audio_iFace_Name is the iFace name of the sound card. By default for the RPi this would be PCM. But this does not work for every setup. If you are using phatbeat as a DAC for example, you need to change the content of Audio_iFace_Name from PCM to Master or Speaker. Other external sound cards might use different interface names. To see if PCM could work for you, type sudo amixer sget PCM. To list all available iFace names, type sudo amixer scontrols.
• If one is using an audio amplifier (like the pHAT BEAT) without a physical volume limiter (like a potentiometer) your Phoniebox can get very loud "accidentally". The maximal volume can be set in settings/Max_Volume_Limit.

echo "PCM" > /home/pi/RPi-Jukebox-RFID/settings/Audio_iFace_Name
echo "3" > /home/pi/RPi-Jukebox-RFID/settings/Audio_Volume_Change_Step
echo "100" > /home/pi/RPi-Jukebox-RFID/settings/Max_Volume_Limit
echo "0" > /home/pi/RPi-Jukebox-RFID/settings/Idle_Time_Before_Shutdown

Install MPD, the music player daemon

Music Player Daemon (MPD) is a flexible, powerful, server-side application for playing music. Through plugins and libraries it can play a variety of sound files while being controlled by its network protocol. While MPD is running in the background, MPC acts like a player 'on top'.

You need to change the configuration file.

sudo nano /etc/mpd.conf

Find these options and change to the following:

• music_directory "/home/pi/RPi-Jukebox-RFID/shared/audiofolders"
• playlist_directory "/home/pi/RPi-Jukebox-RFID/playlists"
• user "root"
• auto_update "yes" (you have to remove the # in front of that line)
• auto_update_depth "10" (remove the # and change the value to 10)
• mixer_control "yourAudioIfaceNameHere" (you need to uncomment this line and change the audio iFace shortname)

Maybe you need to change the audio iFace ("yourAudioIfaceNameHere") in the config file, too. By default it uses PCM which should work out of the box. If it doesn't, type in terminal:

sudo amixer scontrols

This should create an output similar to this:

Simple mixer control 'Speaker',0
Simple mixer control 'Mic',0
Simple mixer control 'Auto Gain Control',0

In which case, instead of PCM you need to use Speaker.

Then you need to update mpc:

mpc update

Samba: Share files and folder over your home network

To make the Phoniebox easy to administer, it is important that you can add new songs and register new RFID cards over your home network. This can be done from any machine. The way to integrate your RPi into your home network is using Samba, the standard Windows interoperability suite for Linux and Unix.

Open a terminal and install the required packages with this line:

sudo apt install samba samba-common smbclient

First, let's edit the Samba configuration file and define the workgroup the RPi should be part of.

sudo nano /etc/samba/smb.conf

Edit the entries for workgroup and wins support:

workgroup = WORKGROUP
wins support = yes

If you are already running a windows home network, add the name of the network where I have added WORKGROUP.

Now add the specific folder that we want to be exposed to the home network in the smb.conf file.

[phoniebox]
   comment=Pi Jukebox
   path=/home/pi/RPi-Jukebox-RFID/shared
   browseable=Yes
   writeable=Yes
   only guest=no
   create mask=0777
   directory mask=0777
   public=no
   veto files=/._*/.DS_Store/

Note: the path given in this example works (only) if you are installing the Phoniebox code in the directory /home/pi/.

If the audio files are not inside the shared folder, you might want to add another section to the config file. Otherwise you can not manage audio files over the samba / windows network. This might look like this - changing the path to your needs:

[phoniebox_audio]
   comment=Pi Jukebox
   path=/path/to/audiofolders
   browseable=Yes
   writeable=Yes
   only guest=no
   create mask=0777
   directory mask=0777
   public=no
   veto files=/._*/.DS_Store/

Finally, add the user pi to Samba. For simplicity and against better knowledge regarding security, I suggest to stick to the default user and password:

user     : pi
password : raspberry

Type the following to add the new user:

sudo smbpasswd -a pi

Running the web app

There is a second way to control the RFID Phoniebox: through the browser. You can open a browser on your phone or computer and type in the static IP address that we assigned to the RPi earlier. As long as your phone or PC are connected to the same WiFi network that the RPi is connected to, you will see the web app in your browser.

File upload via web app: changes in php.ini

The Phoniebox web app allows to upload files through the web app. To do so, php needs to understand that it is allowed to ignore files sizes and maximum size per file and the like. Such restrictions are set in the file /etc/php/7.0/fpm/php.ini. What you need to change (or use the sample script in the following step) are these variables - they need to be changed to read like the following:

file_uploads = On
upload_max_filesize = 0
max_file_uploads = 20
post_max_size = 0

Copy the php.ini file to the right place and change the user and access rights:

sudo cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/php.ini-default.sample /etc/php/7.0/fpm/php.ini
sudo chown root:root /etc/php/7.0/fpm/php.ini
sudo chmod 644 /etc/php/7.0/fpm/php.ini

If you don't want to reboot your Phoniebox, you need to restart php7.0-fpm to load the new php.ini file.

sudo service php7.0-fpm restart

Make a copy of the web app config file

There is a sample config file in the htdocs folder which you need to copy to config.php. This assures that you can make changes to config.php which will not be affected by updates in the upstream repository.

sudo cp /home/pi/RPi-Jukebox-RFID/htdocs/config.php.sample /home/pi/RPi-Jukebox-RFID/config.php

Make sure the shared and htdocs folders are accessible by the web server:

sudo chown -R pi:www-data /home/pi/RPi-Jukebox-RFID/shared
sudo chmod -R 775 /home/pi/RPi-Jukebox-RFID/shared
sudo chown -R pi:www-data /home/pi/RPi-Jukebox-RFID/htdocs
sudo chmod -R 775 /home/pi/RPi-Jukebox-RFID/htdocs

If your audiofiles are not in the shared folder, you may want to make them accessible by the web server as well:

sudo chown -R pi:www-data /path/to/your/audiofiles
sudo chmod -R 775 /path/to/your/audiofiles

Auto-start the Phoniebox

This is the final tweak to the configuration: automatically start our Phoniebox software after the RPi has booted and have it listen to RFID cards. The Raspberry Pi OS uses systemd to start the components.

Systemd will launch the required services after booting AND take care of restarting the script in case they die.

First copy the service config files to the correct directory:

sudo cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/phoniebox-rfid-reader.service-default.sample /etc/systemd/system/phoniebox-rfid-reader.service
sudo cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/phoniebox-startup-sound.service-default.sample /etc/systemd/system/phoniebox-startup-sound.service
sudo cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/phoniebox-gpio-control.service.sample /etc/systemd/system/phoniebox-gpio-control.service
sudo cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/phoniebox-idle-watchdog.service.sample /etc/systemd/system/phoniebox-idle-watchdog.service

Now systemd has to be notified that there are new service files:

sudo systemctl daemon-reload

Now enable the service files, which will start them on reboot:

sudo systemctl enable phoniebox-idle-watchdog
sudo systemctl enable phoniebox-rfid-reader
sudo systemctl enable phoniebox-startup-sound
sudo systemctl enable phoniebox-gpio-control

And now you can reboot to have your daemons running or start them manually:

sudo systemctl start phoniebox-idle-watchdog
sudo systemctl start phoniebox-rfid-reader
sudo systemctl start phoniebox-startup-sound
sudo systemctl start phoniebox-gpio-buttons

The newly installed service can be started either by rebooting the Phoniebox or with: sudo systemctl start phoniebox-rfid-reader

To see if the reader process is running use the following command:

sudo systemctl status phoniebox-rfid-reader

This should produce an output like this:

pi@Jukebox:~ $ systemctl status phoniebox-rfid-reader
 * phoniebox-rfid-reader.service - RFID-Reader Service
   Loaded: loaded (/etc/systemd/system/phoniebox-rfid-reader.service; enabled; vendor pres
   Active: active (running) since Fri 2018-04-13 07:34:53 UTC; 5h 47min ago
 Main PID: 393 (python2)
   CGroup: /system.slice/phoniebox-rfid-reader.service
           └─393 /usr/bin/python2 /home/pi/RPi-Jukebox-RFID/scripts/daemon_rfid_

Apr 13 07:34:53 Jukebox systemd[1]: Started RFID-Reader Service.

The mp3s for startup and shutdown sound have to be copied to the right folder. You may use your own sound files as well.

cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/startupsound.mp3.sample /home/pi/RPi-Jukebox-RFID/shared/startupsound.mp3
cp /home/pi/RPi-Jukebox-RFID/misc/sampleconfigs/shutdownsound.mp3.sample /home/pi/RPi-Jukebox-RFID/shared/shutdownsound.mp3

Reboot your Raspberry Pi

Ok, after all of this, it's about time to reboot your Phoniebox. Make sure you have the static IP address at hand to login over SSH after the reboot.

sudo reboot

Connecting the hardware

Once the software is all in place, make sure the hardware is connected correctly.

1. Connect a USB hub with the power supply. From this hub, connect the RPi to one plug and the USB powered speakers to another. Do not connect the speakers to the USB of the RPi, because the power coming from the RPi might not be enough to run the speakers.
2. You need a number of USB plugs to connect the following and therefore possibly need a second USB hub to connect to the RPi USB:
   • RFID card reader
   • WiFi dongle (WLAN adapter for RPi < version 3)
   • External soundcard (optional)
3. Connect the speakers with the 3.5mm jack to the soundcard (either the built in one from the RPi or the external one attached to the RPi over USB).

Using a USB soundcard

In order to use an external USB soundcard instead of the inbuilt audio out, you might need to update your system and tweak a couple of config files, depending on your card. The most comprehensive explanation on why and how, you can find at adafruit.

Using the Jessie distribution, you might be lucky and there is a quick fix setting the ~/.asoundrc file.

Push buttons (GPIO) for volume control and the like

Adding control buttons for volume, skipping tracks, pause, play, read the GPIO buttons installation guide.

Phoniebox manual

Now the installation and configuration are complete. Time to read the manual of the Phoniebox to add songs, web streams, register new cards and so on. Read the Manual.