From ac04fa473325879ffd0d55b5a0060b54e9edff88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20CHASSAIGNE?= Date: Thu, 15 Sep 2016 18:42:47 +0200 Subject: [PATCH] Doc --- doc/1-HOME.rst | 47 ++++++++++++++ doc/2-PI.rst | 142 +++++++++++++++++++++++++++++++++++++++++ doc/3-COMPILING.rst | 63 +++++++++++++++++++ doc/4-SETUP.rst | 149 ++++++++++++++++++++++++++++++++++++++++++++ doc/5-API.rst | 101 ++++++++++++++++++++++++++++++ 5 files changed, 502 insertions(+) create mode 100644 doc/1-HOME.rst create mode 100644 doc/2-PI.rst create mode 100644 doc/3-COMPILING.rst create mode 100644 doc/4-SETUP.rst create mode 100644 doc/5-API.rst diff --git a/doc/1-HOME.rst b/doc/1-HOME.rst new file mode 100644 index 0000000..7f1531f --- /dev/null +++ b/doc/1-HOME.rst @@ -0,0 +1,47 @@ +=========================== +Boîtes électriques - Server +=========================== + +Table of content +================ + +*1 - HOME* + Presentation of the application. + +*2 - PI* + How to correctly set up the Raspberry Pi + +*3 - COMPILING* + How to build the program from the source. + +*4 - SETUP* + How to install and setup the server's program. + +*5 - API* + How client and server interact with each other. + (Description of the protocol) + +General informations +==================== + +Licenses +~~~~~~~~ + +This documentation is formatted using the `reStructuredText `_ syntax, and is distributed under the Creative Commons BY-SA 4.0 license. + +The `Open Sound Control (OSC) packet manipulation library `_ is written and distributed under the `MIT license `_, with the following addition : + + "Any person wishing to distribute modifications to the Software is requested to send the modifications to `the original developer `_ so that they can be incorporated into the canonical version. It is also requested that these non-binding requests be included whenever the above license is reproduced." + +The `libaudiotool audio framework `_ is distributed under the `GNU GPL v3 `_. + +The application itself is distributed under the `Zlib License `_. + +Notation +~~~~~~~~ + +In that document, you will often see commands that you can enter in an terminal, beginning either with a ``$`` or a ``#``, that you MUST NOT type. + +If the command starts with a ``$``, you just have to be a regular user to perform it (by default, ``pi``). + +If it's a ``#``, you NEED ``root`` privileges (sometimes, the ``sudo`` command is enough, but not always). \ No newline at end of file diff --git a/doc/2-PI.rst b/doc/2-PI.rst new file mode 100644 index 0000000..fd0eba8 --- /dev/null +++ b/doc/2-PI.rst @@ -0,0 +1,142 @@ +Configuration Pi +================ + +Raspbian installation +--------------------- + +The installation will be done on a Raspberry Pi, powered by the `*Raspbian Jessie Lite* `_ image. + +You can follow the installation instructions for more information about how to write the image on an `SD Card `_. + +The follow one of the two sections' instructions, depending on your equipment, and update your Raspberry Pi:: + + # apt-get update && apt-get upgrade + +If you have a screen and a USB keyboard +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have a screen with a HDMI port, connect it to your Raspberry Pi and do the same with a USB keyboard. Then power your Raspberry Pi on and follow the onscreen instructions to perform the installation. + +If you don't +~~~~~~~~~~~~ + +If you don't have both a screen and a keyboard, you can still access it through SSH. + +To do that, once the image has been written on the card, mount its ``boot`` partition, open the ``commandline.txt`` file and add ``silentinstall`` at the beginning of the first line. + +Then, connect the Pi to your network (or directly to your computer, creating a local network !) with an Ethernet cable and power it on. You can scan your network with the ``nmap`` command to find your Pi IP address and connect you to it through SSH (default password : ``raspberry``):: + + $ ssh pi@ + +Server's requirements +--------------------- + +SPI +~~~ + +For the Boîtes Électriques Server's executable to be able to run correctly, you need to activate the SPI interface on the Pi. To do that, just type:: + + # raspi-config + +Then go to: ``9 Advanced Options`` -> ``A5 SPI`` -> ```` -> ```` -> ```` + +Warning : this must be done before executing the server (``be-server``), else it won't run. + +Wifi bridge setup +----------------- + +Network and tools +~~~~~~~~~~~~~~~~~ + +First, edit the ``/etc/network/interfaces`` file, and replace it with this:: + + #config pont + iface eth0 inet dhcp + + allow-hotplug wlan0 + iface wlan0 inet static + address 192.170.0.1 + netmask 255.255.255.0 + network 192.170.0.0 + broadcast 192.170.0.255 + + iface default inet dhcp + +Then, we need Hostapd and DNSMasq to setup the bridge and attribute IPs automatically:: + + $ sudo apt-get install hostapd dnsmasq + +Hostapd configuration +~~~~~~~~~~~~~~~~~~~~~ + +Edit the ``/etc/hostapd/hostapd.conf`` file and replace it with this:: + + interface=wlan0 + driver=nl80211 + ssid=BoitesElectriquesPi + hw_mode=g + channel=6 + ieee80211n=1 + wmm_enabled=1 + ht_capab=[HT40][SHORT-GI-20][DSSS_CCK-40] + macaddr_acl=0 + auth_algs=1 + beacon_int=100 + dtim_period=2 + max_num_sta=255 + rts_threshold=2347 + fragm_threshold=2346 + +Then ``/etc/default/hostapd``to make it run on startup:: + + DAEMON_CONF="/etc/hostapd/hostapd.conf" + +Test it:: + + # systemctl start hostapd + +You can check the service status with the following command:: + + # systemctl status hostapd + +And enable it with ``systemctl``:: + + # systemctl enable hostapd + +DNSMasq +~~~~~~~ + +Edit the ``/etc/dnsmasq.conf`` file and replace it with this:: + + interface=wlan0 + listen-address=192.170.0.1 + bind-interfaces + server=8.8.8.8 + domain-needed + bogus-priv + dhcp-range=192.170.0.50,192.170.0.150,12h + +Test it:: + + # systemctl start dnsmasq + +You can check the service status with the following command:: + + # systemctl status dnsmasq + +And enable it with ``systemctl``:: + + # systemctl enable dnsmasq + +Bugs +---- + +If you have the following error:: + + Setting locale failed + +You can check the `following page `_, and run:: + + # dpkg-reconfigure locales + +Then select the correct locales. \ No newline at end of file diff --git a/doc/3-COMPILING.rst b/doc/3-COMPILING.rst new file mode 100644 index 0000000..d0a44d8 --- /dev/null +++ b/doc/3-COMPILING.rst @@ -0,0 +1,63 @@ +Compiling the project +===================== + +Dependencies +------------ + +Installation on a new Raspberry Pi image (Raspbian Jessie Lite) + +Divers +~~~~~~ + +First, let's download the basic tools for compilation, plus the server's dependencies, from the official repo:: + + $ sudo apt-get install build-essential git liboscpack-dev libqt5serialport5-dev librtaudio-dev libsndfile1-dev qt5-default qt5-qmake wiringpi + +Extra CMake Modules +~~~~~~~~~~~~~~~~~~~ + +Then, we need the Extra CMake Modules to compile KArchive. +The problem is that the version in the official repositories is not enough up-to-date, so we need to compile a more recent verion:: + + $ sudo apt-get install cmake + $ git clone git://anongit.kde.org/extra-cmake-modules + $ cd extra-cmake-modules + $ mkdir build && cd build && cmake .. && make && sudo make install + +KArchive +~~~~~~~~~~ + +Now, we can compile KArchive:: + + $ wget http://download.kde.org/stable/frameworks/5.17/karchive-5.17.0.tar.xz + $ tar -xf karchive-5.17.0.tar.xz + $ cd karchive-5.17.0 + $ mkdir build && cd build && cmake .. && make && sudo make install + +Additional notes +~~~~~~~~~~~~~~~~ + +If there is any problem with those dependencies, or if you can't download the ``liboscpack-dev`` from the official Raspbian repo, you can download the sources from `our git repo `_ + +Building the program +-------------------- + +Compilation +~~~~~~~~~~~ + +First, clone the repository on the Raspberry Pi, either directly from Github or using the Git CLI:: + + $ git clone https://github.com/hixe33/boiteselec-server + +Then, we need to generate the Makefile from the QMake file before finally compiling the sources:: + + $ mkdir boiteselec-server/build + $ qmake -config release -o boiteselec-server/build/Makefile boiteselec-server/src/be-server.pro + $ cd boiteselec-server/build && make + +Now you're all set to test the program ! + +Additional notes +~~~~~~~~~~~~~~~~ + +If there is any ``#include`` problem at compilation, don't forget to check where all the libraries are installed (``.h`` and ``.so`` files) and to update the QMake file (``src/be-server.pro``) according to their locations. diff --git a/doc/4-SETUP.rst b/doc/4-SETUP.rst new file mode 100644 index 0000000..fca1a75 --- /dev/null +++ b/doc/4-SETUP.rst @@ -0,0 +1,149 @@ +Setup +===== + +Installation +------------ + +Basic Installation +~~~~~~~~~~~~~~~~~~ + +Just clone the repository on the Raspberry Pi and follow the instructions of the ``COMPILING.rst`` page. + +To test the program, copy the ``share/run.sh`` script to the executable (``be-server``) directory, and run it (don't forget to ``chmod +x`` it if it doesn't want to be executed. + +WARNING : Be sure SPI has been activated, using the ``rapsi-config`` tool (cf ``PI.rst`` file for more details about how to set up the Raspberry Pi), or the server won't work. + +.. _daemonized: + +Daemonizing +~~~~~~~~~~~ + +WARNING : ``root`` access is required for the following section. + +To make the server running in the background automatically on the RasPi startup, it's possible to daemonize it with a few steps. + +First, copy the ``be-server`` executable file to ``/opt/boites-electriques/``, and the ``be-server.sh`` script (located in the repo's ``share/`` directory) to ``/etc/init.d/be-server``:: + + $ sudo mkdir /opt/boites-electriques + $ sudo cp build/be-server /opt/boites-electriques/be-server + $ sudo cp share/be-server.sh /etc/init.d/be-server + +You can then edit the ``/etc/init.d/be-server`` to change the following values: + +``DAEMON`` + The full command. + Default : ``"/opt/boites-electriques/be-server"`` + +``daemon_OPT`` + The program's arguments (here, the path to a specific configuration file). + Default : ``""`` (empty, to use the default config file) + +``DAEMONUSER`` + The user running the program. + Default : ``"pi"`` (default ``sudo`` user of Raspbian) + +``daemon_NAME`` + Name of the program. + Default : ``"be-server"`` + +Then, we give the right permissions to the daemonizing script and reload the system's daemons (as root or with ``sudo``):: + + # chmod 0755 /etc/init.d/be-server + # systemctl daemon-reload + +We can then test the script:: + + # systemctl start be-server + [ ok ] Starting be-server (via systemctl): be-server.service + + # systemctl stop be-server + [....] Stopping be-server (via systemctl): be-server.service + +And add it to the startup scripts:: + + # systemctl enable be-server + +To remove it:: + + # systemctl enable be-server + +Configuration +------------- + +General informations +~~~~~~~~~~~~~~~~~~~~ + +The server's configuration is saved in the ``config.txt`` file in the same folder as the executable. +This file is formatted with the (almost) standard `INI file format `_. + +By default (if the server is ran without the ``--config`` option), the configuration file is ``~/.config/Rock & Chanson/Boites Electriques.ini``. + +The missing fields in the file will automatically be filled at the execution. + +The following options are available : + +``[default]`` section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``threshold`` + Default threshold value (integer). + Default : ``200`` + +``master`` + Default master volume (integer). + Default : ``50`` + +``volume`` + Default track's volume (integer). + Default : ``50`` + +``pan`` + Default track's pan (integer). + Default : ``0`` + +``activation`` + Default track's activation status (boolean : ``true`` or ``false``). + Default : ``false`` + +``[files]`` section +~~~~~~~~~~~~~~~~~~~ + +``folder`` + Files save/load folder (string : path, ending with '``/``'). + Default : ``/home/pi/songs/`` + +``extension`` + Songs files' extension (string : ``*.``). + Default : ``*.song`` + +``[gpio]`` section +~~~~~~~~~~~~~~~~~~ + +``led`` + LED's WiringPi identifier (to use with the ``gpio`` command). + Default : ``6`` + +``[osc]`` section +~~~~~~~~~~~~~~~~~ + +``ip`` + Client's OSC IP address (integer). + Default : ``192.170.0.17`` + +``receiver`` + Server's OSC receiver port (integer). + Default : ``9988`` + +``sender`` + Server's OSC sender port (integer). + Default : ``9989`` + +Run +--- + +To start the server, just run ``./be-server``, or ``sudo systemctl start be-server.service`` if the server has been daemonized_. + +The following options are available : + +``-c``, ``--config `` + Define the ```` file as the configuration file. diff --git a/doc/5-API.rst b/doc/5-API.rst new file mode 100644 index 0000000..51f1f14 --- /dev/null +++ b/doc/5-API.rst @@ -0,0 +1,101 @@ +Interaction +=========== + +General informations +-------------------- + +To communicate, client and server use the OSC protocol. + +By default, the server uses the IP address ``192.170.0.1``, with the port ``9988`` to send messages and ``9989`` to receive them. +These values can be changed in the configuration file. + +Protocol +-------- + +**Note :** + ```` designate an integer value, ```` a string one, and ```` a boolean one. + +Server +~~~~~~ + +The server can receive the following messages from the client : + +``/box/update_threshold `` + Change the threshold value to ````. + +``/box/reset_threshold `` + Reset the threshold to its default value. + +``/box/enable `` + Switch the track number ````'s state (activate or deactivate it). + +``/box/volume `` + Change the track number ````'s volume value to ````. + +``/box/pan `` + Change the track number ````'s pan value to ````. + +``/box/mute `` + Mute (```` = ``true``) or unmute (``false``) the track number ````. + +``/box/solo `` + "Solo" (```` = ``true``) or "unsolo" (``false``) the track number ````. + +``/box/master `` + Change the master volume value to ````. + +``/box/play `` + Play the song + +``/box/stop `` + Stop the song + +``/box/reset `` + Stop the song and reset its options to their default values + +``/box/refresh_song `` + Refresh the song's informations + +``/box/select_song `` + Select another song + +``/box/sync `` + Send the informations of the actual song and the current state of the player to the client + +Client +~~~~~~ + +The client can receive the following messages from the server to access its informations : + +``/box/beat `` + The actual server's beat count value = ````. + +``/box/enable_out `` + The box number ```` has been activated. + +``/box/enable_sync `` + The numbers of the activated tracks, where ```` is a binary number indicating them. + For example, for an 8-tracks song with its 2nd, 4th, 5th and 8th tracks activated, ```` = 10011010. + +``/box/play `` + The selected song started playing (and that its tempo's value is ````). + +``/box/ready `` + The selected song is (```` = ``true``) or not (``false``) loaded and ready to be played. + +``/box/sensor `` + The actual server's threshold value = ````. + +``/box/songs_list `` + The available songs list = ````. + ```` is the concatenation of the songs' filenames, separated by the character ``|``. + +``/box/title `` + The actual server song's name is ````. + +``/box/tracks_count `` + The selected song's tracks count is ````. + +``/box/tracks_list `` + Send the informations of the selected song's tracks, as ````. + ```` is the concatenation of the songs' tracks' names, separated by the character ``|``.