Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added and improved documentation

  • Loading branch information...
commit c836a611ffe891f75c5219af75360081cebfc2aa 1 parent d6136a4
fragraider authored
4 04_hardware_hard.dox
@@ -110,7 +110,7 @@
110 110 The schematic does not show the 26 pin connector for peripherals.
111 111 See @ref avr_conn
112 112
113   - @subsucsection avr_pic
  113 + @subsubsection avr_pic
114 114
115 115 @image html avr_developement_board_pic.png "Picture of the AVR decelopment board"
116 116 @image latex avr_developement_board_pic.eps "Picture of the AVR decelopment board" width=\textwidth
@@ -904,7 +904,7 @@
904 904 The data sheet for the RFID reader contains information about protocols and
905 905 setup. It can be found on campus net and is named:
906 906 "RFID-Reader_Datasheet_slave.pdf". In the data sheet, the chapter which
907   - probably is of most interest is: </b> 6. Documentation for the interface to
  907 + probably is of most interest is: <b> 6. Documentation for the interface to
908 908 the ATmega8 </b>.
909 909
910 910
354 05_hardware_soft.dox
@@ -2,6 +2,356 @@
2 2 @page hardware_soft AVR development board code overview
3 3
4 4 This part of the documentation gives a structural overview over the code
5   - writen for the AVR development board.
  5 + written for the AVR development board. For a complete description of all
  6 + files, macros and function, please refer to the file documentation later in
  7 + this document.
