Merge branch 'maint-demo'

[eurobot/public.git] / src / doxygen-mainpage.h

diff --git a/src/doxygen-mainpage.h b/src/doxygen-mainpage.h
index 248d889e65662943b768b7f154de457002b5eb15..43519e4d6957ddae10a8e2f3b6a55db1e42da811 100644 (file)
--- a/src/doxygen-mainpage.h
+++ b/src/doxygen-mainpage.h
@@ -5,20 +5,25 @@ This document contains programmer documentation of some parts of
 software developed by Eurobot team at Department of Control
 Engineering, FEE, Czech Technical University. .
 
-Currently, there is documentation to these parts:
+Currently, these modules are documented:
 - \subpage compilation
+- \subpage logging
 - \ref fsm
 - \ref trgen
 - \ref maplib
 - \ref pp
 - \ref uoled
 - \ref leds
-- carousel.c TODO - convert to module
+- \ref canmsg
+- \ref carousel
+- \ref shapedet
 
 To regenerate this documentation, run @c doxygen in @c src
 directory. The result can be found in @c src/doc/html/index.html.
 
-\defgroup leds Meanings of LED diods on various boards
+\defgroup leds Meanings of LEDs on various boards
+
+\defgroup canmsg CAN bus messages
 
 \dir common
 Common files for all supported targets (CAN message IDs etc.).
@@ -34,6 +39,25 @@ Main robot-control application(s) and support files.
 
 \page compilation How to compile it
 
+\section Prerequisites
+
+To compile the software, you need the following programs and libraries.
+- python
+- pkg-config
+- libidl
+- libpopt
+- OpenCV
+- libfft
+- Qt version 4.x
+- libusb
+
+On a Debian-based system, it is sufficient to run
+\verbatim
+apt-get install build-essential python pkg-config libidl-dev libpopt-dev libcv-dev libhighgui-dev libfftw3-dev qt4-dev-tools libusb-dev
+\endverbatim
+
+\section Preparation
+
 Before first compilation, you should execute
 <tt>build/prepare_infrastructure script</tt>. 
 \verbatim
@@ -45,7 +69,7 @@ for @c h8s processors and configures sources. Then, it should be
 sufficient to go to the <tt>build/<em><target></em></tt> directory and
 call 
 \verbatim
-cd linux
+cd host
 make
 \endverbatim
 
@@ -108,4 +132,43 @@ export CONFIG_OPEN_LOOP=y
 make -e  # the -e option is important!
 \endverbatim
 
+\page logging Logging
+
+We use uLUt library for logging. printf() should never be used for
+printing some information - error message, debug data etc. Instead
+ul_logXXX(), which is declared in ul_log.h, should be used.
+
+\section loghowto Howto
+
+In every file, where you want to log something you must initialize
+ul_log.h library by using UL_LOG_CUST macro and defining the name of
+the log domain:
+\code
+UL_LOG_CUST(ulogd_robot); // Log domain name = "ulogd_" + the name of the source file
+\endcode
+
+Then, you can use one of the functions (macros) bellow. Each macro
+logs a message with different severity. The severity should be chosen
+according to the following rules:
+
+- ul_logfatal() - fatal error which causes the program to terminate.
+  These error should only be reported at program startup, not while
+  the program is running for a while.
+
+- ul_logerr() - error i.e. something that should not happen during
+  normal operation. The application should be able to continue,
+  possibly with its functionality limited.
+
+- ul_logmsg() - important information that should always be seen by
+  the operator. These messages with this log level are printed by
+  default.
+
+- ul_loginf() - not so important information, which is normally
+  suppressed and is displayed only on request.
+
+- ul_logdeb() - debuging information. This information is only useful
+  to someone who knows the details of the source code.
+
+- ul_logtrash() - lowlevel debugging information.
+
 */