Skip to content

Commit

Permalink
Update CAR INSTALL.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@mikebrady
mikebrady authored Oct 30, 2023
1 parent 40306cc commit 84a214d
Showing 1 changed file with 90 additions and 105 deletions.
195 changes: 90 additions & 105 deletions CAR INSTALL.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,11 +70,10 @@ $ ./configure --sysconfdir=/etc --with-alsa \
--with-soxr --with-avahi --with-ssl=openssl --with-systemd --with-airplay-2
$ make
# make install
# systemctl enable shairport-sync
```
The `autoreconf` step may take quite a while – please be patient!

**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.

### Configure Shairport Sync
Here are the important options for the Shairport Sync configuration file at `/etc/shairport-sync.conf`:
```
Expand Down Expand Up @@ -106,6 +105,8 @@ A number of packages to enable the Pi to work as a WiFi base station are needed:
```
# apt install --no-install-recommends hostapd isc-dhcp-server
```
(The installer will get errors trying to set up both of these services; the errors can be ignored.)

Disable both of these services from starting at boot time (this is because we will launch them sequentially later on):
```
# systemctl unmask hostapd
Expand Down Expand Up @@ -160,158 +161,142 @@ INTERFACESv4="wlan0"
INTERFACESv6=""
```
### Set up the Startup Sequence
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:
Configure the startup sequence by adding commands to `/etc/rc.local` to start `hostapd` and the `dhcp` automatically after startup. Its contents should look like this:
```
#!/bin/sh -e
#
# rc.local
#
# This script is executed at the end of each multiuser runlevel.
# Make sure that the script will "exit 0" on success or any other
# value on error.
# Uncomment the next line to exit the script here, skipping the remainder of the script where the WiFi access point and Shairport Sync itself are started.
# exit 0 # uncomment this line to exit the script here
# Shairport Sync is automatically started as a service on startup.
/sbin/iw dev wlan0 set power_save off
/usr/sbin/hostapd -B -P /run/hostapd.pid /etc/hostapd/hostapd.conf
/sbin/ip addr add 10.0.10.1/24 dev wlan0
/bin/sleep 1
/bin/systemctl start isc-dhcp-server
/bin/sleep 2
/bin/systemctl start shairport-sync
# If MODE is set to RUN, the system will start the WiFi access point.
exit 0 # normal exit here
```
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.
# If MODE is set to anything else, e.g. DEV, the system will not start the WiFi access point.
# Instead, you can connect the system to a network.
# If it still has the WiFi credentials of the last WiFi network it connected to,
# it can connect to it automatically.
### Final Steps
You should now disable either the `NetworkManager` or the `dhcpcd` service (whichever is in your system) so that they won't run when the system reboots. You can find out which is in your system using the `ps -aux` command and looking for either `NetworkManager` or `dhcpcd`. Here is an example from a system running `dhcpcd`:
```
$ ps aux | grep 'NetworkManager\|dhcpcd' | grep -v grep
root 596 0.0 0.2 3112 2216 ? Ss Oct08 0:51 /usr/sbin/dhcpcd -w -q
```
Once you have identified which service to disable, perform the appropriate one of the following commands:
```
# systemctl disable NetworkManager
```
or
```
# systemctl disable dhcpcd
```
Now you should also disable the `wpa_supplicant` service.
MODE=RUN
```
# systemctl disable wpa_supplicant
```
/sbin/iw dev wlan0 set power_save off # always do this
From this point on, at least on the Raspberry Pi, if you were to power off and reboot the machine, it would not reconnect to your network. Instead, it would act as the WiFi base station you have configured with `hostapd` and `isc-dhcp-server`.
if test $MODE = RUN ; then
**Note:** The WiFi credentials you used to connect to the initial network (e.g. your home network) will have been stored in the system in plain text. This is convenient for when you want to reconnect to update (see later), but if you wish to delete them for any reason, they will be in `/etc/wpa_supplicant/wpa_supplicant.conf`
# If script execution gets in here, it starts the WiFi access point.
/usr/sbin/hostapd -B -P /run/hostapd.pid /etc/hostapd/hostapd.conf
/sbin/ip addr add 10.0.10.1/24 dev wlan0
/bin/systemctl start isc-dhcp-server
else
When you are finished (including any optional steps below), carefully power down the machine before unplugging it from power:
```
# poweroff
# If script execution gets in here, it starts services needed for normal operation.
/bin/systemctl start systemd-timesyncd || :
/bin/systemctl start dhcpcd || /bin/systemctl start NetworkManager || :
fi
exit 0 # normal exit here
```
#### Optional: Optimise startup time – Raspberry Pi Specific
These optional steps have been tested on a Raspberry Pi only. They have not been tested on other systems.
Some services are not necessary for this setup. These commands disable them:

