docs: Added intial documentation for UPM and start of a porting walkthrough

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

docs/building.md

@@ -0,0 +1,31 @@
+Building UPM                         {#building}
+============
+
+UPM uses cmake in order to make compilation relatively painless. Cmake runs
+build out of tree so the recommended way is to clone from git and make a build/
+directory.
+
+UPM will attempt to build all directories inside src/ and they must contain
+individual CMakeLists.txt files.
+
+~~~~~~~~~~~~~{.sh}
+mkdir build
+cd build
+cmake ..
+make
+~~~~~~~~~~~~~
+
+Our cmake configure has a number of options, `cmake -i` will ask you all sorts
+of interesting questions, you can disable swig modules, build documentation
+etc...
+
+Few recommended options:
+Changing install path from /usr/local to /usr
+-DCMAKE_INSTALL_PREFIX:PATH=/usr
+
+Building debug build:
+-DCMAKE_BUILD_TYPE=DEBUG
+
+Using clang instead of gcc:
+ -DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang
+

docs/contributions.md

@@ -0,0 +1,16 @@
+Contributing a module                         {#contributions}
+=====================
+
+Here are the rules of contribution:
+- Try not to break master. In any commit.
+- Commits must have a sign-off line by everyone who reviewed them
+- Commits must be named <file/module>: Some decent description
+- You must license your module under an FOSS license. The recommended license
+  is MIT but any permissive license is fine. Please consider that people using
+  UPM may want to write proprietary programs with your sensors so we like to
+  avoid GPL. (LGPL is fine). If your license is not MIT please include a
+  LICENSE file in src/<mymodule>/
+- Please test your module builds before contributing and make sure it works on
+  the latest version of maa. If you tested on a specific board/platform please
+  tell us what this was in your PR.
+

docs/naming.md

@@ -0,0 +1,24 @@
+Naming a module                         {#naming}
+===============
+
+UPM attemps to follow a clear naming pattern. Modules should be sensibly named
+and then placed in /usr/lib/upm and headers in /usr/include/upm.
+
+### Choosing a name
+
+1. Pick a name
+2. Use it
+
+### Rules for name picking
+
+1. Your lib must belong to namespace UPM
+2. Usually picking the name of the chip of your sensor/actuator might make
+sense. Other times this does not. Try to pick a generic name so people with a
+similar sensor can inherit your class if they only have minor changes.
+3. Avoid brand names
+
+### Doubt
+
+If ever, give me a ping via email: brendan.le.foll@intel.com and I'll try
+suggest decent names for your module.
+

docs/porting.md

@@ -0,0 +1,64 @@
+Porting a module from Arduino                         {#porting}
+=============================
+
+Porting arduino libraries to libmaa as UPM libraries is usually fairly easy.
+The issues typically come from misunderstanding of how a non real time OS deals
+with interupts and timers. It also highly depends on the sensor.
+
+### Adding a new module to UPM
+
+1. Choose a name for your module (see @ref naming)
+2. Make a new folder in src/<modulename>
+3. Create a CMakeLists.txt file inside src/<modulename>
+
+### CmakeLists.txt
+
+By default you need a header called <modulename>.h and a C++ file called
+<modulename>.cxx. You can have multiple headers and source files. Only public
+headers need to be added to module_h and all source files need to be in
+module_src.
+
+~~~~~~~~~~~
+set (libname "modulename")
+set (libdescription "Module Description")
+set (module_src ${libname}.cxx)
+set (module_h ${libname}.h)
+upm_module_init()
+~~~~~~~~~~~
+
+### Making your API
+
+The easiest way to do this is to have a look at a similar sensor to yours.
+Typically create a class for your sensor with a constructor that defines the
+pins it is on. This constructor will create the maa_*_context structs that are
+required to talk to the board's IO. An I2c sensor will create a
+maa_i2c_context, keep it as a private member and require a bus number and slave
+address in it's constructor.
+
+Typically in sensors a simple object->read() function is prefered, depending on
+your sensor/actuaotr this may or may not be easy or not even make sense. Most
+UPM apis have a simple set of functions.
+
+### Mapping arduino API to libmaa
+
+Your constructor is similar to the setup() function in arduino, you should
+initialise your IO the way you want it. This means initialising contexts
+(private members) and setting the correct modes for them.
+
+See the maa API documentation for exact API.
+
+### Building
+
+To build your module just follow @ref building. By creating a folder and the
+CMakelists.txt file you have done all that is required to add your sensor to
+the UPM build system.
+
+### Sending your module to us for inclusion in UPM
+
+The last step is when you're happy with your module and it works send us a pull
+request! We'd love to include your sensor in our repository.
+
+If you don't like github you can also send brendan.le.foll@intel.com a git
+formatted patch if your sensor. More details are on @ref contributing and on
+https://help.github.com/articles/creating-a-pull-request
+