docs/porting.md

   1 Porting a module from Arduino                         {#porting}
   2 =============================
   3
   4 Porting arduino libraries to libmraa as UPM libraries is usually fairly easy.
   5 The issues typically come from misunderstanding of how a non real time OS deals
   6 with interupts and timers. It also highly depends on the sensor. A concrete
   7 example is explained in detail on @ref max31855
   8
   9 ### Adding a new module to UPM
  10
  11 1. Choose a name for your module (see @ref naming)
  12 2. Make a new folder in src/<modulename>
  13 3. Create a CMakeLists.txt file inside src/<modulename>
  14
  15 ### CmakeLists.txt
  16
  17 By default you need a header called <modulename>.h and a C++ file called
  18 <modulename>.cxx. You can have multiple headers and source files. Only public
  19 headers need to be added to module_h and all source files need to be in
  20 module_src.
  21
  22 ~~~~~~~~~~~
  23 set (libname "modulename")
  24 set (libdescription "Module Description")
  25 set (module_src ${libname}.cxx)
  26 set (module_h ${libname}.h)
  27 upm_module_init()
  28 ~~~~~~~~~~~
  29
  30 ### Making your API
  31
  32 The easiest way to do this is to have a look at a similar sensor to yours.
  33 Typically create a class for your sensor with a constructor that defines the
  34 pins it is on. This constructor will create the mraa_*_context structs that are
  35 required to talk to the board's IO. An I2c sensor will create a
  36 mraa_i2c_context, keep it as a private member and require a bus number and slave
  37 address in it's constructor.
  38
  39 Typically in sensors a simple object->read() function is prefered, depending on
  40 your sensor/actuaotr this may or may not be easy or not even make sense. Most
  41 UPM apis have a simple set of functions.
  42
  43 ### Mapping arduino API to libmraa
  44
  45 Your constructor is similar to the setup() function in arduino, you should
  46 initialise your IO the way you want it. This means initialising contexts
  47 (private members) and setting the correct modes for them.
  48
  49 See the mraa API documentation for exact API.
  50
  51 ### Building
  52
  53 To build your module just follow @ref building. By creating a folder and the
  54 CMakelists.txt file you have done all that is required to add your sensor to
  55 the UPM build system.
  56
  57 ### Sending your module to us for inclusion in UPM
  58
  59 The last step is when you're happy with your module and it works send us a pull
  60 request! We'd love to include your sensor in our repository.
  61
  62 If you don't like github you can also send brendan.le.foll@intel.com a git
  63 formatted patch if your sensor. More details are on @ref contributing and on
  64 https://help.github.com/articles/creating-a-pull-request
  65