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