Style fixes and added some comments

doc/arduino-mega-lcd1602-keypad-shield-wiring.markdown

@@ -10,9 +10,21 @@ This shield consists of three logical parts:
 
 <div class=pagebreak></div>
 
+## Connection to Arduino Mega
+
+Following illustration shows how shield is connected to Arduino mega board.
+
+![arduino-mega-lcd1602-keypad-shield-placement.png](arduino-mega-lcd1602-keypad-shield-placement.png)
+
+Image source: [sainsmart.com](http://www.sainsmart.com/media/catalog/product/2/_/2_16_6.jpg)
+
+Additional installation details and tutorials can be found with help of keywords [Arduino 1602 lcd keypad shield tutorial](https://www.google.ee/webhp?q=Arduino+1602+lcd+keypad+shield+tutorial).
+
+<div class=pagebreak></div>
+
 ## Wiring illustration
 
-![Arduino Mega LCD1602 Keypad shield wiring LCD part.png](Arduino-Mega-LCD1602-keypad-shield-wiring.png)
+![arduino-mega-lcd1602-keypad-shield-wiring.png](arduino-mega-lcd1602-keypad-shield-wiring.png)
 
 Author: [Lauri Võsandi](http://lauri.võsandi.com/arduino/lcd1602-key-shield.html#hd44780)
 

doc/arduino-mega-usb-uart-wiring.markdown

@@ -6,12 +6,12 @@ This wiring schema uses only Tx from Arduino and is suitable to be used as stand
 
 ## Wiring illustration
 
-![Arduino Mega USB UART wiring.png](Arduino-Mega-USB-UART-wiring.png)
+![arduino-mega-usb-uart-wiring.png](arduino-mega-usb-uart-wiring.png)
 
 ## Wiring table
 
 | Signal | ATMega2560 port and pin | Arduino Mega 2560 pin | USB UART converter pin |
 | --- | --- | --- | --- |
 | Ground (GND) | GND | GND | GND |
-| Transmit data  from Arduino (TxD) | PORTJ pin 1 (TXD3) | Digital pin 14 (TX3) | TxD |
+| Transmit data  from Arduino (TxD) | PORTJ pin 1 (TXD3) | Digital pin 14 (TX3) | RxD |
 

src/hmi_msg.h

@@ -2,11 +2,11 @@
 #ifndef _HMI_MSG_H_
 #define _HMI_MSG_H_
 
-#define PROG_VERSION "Version: %S built on: %S %S\n"
-#define LIBC_VERSION "avr-libc version: %S\n"
+#define PROG_VERSION "Version: %S built on: %S %S"
+#define LIBC_VERSION "avr-libc version: %S"
 #define STUD_NAME "Arti Zirk"
 #define GET_MONTH_MSG "Enter Month name first letter >"
-#define UPTIME "Uptime: %lu s"
+#define UPTIME_MSG "Uptime: %lu s"
 
 const char m1[] PROGMEM = "January";
 const char m2[] PROGMEM = "February";

src/main.c

@@ -1,20 +1,21 @@
 #include <stdio.h>
 #include <string.h>
+#include <time.h>
 #include <avr/io.h>
-#include <avr/pgmspace.h>
 #include <avr/interrupt.h>
-#include <util/atomic.h>
+#include <avr/pgmspace.h>
 #include <util/delay.h>
 #include "hmi_msg.h"
-#include "uart-wrapper.h"
+#include "../lib/andygock_avr-uart/uart.h"
+#include "uart_wrap.h"
 #include "print_helper.h"
 #include "../lib/hd44780_111/hd44780.h"
-#include "../lib/andygock_avr-uart/uart.h"
 
-#define BAUD 9600
-#define BLINK_DELAY_MS 100
+#define BAUDRATE 9600
 
-volatile uint32_t time;
+// For configuring arduino mega pin 25
+#define LED_INIT DDRA |= _BV(DDA3);
+#define LED_TOGGLE PORTA ^= _BV(PORTA3)
 
 static inline void init_system_clock(void)
 {
@@ -25,31 +26,42 @@ static inline void init_system_clock(void)
     TIMSK5 |= _BV(OCIE5A); // Output Compare A Match Interrupt Enable
 }
 
-static inline void hw_init() {
-    DDRA |= _BV(DDA3); // setup Arduino pin 25 as output
-    uart0_init(UART_BAUD_SELECT(BAUD, F_CPU));
-    uart3_init(UART_BAUD_SELECT(BAUD, F_CPU));
+static inline void init_hw (void)
+{
+    // IO init
+    /// Set arduino pin 25 as output
+    LED_INIT;
+
+    // System clock
     init_system_clock();
-    sei(); // Enable interupts
+
+    // UART init
+    uart0_init(UART_BAUD_SELECT(BAUDRATE, F_CPU));
+    uart3_init(UART_BAUD_SELECT(BAUDRATE, F_CPU));
     stdout = stdin = &uart0_io;
     stderr = &uart3_out;
+
+    // LCD init
     lcd_init();
     lcd_clrscr();
+
+    // Enable interupts
+    sei();
 }
 
-static inline void print_prog_version() {
-    fprintf_P(stderr, PSTR(PROG_VERSION),
+static inline void start_ui (void)
+{
+    // Print program and libc versions
+    fprintf_P(stderr, PSTR(PROG_VERSION "\n"),
               PSTR(GIT_DESCR), PSTR(__DATE__), PSTR(__TIME__));
-    fprintf_P(stderr, PSTR(LIBC_VERSION), PSTR(__AVR_LIBC_VERSION_STRING__));
-}
+    fprintf_P(stderr, PSTR(LIBC_VERSION "\n"), PSTR(__AVR_LIBC_VERSION_STRING__));
 
-
-static inline void print_program_startup() {
+    // print student name
     fprintf_P(stdout, PSTR(STUD_NAME));
-    fputc('\n', stdout); /* Add a new line to the uart printout */
+    fputc('\n', stdout); // Add a new line to the uart printout
     lcd_puts_P(PSTR(STUD_NAME));
 
-    /* ASCII table print */
+    // ASCII table print
     print_ascii_tbl(stdout);
     unsigned char ascii[128];
     for (unsigned char i = 0; i < sizeof(ascii); i++) {
@@ -57,16 +69,17 @@ static inline void print_program_startup() {
     }
     print_for_human(stdout, ascii, sizeof(ascii));
 
+    // Bootstrap search_month message
     fprintf_P(stdout, PSTR(GET_MONTH_MSG));
 }
 
-
-static inline void search_month() {
-    /* Month search and print */
+static inline void search_month (void)
+{
     char letter;
+
     fscanf(stdin, "%c", &letter);
     fprintf(stdout, "%c\n", letter);
-    lcd_goto(0x40); /* Got to the beginning of the next line */
+    lcd_goto(0x40); // Got to the beginning of the next line
     for (int i = 0; i < 6; i++) {
         if (!strncmp_P(&letter, (PGM_P)pgm_read_word(&months[i]), 1)) {
             fprintf_P(stdout, (PGM_P)pgm_read_word(&months[i]));
@@ -75,42 +88,41 @@ static inline void search_month() {
             lcd_putc(' ');
         }
     }
+
+    // this is fine because even when the hd44780 address counter goes over 0xf4
+    // we still have quite a few addresses left until address counter overflow
+    // and we also dont care about the data that is at the end of the ddram
+    lcd_puts_P(PSTR("                ")); // Clear the end of the line
     fprintf_P(stdout, PSTR(GET_MONTH_MSG));
-    lcd_puts_P(PSTR("                ")); /* Clear the end of the line */
 }
 
-static inline void heartbeat() {
-    static uint32_t last_time;
-    uint32_t cur_time;
-    ATOMIC_BLOCK(ATOMIC_FORCEON) {
-        cur_time = time;
+static inline void heartbeat (void)
+{
+    static time_t time_prev;
+    time_t time_cur = time(NULL);
+    if (time_cur <= time_prev) {
+        return;
     }
-    if ((last_time - cur_time) > 0) {
-        // Toggle led on arduino pin 25
-        PORTA ^= _BV(PORTA3);
-        fprintf_P(stderr, PSTR(UPTIME "\n"), cur_time);
-    }
-    last_time = cur_time;
+    time_prev = time_cur;
+    fprintf_P(stderr, PSTR(UPTIME_MSG "\n"), time_cur);
+    LED_TOGGLE;
 }
 
 int main (void)
 {
-
-    hw_init();
-    print_prog_version();
-    print_program_startup();
-
+    init_hw();
+    start_ui();
 
     while (1) {
         heartbeat();
-        if(uart0_available()) {
+        if (uart0_available()) {
             search_month();
         }
     }
 }
 
-/* System clock ISR */
+// System clock
 ISR(TIMER5_COMPA_vect)
 {
-    time++;
+    system_tick();
 }

src/uart-wrapper.c

@@ -1,33 +0,0 @@
-#include <avr/io.h>
-#include <stdio.h>
-#include "../lib/andygock_avr-uart/uart.h"
-
-int uart0_putchar(char c, FILE *stream)
-{
-    (void) stream;
-
-    if (c == '\n') {
-        uart0_putchar('\r', stream);
-    }
-
-    uart0_putc(c);
-    return 0;
-}
-
-int uart3_putchar(char c, FILE *stream)
-{
-    (void) stream;
-
-    if (c == '\n') {
-        uart3_putchar('\r', stream);
-    }
-
-    uart3_putc(c);
-    return 0;
-}
-
-int uart0_getchar(FILE *stream)
-{
-    (void) stream;
-    return uart0_getc() & 0xff;
-}

src/uart-wrapper.h

@@ -1,15 +0,0 @@
-#ifndef _UART_WRAPPER_H_
-#define _UART_WRAPPER_H_
-
-int uart0_putchar(char c, FILE *stream);
-int uart0_getchar(FILE *stream);
-
-int uart3_putchar(char c, FILE *stream);
-
-
-/* http://www.ermicro.com/blog/?p=325 */
-
-FILE uart0_io = FDEV_SETUP_STREAM(uart0_putchar, uart0_getchar, _FDEV_SETUP_RW);
-FILE uart3_out = FDEV_SETUP_STREAM(uart3_putchar, NULL, _FDEV_SETUP_WRITE);
-
-#endif /* _UART_WRAPPER_H_ */

src/uart_wrap.c

@@ -0,0 +1,37 @@
+#include <avr/io.h>
+#include <stdio.h>
+#include "../lib/andygock_avr-uart/uart.h"
+
+int uart0_putc_wrap(char c, FILE *stream)
+{
+    (void) stream;
+
+    if (c == '\n') {
+        uart0_putc_wrap('\r', stream);
+    }
+
+    uart0_putc(c);
+    return 0;
+}
+
+int uart0_getc_wrap(FILE *stream)
+{
+    (void) stream;
+    // Probabbly should add some error checking in here but because
+    // this function is only called out when there is at least one character
+    // available in the input buffer (see main.c line 114) then error checking
+    // is not currently necessary.
+    return (char)uart0_getc();
+}
+
+int uart3_putc_wrap(char c, FILE *stream)
+{
+    (void) stream;
+
+    if (c == '\n') {
+        uart3_putc_wrap('\r', stream);
+    }
+
+    uart3_putc(c);
+    return 0;
+}

src/uart_wrap.h

@@ -0,0 +1,15 @@
+#ifndef _UART_WRAP_H_
+#define _UART_WRAP_H_
+
+int uart0_putc_wrap(char c, FILE *stream);
+int uart0_getc_wrap(FILE *stream);
+
+int uart3_putc_wrap(char c, FILE *stream);
+
+
+/* http://www.ermicro.com/blog/?p=325 */
+
+FILE uart0_io = FDEV_SETUP_STREAM(uart0_putc_wrap, uart0_getc_wrap, _FDEV_SETUP_RW);
+FILE uart3_out = FDEV_SETUP_STREAM(uart3_putc_wrap, NULL, _FDEV_SETUP_WRITE);
+
+#endif /* _UART_WRAP_H_ */