#### Disable Unused Services
These optional steps have been tested on a Raspberry Pi only -- they have not been tested on other systems.
Some services are not necessary for this setup and can be disabled as follows:
```
# systemctl disable systemd-timesyncd
# systemctl disable keyboard-setup
# systemctl disable triggerhappy
# systemctl disable dphys-swapfile
```
#### Optional: Read-only mode – Raspberry Pi Specific
This optional step is applicable to a Raspberry Pi only. 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.
This optional step is applicable to a Raspberry Pi only. 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. (The idea here is that this offers more protection against files being corrupted by the sudden removal of power.)

### Final Steps

You now need to disable some services; that is, you need to stop them starting automatically on power-up. This is because they either interfere with the system's operation in WiFi Access Point mode, or because they won't work when the system isn't connected to the Internet. Only one of the `NetworkManager` and the `dhcpcd` service will be present in your system, but it's no harm to try to disable both.
```
# systemctl disable dhcpcd
# systemctl disable NetworkManager
# systemctl disable wpa_supplicant
# systemctl disable systemd-timesyncd
```
Lastly, note that the WiFi credentials you used initially to connect to your network (e.g. your home network) will have been stored in the system in plain text. This is convenient for when you want to reconnect to update (see later), but if you prefer to delete them, they will be in `/etc/wpa_supplicant/wpa_supplicant.conf`

When you are finished, carefully power down the machine before unplugging it from power:
```
# poweroff
```
### Ready
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.

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.
When the power source is switched on -- typically when you start the car -- it will take around 35 seconds for the system to become available (timing based on a Raspberry Pi Zero 2 W running Bookworm).

### Enjoy!
---
## Updating
From time to time, you may wish to update this installation. Assuming you haven't deleted your original WiFi network credentials, 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.
From time to time, you may wish to update this installation. Assuming you haven't deleted your original WiFi network credentials, the easiest thing is to temporarily reconnect to the network you used when you created the system. You can then update the operating system and libraries in the normal way and then update Shairport Sync.

Note that if you're upgrading the operating system to e.g. from Bullseye to Bookworm, the names and index numbers of the output devices may change, and the names of the mixer controls may also change. You can use [`sps-alsa-explore`](https://github.com/mikebrady/sps-alsa-explore) to discover device names and mixer names.
However, if you're *upgrading* the operating system to e.g. from Bullseye to Bookworm, the names and index numbers of the output devices may change, and the names of the mixer controls may also change. You can use [`sps-alsa-explore`](https://github.com/mikebrady/sps-alsa-explore) to discover device names and mixer names.

