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

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

Doxyfile.in

@@ -754,6 +754,7 @@ WARN_LOGFILE           =
 # Note: If this tag is empty the current directory is searched.
 
 INPUT                  = @CMAKE_CURRENT_SOURCE_DIR@/src \
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs \
                          @CMAKE_CURRENT_SOURCE_DIR@/README.md
 
 # This tag can be used to specify the character encoding of the source files
@@ -863,7 +864,8 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/examples/
+EXAMPLE_PATH           = @CMAKE_CURRENT_SOURCE_DIR@/examples/ \
+                         @CMAKE_CURRENT_SOURCE_DIR@/docs/
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

README.md

@@ -12,15 +12,20 @@ to provide identification/pin location on the board.
 Typically an update() function will be called in order to get new data from the
 sensor in order to reduce load when doing multiple reads to sensor data.
 
-A basic sensor is expected to work as such:
+### Example
-s = new sensor();
+
-print(sensor->read());
+A sensor/acturo is expected to work as such (here is the servo ES08A api):
-sleep(1);
+@snippet es08a.cxx Interesting
-s->update();
-print(sensor->read();
 
 However implementation and API design is compeltely up to the developer, some
 enumerable sensors for example may provide much clever instanciation. Displays
 may also create more complex structures in order to interface with them.
 
-For more information on maa, see the maa documentation
+### Building UPM
+
+See @ref building
+
+### Making your own UPM module
+
+@ref porting has more information on making new UPM modules
+

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
+

examples/es08a.cxx

@@ -34,11 +34,12 @@ main(int argc, char **argv)
     //! [Interesting]
     upm::ES08A *servo = new upm::ES08A(5);    
     servo->setAngle (180);
+    //! [Interesting]
+
     servo->setAngle (90);
     servo->setAngle (0);
     servo->setAngle (90);
     servo->setAngle (180);
-    //! [Interesting]
 
     std::cout << "exiting application" << std::endl;