src/doxygen-mainpage.h

   1 /**
   2 @mainpage Eurobot Software Documentation
   3
   4 This document contains programmer documentation of some parts of
   5 software developed by Eurobot team at Department of Control
   6 Engineering, FEE, Czech Technical University. .
   7
   8 Currently, these modules are documented:
   9 - \subpage compilation
  10 - \subpage logging
  11 - \ref fsm
  12 - \ref trgen
  13 - \ref maplib
  14 - \ref pp
  15 - \ref uoled
  16 - \ref leds
  17 - \ref canmsg
  18 - \ref carousel
  19 - \ref shapedet
  20
  21 To regenerate this documentation, run @c doxygen in @c src
  22 directory. The result can be found in @c src/doc/html/index.html.
  23
  24 \defgroup leds Meanings of LEDs on various boards
  25
  26 \defgroup canmsg CAN bus messages
  27
  28 \dir common
  29 Common files for all supported targets (CAN message IDs etc.).
  30
  31 \dir hello
  32 Demo application to test compilation and demonstrate OMK usage.
  33
  34 \dir laser-nav/matlab
  35 Matlab/Simulink tests for localization and trajectory generation.
  36
  37 \dir robofsm
  38 Main robot-control application(s) and support files.
  39
  40 \page compilation How to compile it
  41
  42 \section Prerequisites
  43
  44 To compile the software, you need the following programs and libraries.
  45 - python
  46 - pkg-config
  47 - libidl
  48 - libpopt
  49 - OpenCV
  50 - libfft
  51 - Qt version 4.x
  52 - libusb
  53
  54 On a Debian-based system, it is sufficient to run
  55 \verbatim
  56 apt-get install build-essential python pkg-config libidl-dev libpopt-dev libcv-dev libhighgui-dev libfftw3-dev qt4-dev-tools libusb-dev
  57 \endverbatim
  58
  59 \section Preparation
  60
  61 Before first compilation, you should execute
  62 <tt>build/prepare_infrastructure script</tt>.
  63 \verbatim
  64 cd build
  65 ./prepare_infrastructure
  66 \endverbatim
  67 It downloads repository
  68 for @c h8s processors and configures sources. Then, it should be
  69 sufficient to go to the <tt>build/<em><target></em></tt> directory and
  70 call
  71 \verbatim
  72 cd host
  73 make
  74 \endverbatim
  75
  76 \section cflags Custom compilation flags
  77
  78 To compile the project with debugging flags, put them to config.omk
  79 file in <tt>build/*</tt> directory. Don't modify config.target,
  80 because this will influence all other developers.
  81
  82 \verbatim
  83 cat <<EOF >> config.omk
  84 CFLAGS = -O0 -g -Wall -fno-strict-aliasing
  85 CXXFLAGS = -O0 -g -Wall -fno-strict-aliasing
  86 EOF
  87
  88 make clean
  89 make
  90 \endverbatim
  91
  92 \section config Using multiple software configurations
  93
  94 OMK build system allows to configure compilation process so that we
  95 can have multiple configurations of software (e.g.: with odometry
  96 feedback or without). On the OMK side, the configuration is done by
  97 setting make variables, from which headers files can be automatically
  98 generated. In sources <tt>##ifdef</tt> can be used to compile
  99 differently under different configuration.
 100
 101 Running
 102 \verbatim
 103 make default-config
 104 \endverbatim
 105
 106 produces list of all possible configuration variables in
 107 <tt>config.omk-default</tt> (note, that this is also run by
 108 <tt>prepare_infrastructure</tt>).
 109
 110 To use different value than the default one, put the variable
 111 assignment to <tt>config.omk</tt> or (preferably) to
 112 <tt>config.omk.local</tt>.
 113
 114 \verbatim
 115 echo CONFIG_OPEN_LOOP = y >> config.omk.local
 116 make
 117 \endverbatim
 118
 119 If you want to compile other configuration only temporarily you can
 120 you the following:
 121
 122 \verbatim
 123 touch config.omk  # make OMK notice a change
 124 make CONFIG_OPEN_LOOP=y
 125 \endverbatim
 126
 127 or a more permanent way:
 128
 129 \verbatim
 130 touch config.omk
 131 export CONFIG_OPEN_LOOP=y
 132 make -e  # the -e option is important!
 133 \endverbatim
 134
 135 \page logging Logging
 136
 137 We use uLUt library for logging. printf() should never be used for
 138 printing some information - error message, debug data etc. Instead
 139 ul_logXXX(), which is declared in ul_log.h, should be used.
 140
 141 \section loghowto Howto
 142
 143 In every file, where you want to log something you must initialize
 144 ul_log.h library by using UL_LOG_CUST macro and defining the name of
 145 the log domain:
 146 \code
 147 UL_LOG_CUST(ulogd_robot); // Log domain name = "ulogd_" + the name of the source file
 148 \endcode
 149
 150 Then, you can use one of the functions (macros) bellow. Each macro
 151 logs a message with different severity. The severity should be chosen
 152 according to the following rules:
 153
 154 - ul_logfatal() - fatal error which causes the program to terminate.
 155   These error should only be reported at program startup, not while
 156   the program is running for a while.
 157
 158 - ul_logerr() - error i.e. something that should not happen during
 159   normal operation. The application should be able to continue,
 160   possibly with its functionality limited.
 161
 162 - ul_logmsg() - important information that should always be seen by
 163   the operator. These messages with this log level are printed by
 164   default.
 165
 166 - ul_loginf() - not so important information, which is normally
 167   suppressed and is displayed only on request.
 168
 169 - ul_logdeb() - debuging information. This information is only useful
 170   to someone who knows the details of the source code.
 171
 172 - ul_logtrash() - lowlevel debugging information.
 173
 174 */