CAR INSTALL.md

   1 # Shairport Sync for Cars
   2 If your car audio has an AUX input, you can get AirPlay in your car using Shairport Sync. Together, Shairport Sync and an iPhone or an iPad with cellular capability can give you access to internet radio, YouTube, Apple Music, Spotify, etc. on the move. While Shairport Sync is no substitute for CarPlay, the audio quality is often much better than Bluetooth.
   3
   4 ## The Basic Idea
   5
   6 The basic idea is to use a small Linux computer to create an isolated WiFi network (a "car network") and run Shairport Sync on it to provide an AirPlay service. An iPhone or an iPad with cellular capability can simultaneously connect to internet radio, YouTube, Apple Music, Spotify, etc. over the cellular network and send AirPlay audio through the car network to the AirPlay service provided by Shairport Sync. This sends the audio to the computer's DAC which is connected to the AUX input of your car audio.
   7
   8 Note that Android devices can not, so far, do this trick of using the two networks simultaneously.
   9
  10 ## Example
  11
  12 **Important Note** This guide can not be used for the latest (time of writing: October 2023) version of Rasberry Pi OS (Bookworm) because the `dhcpcd` package is no longer part of the system. It does work for Rasberry Pi OS (Bullseye)
  13
  14 In this example, a Raspberry Pi Zero 2 W and a Pimoroni PHAT DAC are used. Shairport Sync will be built for AirPlay 2 operation, but you can build it for "classic" AirPlay (aka AirPlay 1) operation if you prefer. A Pi Zero W is powerful enough for classic AirPlay.
  15
  16 Please note that some of the details of setting up networks are specific to the version of Linux used.
  17
  18 ### Prepare the initial SD Image
  19 * Download Raspberry Pi OS Bullseye (Lite) and install it onto an SD Card using `Raspberry Pi Imager`. The Lite version is preferable to the Desktop version as it doesn't include a sound server like PulseAudio or PipeWire that can prevent direct access to the audio output device.
  20 * Before writing the image to the card, use the Settings control on `Raspberry Pi Imager` to set hostname, enable SSH and provide a username and password to use while building the system. Similarly, you can specify a wireless network the Pi will connect to while building the system. Later on, the Pi will be configured to start its own isolated network.
  21 * The next few steps are to add the overlay needed for the sound card. This may not be necessary in your case, but in this example a Pimoroni PHAT is being used. If you do not need to add an overlay, skip these steps.
  22   * Mount the card on a Linux machine. Two drives should appear – a `boot` drive and a `rootfs` drive.
  23   * `cd` to the `boot` drive (since my username is `mike`, it will be `$ cd /media/mike/boot`).
  24   * Edit the `config.txt` file to add the overlay needed for the sound card. This may not be necessary in your case, but in this example a Pimoroni PHAT is being used and it needs the following entry to be added:
  25     ```
  26     dtoverlay=hifiberry-dac
  27     ```
  28   * Close the file and carefully dismount and eject the two drives. *Be sure to dismount and eject the drives properly; otherwise they may be corrupted.*
  29 * Remove the SD card from the Linux machine, insert it into the Pi and reboot.
  30
  31 After a short time, the Pi should appear on your network – it may take a minute or so. To check, try to `ping` it at the `<hostname>.local`, e.g. if the hostname is `bmw` then use `$ ping bmw.local`. Once it has appeared, you can SSH into it and configure it.
  32
  33 ### Boot, Configure, Update
  34 The first thing to do on a Pi would be to use the `raspi-config` tool to expand the file system to use the entire card. Next, do the usual update and upgrade:
  35 ```
  36 # apt-get update
  37 # apt-get upgrade
  38 ```
  39
  40 ### Build and Install
  41 Let's get the tools and libraries for building and installing Shairport Sync (and NQPTP).
  42
  43 ```
  44 # apt install --no-install-recommends build-essential git xmltoman autoconf automake libtool \
  45     libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev \
  46     libplist-dev libsodium-dev libavutil-dev libavcodec-dev libavformat-dev uuid-dev libgcrypt-dev xxd
  47 ```
  48 If you are building classic Shairport Sync, the list of packages is shorter:
  49 ```
  50 # apt-get install --no-install-recommends build-essential git xmltoman autoconf automake libtool \
  51     libpopt-dev libconfig-dev libasound2-dev avahi-daemon libavahi-client-dev libssl-dev libsoxr-dev
  52 ```
  53
  54 #### NQPTP
  55 Skip this section if you are building classic Shairport Sync – NQPTP is not needed for classic Shairport Sync.
  56
  57 Download, install, enable and start NQPTP from [here](https://github.com/mikebrady/nqptp) following the guide for Linux.
  58
  59 #### Shairport Sync
  60 Download Shairport Sync, check out the `development` branch and configure, compile and install it.
  61
  62 * Omit the `--with-airplay-2` from the `./configure` options if you are building classic Shairport Sync.
  63
  64 ```
  65 $ git clone https://github.com/mikebrady/shairport-sync.git
  66 $ cd shairport-sync
  67 $ autoreconf -fi
  68 $ ./configure --sysconfdir=/etc --with-alsa \
  69     --with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
  70 $ make
  71 # make install
  72 ```
  73 The `autoreconf` step may take quite a while – please be patient!
  74
  75 **Note:** *Do not* enable Shairport Sync to start automatically at boot time – later on in this installation, we will arrange for it to start after the network has been set up.
  76
  77 ### Configure Shairport Sync
  78 Here are the important options for the Shairport Sync configuration file at `/etc/shairport-sync.conf`:
  79 ```
  80 // Sample Configuration File for Shairport Sync for Car Audio with a Pimoroni PHAT
  81 general =
  82 {
  83         name = "BMW Radio";
  84         ignore_volume_control = "yes";
  85         volume_max_db = -3.00;
  86 };
  87
  88 alsa =
  89 {
  90         output_device = "hw:1"; // the name of the alsa output device. Use "alsamixer" or "aplay" to find out the names of devices, mixers, etc.
  91 };
  92
  93 ```
  94 Two `general` settings are worth noting. First, the option to ignore the sending device's volume control is enabled. This means that the car audio's volume control is the only one that affects the audio volume. Of course this is a matter of personal preference.
  95 Second, the maximum output offered by the DAC to the AUX port of the car audio can be reduced if it is overloading the input circuits. Again, that's a matter for personal selection and adjustment.
  96
  97 The `alsa` settings are for the Pimoroni PHAT – it does not have a hardware mixer, so no `mixer_control_name` is given.
  98
  99 Note that the DAC's 32-bit capability is automatically selected if available, so there is no need to set it here. Similarly, since `soxr` support is included in the build, `soxr` interpolation will be automatically enabled if the device is fast enough.
 100
 101 ### Extra Packages
 102 A number of packages to enable the Pi to work as a WiFi base station are needed:
 103 ```
 104 # apt-get install hostapd isc-dhcp-server
 105 ```
 106 Disable both of these services from starting at boot time (this is because we will launch them sequentially later on):
 107 ```
 108 # systemctl unmask hostapd
 109 # systemctl disable hostapd
 110 # systemctl disable isc-dhcp-server
 111 ```
 112 #### Configure HostAPD
 113 Configure `hostapd` by creating `/etc/hostapd/hostapd.conf` with the following contents which will set up an open network with the name BMW. You might wish to change the name:
 114 ```
 115 # Thanks to https://wiki.gentoo.org/wiki/Hostapd#802.11b.2Fg.2Fn_triple_AP
 116
 117 # The interface used by the AP
 118 interface=wlan0
 119
 120 # This is the name of the network -- yours may be different
 121 ssid=BMW
 122
 123 # "g" simply means 2.4GHz band
 124 hw_mode=g
 125
 126 # Channel to use
 127 channel=11
 128
 129 # Limit the frequencies used to those allowed in the country
 130 ieee80211d=1
 131
 132 # The country code
 133 country_code=IE
 134
 135 # Enable 802.11n support
 136 ieee80211n=1
 137
 138 # QoS support, also required for full speed on 802.11n/ac/ax
 139 wmm_enabled=1
 140
 141 ```
 142 Note that, since the car network is isolated from the Internet, you don't really need to secure it with a password.
 143
 144 #### Configure DHCP server
 145
 146 First, replace the contents of `/etc/dhcp/dhcpd.conf` with this:
 147 ```
 148 subnet 10.0.10.0 netmask 255.255.255.0 {
 149      range 10.0.10.5 10.0.10.150;
 150      #option routers <the-IP-address-of-your-gateway-or-router>;
 151      #option broadcast-address <the-broadcast-IP-address-for-your-network>;
 152 }
 153 ```
 154 Second, modify the `INTERFACESv4` entry at the end of the file `/etc/default/isc-dhcp-server` to look as follows:
 155 ```
 156 INTERFACESv4="wlan0"
 157 INTERFACESv6=""
 158 ```
 159 ### Set up the Startup Sequence
 160 Configure the startup sequence by adding commands to `/etc/rc.local` to start `hostapd` and the `dhcp` server and then to start `shairport-sync` automatically after startup. Its contents should look like this:
 161 ```
 162 #!/bin/sh -e
 163 #
 164 # rc.local
 165 #
 166 # This script is executed at the end of each multiuser runlevel.
 167 # Make sure that the script will "exit 0" on success or any other
 168 # value on error.
 169 #
 170 # In order to enable or disable this script just change the execution
 171 # bits.
 172 #
 173 # By default this script does nothing.
 174
 175 /sbin/iw dev wlan0 set power_save off
 176 /usr/sbin/hostapd -B -P /run/hostapd.pid /etc/hostapd/hostapd.conf
 177 /sbin/ip addr add 10.0.10.1/24 dev wlan0
 178 /bin/sleep 1
 179 /bin/systemctl start isc-dhcp-server
 180 /bin/sleep 2
 181 /bin/systemctl start shairport-sync
 182
 183 exit 0
 184
 185 ```
 186 As you can see, the effect of these commands is to start the WiFi transmitter, give the base station the IP address `10.0.10.1`, start a DHCP server and finally start the Shairport Sync service.
 187
 188 ### Final Steps
 189 Up to now, if you reboot the Pi, it will reconnect to your WiFi network, ignoring the instructions and settings you have given it to act as a base station. That is because the `wlan0` interface is still under the control of the `dhcpcd` service. So, the final step is to instruct the `dhcpcd` service not to manage `wlan0`. To do this, edit `/etc/dhcpcd.conf` and insert the following line at the start:
 190 ```
 191 denyinterfaces wlan0
 192 ```
 193 From this point on, at least on the Raspberry Pi, if you reboot the machine, it will not reconnect to your network. Instead, it will act as the WiFi base station you have configured with `hostapd` and `isc-dhcp-server`.
 194
 195 ### Optimise startup time – Raspberry Pi Specific
 196
 197 This is applicable to a Raspberry Pi only. Some of it may be applicable to other systems, but it has not been tested on them.
 198
 199 There are quite a few services that are not necessary for this setup. Disabling them can improve startup time. Running these commands disables them:
 200
 201 ```
 202 sudo systemctl disable systemd-timesyncd.service
 203 sudo systemctl disable keyboard-setup.service
 204 sudo systemctl disable triggerhappy.service
 205 sudo systemctl disable dhcpcd.service
 206 sudo systemctl disable wpa_supplicant.service
 207 sudo systemctl disable dphys-swapfile.service
 208 sudo systemctl disable networking.service
 209 ```
 210
 211 ### Read-only mode – Raspberry Pi Specific
 212 Run `sudo raspi-config` and then choose `Performance Options` > `Overlay Filesystem` and choose to enable the overlay filesystem, and to set the boot partition to be write-protected.
 213
 214 ### Ready
 215 Install the Raspberry Pi in your car. It should be powered from a source that is switched off when you leave the car, otherwise the slight current drain will eventually flatten the car's battery.
 216
 217 When the power source is switched on, typically when you start the car, it will take maybe a minute for the system to boot up.
 218
 219 ### Enjoy!
 220
 221 ---
 222
 223 ## Updating
 224 From time to time, you may wish to update this installation. However, in order to update Shairport Sync, you must reconnect the system to a network that can access the internet. The easiest thing is to temporarily reconnect to the network you used when you created the system. To do that, you have to temporarily undo the "Final Steps" and some of the "Raspberry Pi Specific" steps you used. This will enable you to connect your device back to the network it was created on. You should then be able to update the operating system and libraries in the normal way and then update Shairport Sync.
 225
 226 So, take the following steps:
 227
 228 1. If it's a Raspberry Pi and you have enabled the Read-only mode, you must take the device out of Read-only mode:
 229 Run `sudo raspi-config` and then choose `Performance Options` > `Overlay Filesystem` and choose to disable the overlay filesystem and to set the boot partition not to be write-protected. This is so that changes can be written to the file system; you can make the filesystem read-only again later. Save the changes and reboot the system.
 230
 231 2. If you have disabled the `dhcpcd`, `wpa_supplicant` or `systemd-timesyncd` services as suggested in the "Optimise startup time -- Raspberry Pi Specific" section, you need to temporarily re-enable them:
 232 `# systemctl enable dhcpcd.service`
 233 `# systemctl enable wpa_supplicant.service`
 234 `# systemctl enable systemd-timesyncd.service`
 235 Reboot.
 236
 237 3. To allow your device to reconnect to the network it was created on, edit `/etc/dhcpcd.conf` and comment out the following line at the start:
 238 `denyinterfaces wlan0`
 239 so that it looks like this:
 240 `# denyinterfaces wlan0`
 241 From this point on, if you reboot the machine, it will connect to the network it was configured on, i.e. the network you used when you set it up for the first time. This is because the name and password of the network it was created on would have been placed in `/etc/wpa_supplicant/wpa_supplicant` when the system was initially configured and will still be there.
 242
 243 4. Reboot and do Normal Updating
 244
 245    You can perform updates in the normal way. When you are finished, you need to undo the temporary changes you made to the setup, as follows:
 246
 247 5. If you had temporarily re-enabled services that are normally disabled, then it's time to disable them again:
 248 `# systemctl disable dhcpcd.service`
 249 `# systemctl disable wpa_supplicant.service`
 250 `# systemctl disable systemd-timesyncd.service`
 251
 252 6. To re-enable the system to create its own network, edit `/etc/dhcpcd.conf` and uncomment the line that you had temporarily commented out at the start of the update. Change:
 253 `# denyinterfaces wlan0`
 254 so that it looks like this:
 255 `denyinterfaces wlan0`
 256
 257 7. Reboot. The system should start as it would if it was in the car.
 258
 259 8. If the device is a Raspberry Pi and you wish to make the file system read-only, connect to the system, run `sudo raspi-config` and then choose `Performance Options` > `Overlay Filesystem`. In there, choose to enable the overlay filesystem, and to set the boot partition to be write-protected. Do a final reboot and check that everyting is in order.