6 8
7   -*/
  9 +@section hardware_soft_timer Timer overview
  10 +
  11 + The macros and functions to handle some aspects of timer 0 and timer 1 in
  12 + timers.h are well documented. Usage of the macros should be easy by reading
  13 + the file documentation. There might though be two aspects which might need
  14 + some clarification:
  15 +
  16 + @subsection timers_top_extra TOP and COMP_EXTRA designation
  17 +
  18 + Like in the Atmega32 datasheet, the label TOP refers to the maximal value the
  19 + timer is actually counting to. This can be a different value from a timers
  20 + maximal value (MAX). In the Clear Timer on Compare mode (CTC mode), a timer
  21 + counts to the value in the primary timers compare register and will then be
  22 + cleared. This means the timer counted to a certain value in this compare
  23 + register. This value is not necessarily the maximum value the timer could
  24 + count to. This value is called TOP.
  25 +
  26 + For the timer 1 an additional compare register exists. To keep it simple, I
  27 + did not use the term used in the data sheet (Output Compare Register 1 B,
  28 + OCR1B) but called it COMP_EXTRA. COMP_EXTRA seemed to be suitable because it
  29 + is an additional possibility to compare the timer count with a number. This
  30 + register does not have influence on the count value in any mode.
  31 +
  32 + @subsection timers_extra_reachable COMP_EXTRA reachability
  33 +
  34 + Since the CTC mode is the only mode which is supported by timers.h , one very
  35 + important consequence arises: If the COMP_EXTRA value is bigger than the TOP
  36 + value, the flag corresponding to COMP_EXTRA will never be set. This should
  37 + not be a problem because the order in which the comparisons appears is not
  38 + relevant for a program flow, since the order of checking for the flags can be
  39 + changed.
  40 +
  41 +@section hardware_soft_disp Display overview (display.h and display_snippets.h)
  42 +
  43 + For a description of all macros and functions, please go to the display.h and
  44 + display_snippets.h file documentation.
  45 +
  46 + @subsection disp_relevant_info External sources
  47 +
  48 + There are two external documents which are useful when trying to follow this
  49 + description:
  50 +
  51 + <ul>
  52 + <li>
  53 + Display controller data sheet st7066.pdf:
  54 + http://www.lcd-module.de/fileadmin/eng/pdf/zubehoer/st7066.pdf
  55 + </li>
  56 + <li>
  57 + Display data sheet: http://www.display-elektronik.de/DEM20485SYH-LY.PDF
  58 + </li>
  59 + </ul>
  60 +
  61 + @subsection disp_design Design
  62 +
  63 + The macros and functions used to handle the display in a convenient way are
  64 + split up into two files: display.h and display_snippets.h .
  65 + display_snippets.h contains very basic macros which perform simple action
  66 + like setting up the needed ports, starting and stopping the wait timer,
  67 + reacting on timer events and so on. This basic components allow to compose
  68 + macros or functions that can solve certain tasks related to the display.
  69 + Such macros and functions can be found in the display.h header file.
  70 +
  71 + This design allows to reimplementation of similar functionality in different
  72 + macros or function, but in an adjusted and optimized way for the function.
  73 + Moreover, it significantly increased the readability and maintainability of
  74 + the code.
  75 +
  76 + The user might never have to take a look into the display_snippets.h header
  77 + file. Some user adjustable variables can be overridden in the user C file,
  78 + others must be changed in the header file.
  79 +
  80 + Definitions that can be overwritten in the user C file are:
  81 + <ul>
  82 + <li>LCD_CLOCKDIVISION</li>
  83 + <li>LCD_EXTRA_DIV</li>
  84 + <li>LCD_TOP_DIV</li>
  85 + </ul>
  86 + Those allow to somewhat tune the speed, at which data is send to the display.
  87 + The default settings should work safely for all displays. It is noteworthy
  88 + that LCD_EXTRA_DIV and LCD_TOP_DIV influence also the duty cyle of the
  89 + generated clock.
  90 +
  91 + Definitions that have to be changed in the display.h header file.
  92 + <ul>
  93 + <li>LCD_RS</li>
  94 + <li>LCD_EN</li>
  95 + <li>LCD_D4</li>
  96 + <li>LCD_D5</li>
  97 + <li>LCD_D6</li>
  98 + <li>LCD_D7</li>
  99 + <li>LCD_PORT</li>
  100 + <li>LCD_DDR</li>
  101 + <li>LCD_MAX_CHARS</li>
  102 + <li>LCD_MAX_CHARS_LINE</li>
  103 + </ul>
  104 +
  105 + In this project there is naturally no need to change any of those values,
  106 + but giving the possibility to do so will improve portability and re usability
  107 + of the code.
  108 +
  109 + @subsection disp_clocking Clocking
  110 +
  111 + To produce the clock signal on the E pin on the display, macros that start
  112 + with "LCD_WAIT" in display_snippets.h are used. Those commands "front end"
  113 + corresponding timer 1 macros and add functionality. The names for the macros
  114 + are not very friendly to new user and where chosen out of lack of creativity
  115 + and time pressure. The names are friendly for users which have knowledge
  116 + about timer 1 in timers.h . The file documentation should make a correct use
  117 + of those statements apparent, but here is the reference order for the commands
  118 + excluding data setup statements. Data set up statements should be used
  119 + according to timing considerations. For more information, please consult the
  120 + display data sheet mentioned at \ref disp_relevant_info.
  121 +
  122 + <table border="1">
  123 + <tr>
  124 + <th><b>Macro</b></th>
  125 + <th><b>Description</b></th>
  126 + </tr>
  127 + <tr>
  128 + <td>LCD_WAIT_SETUP</td>
  129 + <td>
  130 + Sets the timer used for timing the wait cycles up. This happens according
  131 + to the LCD_CLOCKDIVISION, LCD_EXTRA_DIV and LCD_TOP_DIV macros.
  132 + </td>
  133 + </tr>
  134 + <tr>
  135 + <td>LCD_WAIT_TIMER_START</td>
  136 + <td>Starts the timer used for timing the wait cycles.</td>
  137 + </tr>
  138 + <tr>
  139 + <td>LCD_WAIT_CLK_HIGH</td>
  140 + <td>
  141 + Sets LCD_EN high and waits for the EXTRA flag. The EXTRA flag is the
  142 + first flag which goes high after the timer starts. Its value is
  143 + defined in LCD_EXTRA_DIV.
  144 + </td>
  145 + </tr>
  146 + <tr>
  147 + <td>LCD_WAIT_CLK_LOW</td>
  148 + <td>
  149 + Sets LCD_EN low and waits for the TOP flag. The TOP flag is the second
  150 + flag that goes high after the timer starts. Its value is defined in
  151 + LCD_TOP_DIV. At this value, the timer will also be cleared.
  152 + </td>
  153 + </tr>
  154 + <tr>
  155 + <td>LCD_WAIT_TIMER_STOP</td>
  156 + <td>Stops the timer used for timing the wait cycles.</td>
  157 + </tr>
  158 + </table>
  159 +
  160 + To see practical examples, please refer to the source code for display.h,
  161 + which is found after the file documentation.
  162 +
  163 + @subsection disp_osci_pics Oscilloscope screen shots
  164 +
  165 + Here are some oscilloscope screen shots from the communication with the LCD
  166 + to allow the reader to gain a somewhat more physical grasp of the theory
  167 + above. Only a selection of the pins needed to communicate with the display is
  168 + shown. This is due to the limited channels the used oscilloscope has.
  169 +
  170 + This list relates the channel number of the oscilloscope to the measured
  171 + signal.
  172 +
  173 + <ol>
  174 + <li>E (Enable)</li>
  175 + <li>RS (Register Select)</li>
  176 + <li>D4 (Data 4)</li>
  177 + <li>D5 (Data 5)</li>
  178 + </ol>
  179 +
  180 + The following screen shot shows a writing operation for three characters and
  181 + one command. The character writing operation is distinguishable from the
  182 + command operation by taking a look at the second, green, signal. The high part
  183 + indicates the character writing operation, the low part the command operation.
  184 +
  185 + @image html disp_three_char_two_cmd.png "Character write and command operation"
  186 + @image latex disp_three_char_two_cmd.eps "Character write and command operation" width=\textwidth
  187 +
  188 + Here we can see a longer write action. The measurements are taken for the
  189 + first, the clock or E signal.
  190 +
  191 + @image html lcd_write_excerpt.png "Excerpt from the lcd_write funkiton"
  192 + @image latex lcd_write_excerpt.eps "Excerpt from the lcd_write funkiton" width=\textwidth
  193 +
  194 + The following screen shot shows a more close view on a data operation. Signals
  195 + two and four are not shown to be able to concentrate on the data operation.
  196 + The display will read the data at a falling edge of the clock (E) signal. We
  197 + can also see, that new data is set up shortly before the rising edge of the
  198 + clock.
  199 +
  200 + @image html disp_data_exchange_excerpt.png "Closeup data writing operation"
  201 + @image latex disp_data_exchange_excerpt.png "Closeup data writing operation" width=\textwidth
  202 +
  203 + @subsection lcd_init_desc LCD initialisation: LCD_INIT
  204 +
  205 + This macro initialises the display in 4 pin mode and switches it on. To do
  206 + so, it must follow a sequence during which the display can be brought into a
  207 + certain state. The following table will show the steps:
  208 +
  209 + <table border="1">
  210 + <tr>
  211 + <th><b>Action</b></th>
  212 + <th><b>Description</b></th>
  213 + <th><b>Command</b></th>
  214 + </tr>
  215 + <tr>
  216 + <td>Wait for 15ms</td>
  217 + <td>Power on delay.</td>
  218 + <td>_delay_ms(15);</td>
  219 + </tr>
  220 + <tr>
  221 + <td>Send 0011 as command</td>
  222 + <td>Initialisation command. The display controller expects this.</td>
  223 + <td>LCD_CMD_NIBBLE( 0b0011 );</td>
  224 + </tr>
  225 + <tr>
  226 + <td>Wait for 5 ms</td>
  227 + <td>
  228 + The display controller demands a delay of more than 4.1 ms. 5 ms is
  229 + used.
  230 + </td>
  231 + <td>_delay_ms(5);</td>
  232 + </tr>
  233 + <tr>
  234 + <td>Send 0011 as command</td>
  235 + <td>Initialisation command. The display expects this.</td>
  236 + <td>LCD_CMD_NIBBLE( 0b0011 );</td>
  237 + </tr>
  238 + <tr>
  239 + <td>Wait for 1 ms</td>
  240 + <td>
  241 + The display controller demands a delay of more than 100 us. 1 ms is
  242 + used.
  243 + </td>
  244 + <td>_delay_ms(1);</td>
  245 + </tr>
  246 + <tr>
  247 + <td>Send 0011 as command</td>
  248 + <td>Initialisation command. The display expects this.</td>
  249 + <td>LCD_CMD_NIBBLE( 0b0011 );</td>
  250 + </tr>
  251 + <tr>
  252 + <td>Wait for 1 ms</td>
  253 + <td>
  254 + The data sheet for the display controller does not request a delay here.
  255 + There is one anyway, because the supervisors reference function uses
  256 + one here. After the initialisation worked, removing the delay was not
  257 + tested.
  258 + </td>
  259 + <td>_delay_ms(1);</td>
  260 + </tr>
  261 + <tr>
  262 + <td>Send 0011 as command</td>
  263 + <td>Initialisation command. The display expects this.</td>
  264 + <td>LCD_CMD_NIBBLE( 0b0011 );</td>
  265 + </tr>
  266 + <tr>
  267 + <td>Wait for 1 ms</td>
  268 + <td>
  269 + The data sheet for the display controller does not request a delay here.
  270 + There is one anyway, because the supervisors reference function uses
  271 + one here. After the initialisation worked, removing the delay was not
  272 + tested.
  273 + </td>
  274 + <td>_delay_ms(1);</td>
  275 + </tr>
  276 + </table>
  277 + <table border="1">
  278 + <tr>
  279 + <td>Funktion Set: Byte 00101000 is written as command</td>
  280 + <td>
  281 + With the function set command, the display allows to set (next to
  282 + others) the mode for the interface. We use choose the 4 bit interface.
  283 + The data sheet is inconsistent here. In the instruction table, other
  284 + pins claim this functionality than in the initialisation description.
  285 + We used the instruction table as reference, since this was also what
  286 + the initialisation reference function from our supervisor did.
  287 + </td>
  288 + <td>LCD_CMD_BYTE( 0b00101000 );</td>
  289 + </tr>
  290 + <tr>
  291 + <td>Wait for 1 ms</td>
  292 + <td>
  293 + The data sheet for the display controller does not request a delay here.
  294 + There is one anyway, because the supervisors reference function uses
  295 + one here. After the initialisation worked, removing the delay was not
  296 + tested. Also, this delay respects execution time the LCD might need.
  297 + </td>
  298 + <td>_delay_ms(1);</td>
  299 + </tr>
  300 + <tr>
  301 + <td>Display off: Byte 00001000 is written as command</td>
  302 + <td>Turns the display off. Expected command by the display controller.</td>
  303 + <td>LCD_CMD_BYTE( 0b00001000 );</td>
  304 + </tr>
  305 + <tr>
  306 + <td>Wait for 1 ms</td>
  307 + <td>
  308 + The data sheet for the display controller does not request a delay here.
  309 + There is one anyway, because the supervisors reference function uses
  310 + one here. After the initialisation worked, removing the delay was not
  311 + tested. Also, this delay respects execution time the LCD might need.
  312 + </td>
  313 + <td>_delay_ms(1);</td>
  314 + </tr>
  315 + <tr>
  316 + <td>Display clear: Byte 00000001 is written as command.</td>
  317 + <td>Clears the display. Expected command by the display controller.</td>
  318 + <td>LCD_CMD_BYTE( 0b00000001 );</td>
  319 + </tr>
  320 + </table>
  321 + <table border="1">
  322 + <tr>
  323 + <td>Wait for 2 ms</td>
  324 + <td>
  325 + The instruction table in the display controller data sheet specifies a
  326 + minimum execution time of 1.54 ms to clear the display. 2 ms is used
  327 + instead.
  328 + </td>
  329 + <td>_delay_ms(2);</td>
  330 + </tr>
  331 + <tr>
  332 + <td>Entry mode set: Byte 00000110 is written as command.</td>
  333 + <td>
  334 + The cursor movement is set set to increment, the shift property is
  335 + disabled.
  336 + </td>
  337 + <td>LCD_CMD_BYTE( 0b00000110 );</td>
  338 + </tr>
  339 + <tr>
  340 + <td>Display on: Byte 00001100 is written as a command.</td>
  341 + <td>
  342 + Switches the display on, so there is no need to do so on the user side.
  343 + This is no more part of the required initialisation for the display
  344 + controller.
  345 + </td>
  346 + <td>LCD_CMD_BYTE( 0b00001100 );</td>
  347 + </tr>
  348 + </table>
  349 +
  350 + The following oscilloscope picture shows the signals (in this order) E, RS,
  351 + D4, D5 for the entire display initialisation described above. The data lines
  352 + D6 and D7 are not on the picture because the oscilloscope only has 4 inputs.
  353 +
  354 + @image html lcd_init_complete.png "Oscilloscope screen shot for the LCD_INIT macro."
  355 + @image latex lcd_init_complete.eps "Oscilloscope screen shot for the LCD_INIT macro." width=\textwidth
  356 +
  357 +*/
