Welcome to mpd-box’s documentation!¶
MPD-Box start a song in Music Player Daemon by simply scanning a NFC.
It creates a new way to interact with your music. Once setup for the first time, just grab a tag and start listening to it without having to navigate a screen interface. Remove it, and it will stop.
Summary¶
This documentation cover all technical aspects on server side.
Installation¶
To actually run mpb-box, you need to install on local machine mpd and redis. Then follow one of the follow.
MPD¶
Follow instructions from Music Player Daemon official documentation.
Note
It is highly recommanded to install MPD using a local configuration (per user) to avoid forbidden access to music’s file. Instruction can be found on arch linux wiki (works great on every distribution).
You can use mpc to verify your installation
pi@raspberrypi ~ $ mpc status
volume: 90% repeat: off random: on single: off consume: off
MPD should automatically start on start. If you installed it using a local configuration, make sure you did configure your .profile to launch it on login.
MPD-Box does not manage your music yet. You need to configure a path in MPD and save some files in it. We recommand to create then a symbolic link to your medias and access a USB stick.
Redis¶
Follow instructions from Redis Quick Start documentation.
MPD-Box¶
setuptools¶
MPD-Box is available as a python module defined in setup.py on root folder.
Use git to clone code from github repository.
git clone https://github.com/mpd-box/mpd-box.git
Then install it in your python environment.
cd mpd-box
python setup.py install
Feel free to read Python documentation about Installing Python Modules to learn more about setup.py.
You should now be able to run mpd-box using command line.
mpd-box start
Warning
You system might require mpd-box to run as root to access hardware (like NFC reader). To do so, just run mpd-box using sudo.
Next section is about how to configure and run mpd-box.
Zeroconf (optional)¶
It might be usefull installing Ahari-daemon to activate zeroconf and have an easy access from other devices.
This will use local hostname as a domain name on your local network. If your device is named MPD-Box (recommanded)
then you will be able to access it using MPD-Box.local as a domain name.
Installation procedure depend on your operating system.
Configuration¶
MPD-Box use python ConfigParser module to store and read app config file.
Default configuration is saved in mpd_box/config.default.cfg but is override by ~/.mpd-box.cfg or /etc/mpd-box.cfg
You can read default config file to learn about MPD-Box, but main properties are the followong :
[mpd_box]
# List of readers to activate
mpd_box.readers =
mpd_box.readers.nfc.raspberry_explorer_board
# Port to access MPD-Box services
port = 6543
[mpd]
# Redefine port to access MPD
# default : 6600
port = 6600
[redis]
# Redefine port to access Redis
# default : 6379
port = 6379
Warning
If run as administrator, ~ is relative to root user, probably /root.
MPD-Box will first try to access local user config file and only if could not find it will try /etc/mpd-box.cfg
Run¶
As a service¶
You can run MPD-Box as a unix service.
Copy mpd-box-daemon script to /etc/init.d directory.
sudo cp <mpd_box_path>/scripts/mpd-box-daemon /etc/init.d/mpd-box
You can now use service command line to controle mpd-box.
sudo service mpd-box start
sudo service mpd-box status
sudo service mpd-box restart
sudo service mpd-box stop
It will automatically start on system launch. Logs can be consulted in /var/log/mpd-box.log.
Readers¶
Readers are independant modules of MPD-Box you can activate or deactivate to fit your needs.
To activate a reader, just put its name in your configuration file. (See configuration section)
List of readers¶
Raspberry Explorer Board¶
This reader has been design to work with the NF explorer Board.
Installation¶
This reader require you to install a python library to allow MPD-Box accessing the hardware : nxppy
pip install nxppy
This can take few minutes since your rapsberry needs to compile it.
Configuration¶
In your configuration file, add mpd_box.readers.nfc.raspberry_explorer_board:
[mpd_box]
# List of readers to activate
mpd_box.readers =
mpd_box.readers.nfc.raspberry_explorer_board
Behaviour¶
Put a tag, music start. Remove it, music stop.
API¶
MPD-Box has two distinct API to use. First one is from MPD, other one is running on Pyramid and designed to manage tags.
Cheatsheet¶
MPD¶
MPD provide an API to control most feature. You can find Client Libraries readdy to use and implement on your project.
MPD-Box use python-mpd2.
MPD-Box API¶
MPD-Box has a RESTFull API to control tags.
| Method | URI | Description |
|---|---|---|
| GET | /current-id | Return current tag-id read by mpd-box |
| Tags | ||
| POST | /tag/(tag_id) | Create a tag |
| GET | /tag/(tag_id) | Retrieve an existing tag |
Full reference¶
Hardware¶
Since day one, PD-Box has been design to run on a Raspberry Pi (Model B) using its dedicated NFC Explorer Board. However, there is no reason this project does not work on other configuration.
As a target platform, Raspberry Pi will be used as reference to define perfomance limitation.
Raspberry Pi¶
This page explain how to install MPD-Box on a Raspberry Pi.
Required hardware :
- Raspberry Pi
- SD Card (8go min)
- USB Adapter for power supply
- Ethernet cable (USB wifi card also works)
- NFC explorer board
- Some NFC chip (one included with NFC explorer, your credit card works too)
Operating System¶
Any linux distribution is good. We recommand to visit raspbian official website and download the latest version.
Copy it on your SD card, then plug it on your raspberry. Turn it on, and you should have a debian runnning :)
Activate NFC explorer board¶
To be able to use the NFC reader, you have to activate the SPI connector.
Open a terminal and write :
$> sudo raspi-config
The option to activate SPI can be found as follows: Advanced Options > SPI > <Yes>.
Now reboot your Raspberry Pi by typing the following command: sudo reboot
Install MPD-Box¶
Follow the instruction from the installation section. You should then be able to use it now.
Activate raspberry_explorer_board reader¶
Follow instruction from the Raspberry Explorer Board Reader.
Frequently asked questions¶
How can I get a MPD-Box ?¶
There is no commercial use of MPD-Box for now. It all started as a personnal side-project and will more than likely stay like one.
However, I would recommand you to try finding a Hackerspace or Fablab near your place. Maybe someone there will be interested to help and build one.
Also, feel free to send an email for more support at mpd-box@sebastienbarbier.com.
Thanking¶
Thanks to Jordi Parra for inspiring this project with his “Spotify box” project.