Rpi-jukebox-rfid: Add Architecture description

[joshwapohlmann]

Very often I find myself in the position, that I'd like to contribute, but have to spend hours to just understand what part of the project/code does what.
In many cases this is not necessary for most small features and I feel this would lower the barrier for people to actually contribute small changes if they don't have to dig through all the code.

[MiczFlor]

Hi @joshwapohlmann
good point. And needs to be done the sooner the better - so that more people can contribute. Can you point me to an example file that you think would help?
Digging through Phoniebox code is also digging through many different styles of coding :) being open source and benefiting from people like yourself commiting their code, makes it a very colourful code base.

[joshwapohlmann]

@MiczFlor Maybe add a coding style section in the CONTRIBUTION.md, e.g. python pep8.
Also point to the architecture document (maybe a structure.md in /doc ?).
I have no example file at hand, sorry :(. A general overview about the components would help:
So far I see 4 "components":

1. python for reading the RFID cards.
2. python for controling mpd depending on RFID value read.
3. PHP website for interfacing with MPD and other controls. (or does it interface with the python script?)
4. a ton of shellscripts for installation and configuration.

If you could clarify this, add a few more details who is talking to who, doing what ..... this would be great. Bonus points for pointing roughly at the code in the repository :)

[Squelsh]

3. PHP website for interfacing with MPD and other controls. (or does it interface with the python script?)

==> PHP also generates the playlists for MPD which are saved in the playlists folder.

And please can someone clarify if mopidy requires mpd or if it is a replacement. I still can't tell.

[Squelsh]

Found it in the installer script: Mopidy replaces mpd in the Spotify version...

# Spotify config
if [ $SPOTinstall == "YES" ]
then
        sudo systemctl disable mpd
        sudo systemctl enable mopidy

I think, this would be really helpful in the description.

[s-martin]

I agree this would be very helpful.

In addition some roadmap what’s planned to do or could be picked up by contributors could help. E.g. is it planned to migrate the bash scripts to python or should it stay this way?

[MiczFlor]

Hi @s-martin
Phoniebox has come a long way and still carries a lot of infant code with it. The "never change a running system" policy has made it accessible and stable enough for many. I remember a few points in the history (e.g. replacing cvlc with mpd) which created many sleepless nights :)
If there was a number of committed developers, who spend some of their downtime, I would be happy to be in a more managerial role and community contact. Then a roadmap would be good.
I still would like to keep this as simple as possible: so that many, many people can contribute. I often get messages that this is somebody's first Pi / Linux / coding project and that makes me very happy. If Phoniebox were to become a superslick install but difficult to contribute code base, it would lose some of its strength.

[joshwapohlmann]

@MiczFlor Thanks for the statement. I understand the priorities you make in terms of the design.
Before discussing the future course of this project I'd (still) like to stress the importance of documenting the current design and structure so that everybody is on the same page.

I will provide a first graphical representation of the project as I understand it (without digging too much into the code) and you could help me correct and clarify bits and parts of it.
When finished we can drop it into the docs/ folder along with the contribution guide to get contributors started.

What do you think?

[MiczFlor]

Hi @joshwapohlmann
Yes, please! And thanks for the effort. What tool will you use for the graph(s)?

[joshwapohlmann]

@MiczFlor I will use inkscape to create a SVG image.

[joshwapohlmann]

Okay,
First let's explain the code structure.
/ - root directory, here is everything to get started and install the project.
/display - code for connecting and controlling a display attached to the respberry pi. See directorie's README for details
/docs - documentation and howtos for the project besides the README
/htdocs - PHP web interface
/logs - not holding any source files
/misc - sample configuration files, mp3 testfiles
/scripts - ???
/scripts/helperscripts - help to configure and manage your phoniebox
/scripts/installscripts - installation scripts which modify the system to work with/as a phoniebox
/scripts/pirc522 - python driver for the RFID module
/scripts/python-phoniebox - ???
/scripts/userscripts - ???
/settings - settings how the phoniebox should behave (other locations/files as well ???)
/shared/audiofolders - files available to be played
/shared/shortcuts - ???
/tests - ???

Is this listing correct @MiczFlor? Could you please fill in the gaps marked with "???"
After this I continue to draw the diagram.

[MiczFlor]

Hi @joshwapohlmann
to make the process a bit transparent, I started to add a wiki page
https://github.com/MiczFlor/RPi-Jukebox-RFID/wiki/Architecture_FoldersFiles
possibly that could be a space where we can finalize the content and then you take it to inkscape

[Squelsh]

Hi Micz,

the folder structure is already a nice starting point. Could you please clarify in 3 sentences, which backend is responsible for which music? As I still don't understand if local music / playlists in the Spotify Edition are handled by mopidy or its mpd server part or completely different.

I only noticed that the playlist filestructure differs between Sotify and classic edition.
From what I see in the playout_controls.sh mpc load is used and the mpc play.
But on my setup mpc is not able to handle the playlist file format as the lines start with "local::track".

So mpc fails in loading the playlists. What is wrong? Am I missing a parsing plugin or did something go wrong during installation and the classic and spotify version are mixed up?

Thanks in advance!

[Squelsh]

Sorry, just found this one: https://github.com/MiczFlor/RPi-Jukebox-RFID/issues/745#issuecomment-577190340
But I still don't understand why my mopidy installation can't handle the .m3u files