diff --git a/doc/API.rst b/doc/API.rst deleted file mode 100644 index 51f1f14..0000000 --- a/doc/API.rst +++ /dev/null @@ -1,101 +0,0 @@ -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 ``|``. diff --git a/doc/COMPILING.rst b/doc/COMPILING.rst deleted file mode 100644 index d0a44d8..0000000 --- a/doc/COMPILING.rst +++ /dev/null @@ -1,63 +0,0 @@ -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/HOME.rst b/doc/HOME.rst deleted file mode 100644 index 7f1531f..0000000 --- a/doc/HOME.rst +++ /dev/null @@ -1,47 +0,0 @@ -=========================== -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/PI.rst b/doc/PI.rst deleted file mode 100644 index fd0eba8..0000000 --- a/doc/PI.rst +++ /dev/null @@ -1,142 +0,0 @@ -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/SETUP.rst b/doc/SETUP.rst deleted file mode 100644 index fca1a75..0000000 --- a/doc/SETUP.rst +++ /dev/null @@ -1,149 +0,0 @@ -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.