mpdlistenpy/readme.md

# mpdlistenpy

This python script is supposed to run on a rpi and does the following :

 * Relay trigger : Watches a MPD instance for play/pause/stop states and activates a relay via GPIOs accordingly ; the usecase for this is powering on/off a pair of speakers only when something is running.  
 * OLED display : Drives a 0.96" OLED display (ssd1306) to display MPD status (volume, current artist, album, title...)  
 * Button input : watches GPIOs for button input ; I'm using 5 push buttons for controlling playback (previous, next, toggle playback, stop, menu) or browse the database and add stuff to the playlist.  
 * Potentiometer input : Watches a GPIO for estimating the resistance of a rotary potentiometer and set volume accordingly.  
 
## Setup

### Software

1. Install the latest **light** version of Raspberry Pi OS and run it on the RPI model of your choice.
2. Install the following dependencies (these are for mpd, the python script and filesystem handling):  
  ```
  sudo apt install --no-install-recommends --no-install-suggests mpd gvfs-fuse gvfs-backends gvfs libglib2.0-bin python3-musicpd  python3-luma.oled i2c-tools python3-pil libjpeg-dev zlib1g-dev libfreetype6-dev liblcms2-dev libopenjp2-7 libtiff5-dev exfat-fuse
  ```
3. Configure '~/.config/mpd/mpd.conf' as you please and enable mpd systemd unit :  
  ```
  systemctl --user --full enable mpd
  ```
4. See [Installing the systemd service](#installing-the-systemd-service) for installing the mpdlistenpy systemd service and start/enable it.  
5. See [Automounting Samba shares on startup](#automounting-samba-shares-on-startup) for setting up an automount service and start/enable it.  

### Hardware

#### Overall GPIOs usage

| FUNCTION | GPIO # |
| ---    | ---   |
| OLED | GND, 3.3V, 2(SDA), 3(SCL) |
| 5 BUTTONS | GND, 7, 8, 9, 11, 25 |
| POTENTIOMETER | GND, 3.3V, 23 |
| RELAY | GND, 5V, 17 |

You can check these here : [https://pinout.xyz/](https://pinout.xyz/)  

#### Oled screen

Using the SSD1306 OLED screen involves a few steps described here :

[https://luma-oled.readthedocs.io/en/latest/hardware.html](https://luma-oled.readthedocs.io/en/latest/hardware.html)

and here :

[https://luma-oled.readthedocs.io/en/latest/software.html](https://luma-oled.readthedocs.io/en/latest/software.html)

Once you've gone through these steps, you should be good to go.  

#### Relay circuit

We're using the circuit described on projects-raspberry.com :

##### Components

 * 5V DC coil relay
 * BC337 NPN transistor
 * 1N4002 [diode](https://en.wikipedia.org/wiki/1N400x_general-purpose_diodes)
 * 1KΩ resistor

##### Diagram 

![https://web.archive.org/web/20240217011938/https://projects-raspberry.com/raspberry-pi-driving-a-relay-using-gpio/](https://web.archive.org/web/20240217011938im_/https://projects-raspberry.com/wp-content/uploads/2015/04/Raspberry-Pi-%E2%80%93-Driving-a-Relay-using-GPIO2.jpg)

*source: [https://projects-raspberry.com/raspberry-pi-driving-a-relay-using-gpio/](https://web.archive.org/web/20240217011938/https://projects-raspberry.com/raspberry-pi-driving-a-relay-using-gpio/)*

#### Buttons circuit

Dead simple way described here, using a common GND, and 1 GPIO/button : 

[http://razzpisampler.oreilly.com/ch07.html](https://web.archive.org/web/20240121074741/http://razzpisampler.oreilly.com/ch07.html)

The only difference is the addition of a resistor on the GND rail.  

If you're short on GPIOs, there is a way to use a single GPIO for multiple buttons based on resistance described here : 

[https://www.instructables.com/RaspberryPi-Multiple-Buttons-On-One-Digital-Pin/](https://www.instructables.com/RaspberryPi-Multiple-Buttons-On-One-Digital-Pin/)  

#### Potentiometer circuit

Using the 'step response' method described [here](http://razzpisampler.oreilly.com/ch08.html#Discussion) (It's the same principle as in the link above),
we can use an analog potentiometer to control volume.

The solution described in the previous link is not very accurate though, so we'll be using an alternative solution offered by abyz.me.uk :

[https://abyz.me.uk/rpi/pigpio/examples.html#Python_pot_cap_py](https://abyz.me.uk/rpi/pigpio/examples.html#Python_pot_cap_py)

##### Components

 * 100nf Ceramic capacitor
 * 5KΩ Potentiometer

##### Diagram 

```
   3V3 ----- Potentiometer --+-- Capacitor ----- Ground
                             |
                             +-- GPIO 23
```

Instructions for use are in the source file. The library ('pot_cap.py') is included in this project for convenience.  

You might have to install the 'pigpio' library though :

```
sudo apt install python3-pigpio
```

You can find out more about installing 'pigpio' here :

[https://abyz.me.uk/rpi/pigpio/download.html](https://abyz.me.uk/rpi/pigpio/download.html)

## Optional steps 

### Installing the systemd service

 * Copy the provided service file 'mpdlistenpy.service' to '~/.config/systemd/user/mpdlistenpy.service'.  
 * Update, enable and start the service as a user :
 
```
 # If you need to edit the path to the script (should be in ~/mpdlisten by default)
 # systemctl --user --full edit mpdlistenpy.service
 systemctl --user daemon-reload
 systemctl --user enable mpdlistenpy.service
 systemctl --user start mpdlistenpy.service
```

### Automounting Samba shares on startup

If you want to setup a systemd service that mounts smb shares on startup, follow these instructions :

[Automount SMB shares on startup](https://forge.chapril.org/ABelliqueux/smbautomount)

*source :* [https://root.nix.dk/en/utility-scripts/mount-samba-share-as-user](https://root.nix.dk/en/utility-scripts/mount-samba-share-as-user)

### Automounting USB

[https://gist.github.com/zebrajaeger/168341df88abb6caaea5a029a2117925](https://gist.github.com/zebrajaeger/168341df88abb6caaea5a029a2117925)