83 08_testing_c.dox
... ... @@ -1,19 +1,32 @@
1 1 /*!
2 2 @page testing_c C tests
3 3
4   -@section display_test Display test
5   -
6   - The file ::display_test.c tests all macros and funktions in ::display.h . To
7   - understand the tests, please read the comments in ::display_test.c. The
8   - comments guide through the test. They have the following structure:
  4 +@section about_test About testing the C code
  5 +
  6 + Although there would be the possibility of using a unit test like system for
  7 + testing C code (http://throwtheswitch.org/white-papers/unity-intro.html), using
  8 + it was not scope of the course. Also, the requested type of test (namely:
  9 + Screen shots from debuggers) has more the characteristic of a one time proof
  10 + that a macro or function works. Therefore, the test found in this sections are
  11 + rarely capable to detect regressions in an easy way or add more test for new
  12 + features to a set of existing tests.
9 13
  14 +@section display_test Display header files
  15 +
  16 + The file display_test.c tests all macros and funktions in display.h . To
  17 + understand the tests, please read the comments in display_test.c. The
  18 + comments guide through the test and have the following structure.
10 19
11 20 # TEST {number}
12 21 #
13   - # Wath is tested: {description}
  22 + # What is tested: {description}
14 23 #
15 24 # {Description on how it works and what might be seen in some cases.}
16 25
  26 + By testing display.h, also display_snippets.h is tested since most macros
  27 + and functions in display.h use almost every macro/funktions in
  28 + display_snippets.h .
  29 +
17 30 Here are pictures form a successfull test run. The pictures are in order.
18 31
19 32 @image html disp_test_1.png "Picture of successful TEST 1"
@@ -37,4 +50,62 @@
37 50 @image html disp_test_7.png "Picture of successful TEST 7"
38 51 @image latex disp_test_7.eps "Picture of successful TEST 7" width=\textwidth
39 52
  53 +
  54 +@section timer_test Timer header file
  55 +
  56 + The timer methods in the file timers.h are tested by two different C files.
  57 + The first one timer_0_test.c was created to test all methods written for
  58 + timer 0. The file timer_1_test.c tests methods written for timer 1. Both C
  59 + files have the same basic structure with one exceptions: the file to test
  60 + timer 1 also checks if the handling of the extra compare register and flag is
  61 + working.
  62 +
  63 + It must be stressed, that close study of the well commented test files is the
  64 + only way to throughly understand what will be described here and to adapt the
  65 + test to new features.
  66 +
  67 + @supsection timer_test_desc Test description
  68 +
  69 + The test for timer 0 and timer 1 related macros and functions work in a very
  70 + similar way. The only major difference shows itself in the very beginning of
  71 + the tests and will me mentioned.
  72 +
  73 + The AVR development board LED is used to make the tests visible. The correct
  74 + kind and order of the LED being lid, represents a successful test.
  75 +
  76 + Here is a small guide with some notes through the test:
  77 +
  78 + The test starts with one very short short flash for the timer 0 test and two
  79 + short flashes for the timer 1 test. To allow the eye to prepare itself, one
  80 + second delays are placed after, before and in between the flashes.
  81 + After the flashes, the timer interrupt is activated. In the interrupt routine,
  82 + the LED is toggled after a certain amount of interrupt calls. This causes the
  83 + LED to blink. During this prozess, the timer speed will be changed. The LED
  84 + blinks slower. Another speed change for the timer happens, the LED will blink
  85 + fast again.
  86 + Finally, the timer might be stopped or the interrupt deactivated. This depends
  87 + on what the tester would like to test. From stopping the timer, no recovery is
  88 + designated. The LED will not light up any more. If the interrupt is
  89 + deactivated, it can be reactivated after a 5 seconds delay, depending on the
  90 + preference of the tester.
  91 +
  92 + To test the reset functionality, a special test was used, using the button of
  93 + the AVR development board. If the button is pushed, the timer will be reset
  94 + as long it is pushed. The LED will keep its state as long the button is
  95 + pushed. This test is especially verbose during the blinking phases of the
  96 + LED.
  97 +
  98 + It must again be stressed, to fully understand the testing, the source for
  99 + timer_0_test.c or timer_1_test.c must be studied.
  100 +
  101 +
  102 + @subsection timer_test_oddity Unexplainable behaviour
  103 +
  104 + After the short flashes at the beginning of the timer 1 test, the LED stays
  105 + lid for an oddly long time. A lower TOP value for the timer seemed to resolve
  106 + the problem, but this did not explain the unexpected behaviour when using a
  107 + higher value. The test is considered to be passed anyway, because the rest of
  108 + the test is unambiguous enough to verify the functionality of all tested
  109 + macros and functions.
  110 +
40 111 */

0 comments on commit c836a61

Please sign in to comment.
Something went wrong with that request. Please try again.