DOCS: Create proper README for new pypi module
This commit is contained in:
Dominique Barton
parent
30bc55c146
commit
9efcf167e8
|
|
@ -1,16 +0,0 @@
|
|||
Configuration
|
||||
=============
|
||||
|
||||
The configuration of Mopidy can be stored wherever you want. However, I'd recommend to store it in `/etc/mopidy/mopidy.conf`. If you want to use that, create the directory with the correct permissions:
|
||||
|
||||
```
|
||||
mkdir /etc/mopidy
|
||||
chown mopidy: /etc/mopidy
|
||||
```
|
||||
|
||||
When you run Mopidy the first time, an initial configuration will be created.
|
||||
|
||||
You might want to set the following configuration parameters:
|
||||
|
||||
- `http.hostname = 0.0.0.0` to bind HTTP listener to all interfaces
|
||||
- `mpd.hostname = 0.0.0.0` to bind MPD listener to all interfaces
|
||||
24
HARDWARE.md
24
HARDWARE.md
|
|
@ -1,24 +0,0 @@
|
|||
Hardware
|
||||
========
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
To setup Pummeluff, you need to following hardware:
|
||||
|
||||
- [Raspberry Pi 3](https://www.raspberrypi.org/)
|
||||
- [RC522 RFID reader](https://www.aliexpress.com/wholesale?SearchText=rc522)
|
||||
|
||||
Connect RFID reader
|
||||
-------------------
|
||||
|
||||
Connect the RC522 RFID reader on the following ports:
|
||||
|
||||
- RC522 PIN `1` / `SDA` ––– RPi PIN `24` / `SPI0 CS0`
|
||||
- RC522 PIN `2` / `SCK` ––– RPi PIN `23` / `SPI0 SCLK`
|
||||
- RC522 PIN `3` / `MOSI` ––– RPi PIN `19` / `SPI0 MOSI`
|
||||
- RC522 PIN `4` / `MISO` ––– RPi PIN `21` / `SPI0 MISO`
|
||||
- RC522 PIN `5` / `IRQ` ––– RPi PIN `18` / `GPIO 24`
|
||||
- RC522 PIN `6` / `GND` ––– RPi PIN `20` / `GND`
|
||||
- RC522 PIN `7` / `RST` ––– RPi PIN `22` / `GPIO 25`
|
||||
- RC522 PIN `8` / `3.3V` ––– RPi PIN `17` / `3.3V PWR`
|
||||
13
README.md
13
README.md
|
|
@ -1,13 +0,0 @@
|
|||
Purpose
|
||||
=======
|
||||
|
||||
Pummeluff is an audio music box for kids.
|
||||
|
||||
It is based on [Mopidy](https://www.mopidy.com/) and additional self-written extensions, which enable the support of the RFID card reader and its management.
|
||||
|
||||
Please have a look at the following documents for more informations:
|
||||
|
||||
- [Hardware](HARDWARE.md)
|
||||
- [Setup](SETUP.md)
|
||||
- [Configuration](CONFIGURATION.md)
|
||||
- [Run](RUN.md)
|
||||
122
README.rst
Normal file
122
README.rst
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
Mopidy Pummeluff
|
||||
================
|
||||
|
||||
Pummeluff is a `Mopidy <http://www.mopidy.com/>`_ extension which allows you to control Mopidy via RFID cards. It is as simple as that:
|
||||
|
||||
- Register an action to an RFID card
|
||||
- Touch that card on the RFID reader and the action will be executed
|
||||
|
||||
Thus, the Mopidy Pummeluff extension adds the following features to Mopidy:
|
||||
|
||||
- A radically simple web UI which can be used to manage the RFID cards
|
||||
- A daemon which continuously reads RFID cards in the background and executes the assigned actions
|
||||
|
||||
There are several actions included, such as replacing the tracklist with a desired URI, setting the volume to a specific level or controlling the playback state.
|
||||
|
||||
Hardware
|
||||
========
|
||||
|
||||
Requirements
|
||||
------------
|
||||
|
||||
To get the whole thing working, you need the following hardware:
|
||||
|
||||
- A Raspberry Pi 3 Model B
|
||||
- An ``RC522`` RFID module (available on `AliExpress <https://www.aliexpress.com/wholesale?SearchText=rc522>`_ for approx. *USD 1*)
|
||||
- RFID cards, keyfobs or stickers (``ISO 14443A`` and ``Mifare`` should work)
|
||||
|
||||
.. note::
|
||||
|
||||
The project will probably run on other RPi models, but I've only tested it on the ``3B``. The RPi ``3B+`` should also work fine, as the GPIO pins are identical. I don't know about RPi ``1`` or ``2``, but you can give it a shot.
|
||||
|
||||
Connecting the RC522 module
|
||||
---------------------------
|
||||
|
||||
Please connect the ``RC522`` RFID module to the RPi as follows:
|
||||
|
||||
- ``RC522 pin 1 [SDA ]`` ––– ``RPi pin 24 [SPI0 CE0 ]``
|
||||
- ``RC522 pin 2 [SCK ]`` ––– ``RPi pin 23 [SPI0 SCLK]``
|
||||
- ``RC522 pin 3 [MOSI]`` ––– ``RPi pin 19 [SPI0 MOSI]``
|
||||
- ``RC522 pin 4 [MISO]`` ––– ``RPi pin 21 [SPI0 MISO]``
|
||||
- ``RC522 pin 5 [IRQ ]`` ––– ``RPi pin 18 [ GPIO 24 ]``
|
||||
- ``RC522 pin 6 [GND ]`` ––– ``RPi pin 20 [ GND ]``
|
||||
- ``RC522 pin 7 [RST ]`` ––– ``RPi pin 22 [ GPIO 25 ]``
|
||||
- ``RC522 pin 8 [3.3V]`` ––– ``RPi pin 17 [3.3V PWR ]``
|
||||
|
||||
Please have a look at the `Raspberry Pi SPI Pinout <https://pinout.xyz/pinout/spi>`_ if you want to have a graphical view of the RPi GPIO pins.
|
||||
|
||||
.. note::
|
||||
|
||||
This connections are only valid for the RPi model ``3B`` and ``3B+``. If you want to use another RPI model, make sure you're using the correct pins.
|
||||
|
||||
.. important::
|
||||
|
||||
Some manuals in the internet mention that the ``IRQ`` pin shouldn't be connected.
|
||||
However, Mopidy Pummeluff really uses the ``IRQ`` pin for the interrupt, so that less CPU cycles are used for the card reading daemon. If you don't connect the ``IRQ`` pin, Mopidy Pummeluff won't work!
|
||||
|
||||
Installation
|
||||
============
|
||||
|
||||
Prepare Raspberry Pi
|
||||
--------------------
|
||||
|
||||
Before you can install and use Mopidy Pummeluff, you need to configure your Raspberry Pi.
|
||||
Just follow these steps:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo raspi-config
|
||||
|
||||
In the configuraton utility, **Enable the SPI** under ``5 Interfacing Options – P4 SPI``.
|
||||
|
||||
After that, add your ``mopidy`` user to the ``spi`` group and reboot the RPi:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo usermod -a -G spi,gpio mopidy
|
||||
sudo reboot
|
||||
|
||||
Install via pip
|
||||
---------------
|
||||
|
||||
To install Mopidy Pummeluff via ``pip``, run this command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo pip install mopidy-pummeluff
|
||||
|
||||
Install from source
|
||||
-------------------
|
||||
|
||||
To install Mopidy Pummeluff from source, run this command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo su -
|
||||
cd /usr/src
|
||||
git clone https://github.com/confirm/mopidy-pummeluff.git
|
||||
cd pummeluff
|
||||
python setup.py install
|
||||
|
||||
Finally restart ``mopidy``:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
systemctl restart mopidy
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Activate and configure the `Mopidy HTTP <https://docs.mopidy.com/en/latest/ext/http/>`_ extension and make sure you can connect to the Web UI. The minimal config looks like this:
|
||||
|
||||
.. code-block::
|
||||
|
||||
[http]
|
||||
enabled = true
|
||||
hostname = 0.0.0.0
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Open the Mopidy Web UI (i.e. ``http://{MOPIDY_IP}:6680/``).
|
||||
You should see a ``pummeluff`` web client which can be used to regsiter new RFID cards.
|
||||
31
RUN.md
31
RUN.md
|
|
@ -1,31 +0,0 @@
|
|||
Run Mopidy
|
||||
==========
|
||||
|
||||
Run Mopidy via CLI
|
||||
------------------
|
||||
|
||||
You can run Mopidy from the CLI by executing:
|
||||
|
||||
```
|
||||
su - mopidy
|
||||
source mopidy/bin/activate
|
||||
mopidy --config /etc/mopidy/mopidy.conf
|
||||
```
|
||||
|
||||
Run Mopidy as service
|
||||
---------------------
|
||||
|
||||
To run Mopidy as service, copy the [mopidy systemd service unit](systemd/mopidy.service) to `/etc/systemd/system/mopidy.service` and run the following commands:
|
||||
|
||||
```
|
||||
systemctl daemon-reload
|
||||
systemctl enable mopidy
|
||||
```
|
||||
|
||||
From now on you can easily `start`, `stop` or `restart` Mopidy:
|
||||
|
||||
```
|
||||
systemctl start mopidy
|
||||
systemctl stop mopidy
|
||||
systemctl restart mopidy
|
||||
```
|
||||
168
SETUP.md
168
SETUP.md
|
|
@ -1,168 +0,0 @@
|
|||
Setup
|
||||
=====
|
||||
|
||||
Rasbian
|
||||
-------
|
||||
|
||||
Download and install [Raspbian](https://raspbian.org/) on an SD card.
|
||||
Boot the RPi, login with the credentials (`pi`/`raspberry`) and run the following commands as `root` (run `sudo su -` to become `root`):
|
||||
|
||||
```
|
||||
raspi-config
|
||||
```
|
||||
|
||||
Change the following settings:
|
||||
|
||||
- `2 Network Options`
|
||||
- `N1 Hostname`: Enter the desired hostname
|
||||
- `N2 Wi-fi`: Enter the WLAN settings
|
||||
- `4 Localisation Options`
|
||||
- Change the desired settings
|
||||
- `5 Interfacing Options`
|
||||
- `P4 SPI`: Enable the SPI interface
|
||||
- `7 Advanced Options`
|
||||
- `A3 Memory Split`: Set GPU memory to `8` MB
|
||||
|
||||
Now enable SSH:
|
||||
|
||||
```
|
||||
systemctl enable ssh
|
||||
systemctl start ssh
|
||||
```
|
||||
|
||||
Also change the password of the `pi` user:
|
||||
|
||||
```
|
||||
passwd
|
||||
```
|
||||
|
||||
If you want to rename the `pi` user, execute the following commands (a bit hacky, but the most straight-forward way):
|
||||
|
||||
```
|
||||
export NEW_USER="dbarton"
|
||||
|
||||
sed -i "s/^pi:/${NEW_USER}/" /etc/passwd # Rename POSIX pi user
|
||||
sed -i "s/^pi:/${NEW_USER}/" /etc/group # Rename POSIX pi group
|
||||
sed -i "s/pi$/${NEW_USER}/" /etc/group # Rename pi membership of additional POSIX groups
|
||||
sed -i "s/^pi:/${NEW_USER}/" /etc/shadow # Rename shadow entry
|
||||
|
||||
mv /home/pi /home/${NEW_USER} # Move home directory
|
||||
|
||||
cd /etc/sudoers.d/ # Update sudoers nopasswd rule
|
||||
mv 010_pi-nopasswd ${NEW_USER}
|
||||
sed -i "s/^pi/${NEW_USER}/" ${NEW_USER}
|
||||
```
|
||||
|
||||
Now update the system:
|
||||
|
||||
```
|
||||
apt update
|
||||
apt dist-upgrade
|
||||
```
|
||||
|
||||
Finally, reboot the machine to check if everything is still working:
|
||||
|
||||
```
|
||||
reboot
|
||||
```
|
||||
|
||||
Mopidy
|
||||
------
|
||||
|
||||
To install [Mopidy](https://www.mopidy.com/), you can execute the following steps. Please note these steps are mainly based on the [official source installation docs](http://docs.mopidy.com/en/latest/installation/source/).
|
||||
|
||||
First of all, install all requirements for Mopidy:
|
||||
|
||||
```
|
||||
# Add GPG key and apt source for mopidy apt repo (required for some extensions).
|
||||
wget -q -O - https://apt.mopidy.com/mopidy.gpg | sudo apt-key add -
|
||||
wget -q -O /etc/apt/sources.list.d/mopidy.list https://apt.mopidy.com/stretch.list
|
||||
apt update
|
||||
|
||||
# Install python pip and development requirements, required by Mopidy and extensions.
|
||||
apt install build-essential python-dev python-pip
|
||||
|
||||
# Install GStreamer, required by Mopidy itself.
|
||||
apt install gstreamer1.0-alsa \
|
||||
python-gst-1.0 \
|
||||
gir1.2-gstreamer-1.0 \
|
||||
gir1.2-gst-plugins-base-1.0 \
|
||||
gstreamer1.0-plugins-good \
|
||||
gstreamer1.0-plugins-ugly \
|
||||
gstreamer1.0-tools
|
||||
|
||||
# Install Python virtualenv, required for our setup.
|
||||
pip install virtualenv
|
||||
```
|
||||
|
||||
Now prepare our Mopidy environment:
|
||||
|
||||
```
|
||||
groupadd -g 666 mopidy
|
||||
useradd -u 666 -g 666 -G audio,spi,gpio -c "Mopidy User" -d /opt/mopidy -m -s /bin/bash mopidy
|
||||
```
|
||||
|
||||
Let's create our python venv and install mopidy:
|
||||
|
||||
```
|
||||
su - mopidy
|
||||
|
||||
virtualenv --system-site-packages mopidy
|
||||
source mopidy/bin/activate
|
||||
|
||||
pip install mopidy
|
||||
```
|
||||
|
||||
Spotify Extension
|
||||
-----------------
|
||||
|
||||
If you want to use Spotify within Mopidy, install the [Mopidy Spotify Extension](https://github.com/mopidy/mopidy-spotify):
|
||||
|
||||
```
|
||||
# IMPORTANT: The following command requires the mopidy apt repo from above.
|
||||
apt install libffi-dev libspotify-dev libspotify12
|
||||
sudo -u mopidy /opt/mopidy/mopidy/bin/pip install pyspotify mopidy-spotify
|
||||
```
|
||||
|
||||
After installing spotify, you must authenticate it as described in the [official github repo](https://github.com/mopidy/mopidy-spotify#configuration) and/or on the [mopidy website](https://www.mopidy.com/authenticate/#spotify). The configuration looks like this:
|
||||
|
||||
```
|
||||
[spotify]
|
||||
username = … your username …
|
||||
password = … your secret …
|
||||
client_id = … client_id value you got from mopidy.com …
|
||||
client_secret = … client_secret value you got from mopidy.com …
|
||||
```
|
||||
|
||||
Iris Extension
|
||||
--------------
|
||||
|
||||
If you want a web interface to control Mopidy, I'd recommend [Iris](https://github.com/jaedb/Iris):
|
||||
|
||||
```
|
||||
sudo -u mopidy /opt/mopidy/mopidy/bin/pip install mopidy-iris
|
||||
```
|
||||
|
||||
After installing Iris, you might want to set the following settings:
|
||||
|
||||
```
|
||||
[iris]
|
||||
country = CH
|
||||
locale = de_CH
|
||||
```
|
||||
|
||||
Pummeluff Extension
|
||||
-------------------
|
||||
|
||||
The Pummeluff extension is in charge of the whole RFID handling. The sources for it reside in this repository, but we need to make sure we've all dependencies in place. Follow these steps to install it:
|
||||
|
||||
```
|
||||
su - mopidy
|
||||
|
||||
source mopidy/bin/activate
|
||||
|
||||
pip install spidev # Install this before pi-rc522
|
||||
pip install pi-rc522
|
||||
|
||||
|
||||
```
|
||||
Loading…
Reference in a new issue