docs/max31855.md

   1 Making a UPM module for MAX31855                         {#max31855}
   2 ================================
   3
   4 The Maxim Integrated MAX31855 is a thermocouple amplifier allowing you to read
   5 from a K type themocouple. My board comes from the Pmod kit form Maxim
   6 (MAX31855PMB1) but you can get this from many different sources. The adafruit
   7 people made arduino code already so we'll use that as a
   8 [reference](https://github.com/adafruit/Adafruit-MAX31855-library/blob/master/Adafruit_MAX31855.cpp).
   9
  10 ### Basics
  11
  12 This is a spi module so we will use the maa spi functions to build our module.
  13 First thing to do is to create a tree structure like this in upm/src/max31855:
  14
  15 * max31855.cxx
  16 * max31855.h
  17 * jsupm_max31855.i
  18 * pyupm_max31855.i
  19 * CMakeLists.txt
  20
  21 And then an example file to use & test our lib with in upm/examples/max31855.cxx.
  22
  23 ### Swig
  24
  25 The .i files are used by swig, there is one for each python & javascript. They
  26 contain essentially the same thing and are very simple. The only thing to
  27 change between the javascript & node.js one is the argument to %module.
  28
  29 @snippet jsupm_max31855.i Interesting
  30
  31 The %include parameter defines which functions will be available to the
  32 node/python module created, Whilst the headers inside %{} will be explicitly
  33 required during compilation. Typically only the top level header is required in
  34 either of those args.
  35
  36 ### API
  37
  38 Then we create the header (max31855.h) , a very simple header in our case we
  39 will have only a very basic api. We provide a getTemp() function which will
  40 return the same type as in the arduino library, a double.
  41
  42 @snippet max31855.h Interesting
  43
  44 Note that the header contains both the io that we will use, the gpio is in this
  45 case used as the chip select pin.
  46
  47 ### Implementing our API
  48
  49 In the adafruit library the read function (our chip is a 3pin SPI so only read
  50 is possible), the spiread32() does all the work. It starts by setting up the io
  51 so we will do the same in our constructor.
  52
  53 Note unlike on Arduino, we'll just set a 2Mhz clock and let the chip do the
  54 work.
  55
  56 @snippet src/max31855/max31855.cxx Constructor
  57
  58 Then we also need to implement a nice cleanup in our destructor.
  59
  60 @snippet src/max31855/max31855.cxx Destructor
  61
  62 Then to read data, we will use spi_write_buf which will allow us to write a
  63 whole uint32_t in order to get one back, which is what the arduino code does in
  64 spiread32. Obviously we set our chip select to low first. Here is the start of
  65 the implementation of MAX31855::getTemp()
  66
  67 @snippet src/max31855/max31855.cxx spi
  68
  69 Then using the arduino code as reference we simply reconstruct form the 4
  70 uint8_t values a 32bit int value and select only the valuable parts of
  71 information from that. The MAX31855 datahseet explains exactly which bits are
  72 useful, we will just do the same as the adafruit code, first checking the error
  73 bit and then scrapping everything but the 14bit of thermocouple data that are
  74 useful to us and converting it to a double.
  75
  76 @snippet src/max31855/max31855.cxx conversion
  77
  78 ### Finalizing
  79
  80 Our final example, very easy to use api!
  81
  82 @snippet examples/max31855.cxx Interesting
  83
  84 ### Building
  85
  86 The we need to add it to the examples/CMakeLists.txt. Only three lines are required
  87
  88 ~~~~~~~~~~~
  89 add_executable (max31855-example max31855.cxx)
  90 include_directories (${PROJECT_SOURCE_DIR}/src/max31855)
  91 target_link_libraries (max31855-example max31855 ${CMAKE_THREAD_LIBS_INIT})
  92 ~~~~~~~~~~~
  93
  94 Note you dont have to rebuild everything, cmake keeps target lists so if you
  95 named your example target <modulename>-example you can simply do make
  96 max31855-example and both the library & example will build.