Doc

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 <http://docutils.sourceforge.net/rst.html>`_ syntax, and is distributed under the Creative Commons BY-SA 4.0 license.
+
+The `Open Sound Control (OSC) packet manipulation library <http://www.rossbencina.com/code/oscpack>`_ is written and distributed under the `MIT license <https://opensource.org/licenses/mit-license.phpl>`_, with the following addition : 
+
+	"Any person wishing to distribute modifications to the Software is requested to send the modifications to `the original developer <mailto:[email protected]>`_ 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 <https://github.com/jcelerier/libaudiotool>`_ is distributed under the `GNU GPL v3 <https://www.gnu.org/licenses/gpl-3.0.html>`_.
+
+The application itself is distributed under the `Zlib License <https://opensource.org/licenses/Zlib>`_.
+
+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).

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* <https://www.raspberrypi.org/downloads/raspbian/>`_ image. 
+
+You can follow the installation instructions for more information about how to write the image on an `SD Card <https://www.raspberrypi.org/documentation/installation/installing-images/README.md>`_.
+
+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@<your pi's IP>
+
+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`` -> ``<Yes>`` -> ``<Ok>`` -> ``<Finish>``
+
+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 <https://www.thomas-krenn.com/en/wiki/Perl_warning_Setting_locale_failed_in_Debian>`_, and run::
+ 
+  # dpkg-reconfigure locales
+  
+Then select the correct locales.  

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 <https://github.com/hixe33/boiteselectriques-server-deps>`_
+
+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.