To update, take the following steps:
### Temporarily reconnect to the original network and update
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:
#### Exit Raspberry Pi Read-Only Mode
If it's a Raspberry Pi and you have optionally enabled the read-only mode, you must take the device out of Read-only mode:
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.
#### Undo Optimisations
If you have disabled any of the services listed in the [Disable Unused Services](#disable-unused-services) section, you should re-enable them. (But *do not* re-eneable `NetworkManager`, `dhcpcd`, `wpa_supplicant` or `systemd-timesyncd` -- they are handled specially by the startup script.)
#### Perform Legacy Updates
Over time, the arrangements by which the system is prepared for operation has changed to make it easier to revert to normal operation when necessary for maintenance, updates, etc. A small number of the old settings need to be changed to bring them up to date with the present arrangements. Once the required changes have been made, your system will be ready for the update process detailed below. Here are those legacy changes you need to make, just once:

2. Undo a modification you may have made during previous installations.

Remove a possible modification from a file. If there is a file called `/etc/dhcpcd.conf` and if the first line reads:
1. If there is a file called `/etc/dhcpcd.conf` and if the first line reads:
```
denyinterfaces wlan0
```
then delete that line or comment it out -- it it no longer needed going forward.
If the file `/etc/dhcpcd.conf` doesn't exist, or if the first line is not `denyinterfaces wlan0` as given here, then you don't need to do anything.

(The reason for this suggestion is that a simpler way is now used to prevent the `dhcpcd` service from trying to manage the interface -- the `dhcpcd` service is now completely disabled.)
then delete that line -- it is no longer needed and will cause problems in future if it remains there.

If the file `/etc/dhcpcd.conf` doesn't exist, or if the first line is not `denyinterfaces wlan0`, then you don't need to do anything.

2. Replace the contents of the file `/etc/rc.local` with the new contents given [above](#set-up-the-startup-sequence).

4. Re-enable either `NetworkManager` or `dhcpcd` as appropriate:
3. Disable a number of services as follows. Only one of the `NetworkManager` and the `dhcpcd` service will be present in your system, but it's no harm to try to disable both.
```
# systemctl enable NetworkManager
```
or
```
# systemctl enable dhcpcd
# systemctl disable dhcpcd
# systemctl disable NetworkManager
# systemctl disable wpa_supplicant
# systemctl disable systemd-timesyncd
```
(Just FYI, even though the `wpa_supplicant` service has previously been disabled from starting automatically, it will be turned on by `NetworkManager` or `dhcpcd` after reboot.)

5. If you had disabled the `systemd-timesyncd` service as suggested in the "Optimise startup time -- Raspberry Pi Specific" section, you need to temporarily re-enable it:
4. Enable the `shairport-sync` service itself:
```
# systemctl enable systemd-timesyncd
# systemctl enable shairport-sync
```
This is needed because the correct time is necessary for detemininig what has been updated.

6. Edit `/etc/rc.local` to exit the script before enabling the WiFi access point and starting Shairport Sync. Do this by uncommenting the line:
Once you have made these one-off legacy updates, you can proceed to the next stage -- performing the update.
### Performing the Update
To update, take the following steps:
#### Temporarily reconnect to a network and update
1. Edit the startup script in `/etc/rc.local` to so that the system is no longer in the RUN mode.
To do that, change line 15 so that it goes from this:
```
# exit 0 # uncomment this line to exit the script here
MODE=RUN
```
so that it looks like this:
to this:
```
exit 0 # uncomment this line to exit the script here
MODE=DEV
```
Save the changes.

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.
Do not be tempted to insert any spaces anywhere -- Unix scripting syntax is very strict!

7. Reboot and do normal updating.
2. Save and close the file and reboot. From this point on, the system will start normally and can be connected to a network. If it still has the WiFi credentials of the last network it was connected to, then it could automatically reconnect.

### Revert to normal operation
When you are finished updating, you need to undo the temporary changes you made to the setup, as follows:
The system is now ready for updating in the normal way.
#### Revert to normal operation
When you are finished updating, you need to put the system back into its RUN mode, as follows:

1. First, disable `NetworkManager` or `dhcpcd` as appropriate:
```
# systemctl disable NetworkManager
1. Edit the startup script in `/etc/rc.local` to so that the MODE variable is set to RUN.
To do that, change line 15 so that it goes from this:
```
or
MODE=DEV
```
# systemctl disable dhcpcd
```
2. Also, ensure that the `wpa_supplicant` service is disabled.
```
# systemctl disable wpa_supplicant
to this:
```
3. Next, if you had temporarily re-enabled services that are normally disabled, then it's time to disable them again:
MODE=RUN
```
# systemctl disable systemd-timesyncd
```
4. Edit `/etc/rc.local` to perform the entire script before exiting, so that it enables the WiFi access point and starts Shairport Sync. Do this by commenting out the line:
```
exit 0 # uncomment this line to exit the script now
```
so that it loooks like this:
```
# exit 0 # uncomment this line to exit the script now
```
Save the changes.

5. Reboot. The system should start as it would if it was in the car.
Once again, do insert any spaces anywhere.

5. 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.

2. Save and close the file and reboot. The system should start as it would if it was in the car.

0 comments on commit 84a214d

Please sign in to comment.