improved comments

firmware/dcftime.c

@@ -2,7 +2,7 @@
  * \file dcftime.c
  * \brief Decoder for DCF-77 time signals
  * \author Ronald Schaten & Thomas Stegemann
- * \version $Id: dcftime.c,v 1.1 2007/01/02 21:30:40 rschaten Exp $
+ * \version $Id: dcftime.c,v 1.2 2007/01/03 12:38:55 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -78,7 +78,7 @@ static struct dcf_data_struct dcf_data; /**< full set of received dcf data */
 
 /**
  * Initialize a dcf_time value.
- * \param pTime: pointer to a dcf_time variable
+ * \param pTime pointer to a dcf_time variable
  */
 static void dcf_time_init(dcf_time * pTime) {
     pTime->second = 0;
@@ -89,7 +89,7 @@ static void dcf_time_init(dcf_time * pTime) {
 
 /**
  * Increment a time-value by one second.
- * \param pTime: pointer to a dcf_time variable
+ * \param pTime pointer to a dcf_time variable
  * \return True if the date has to be incremented, too. Otherwise False.
  */
 static boolean dcf_time_inc(dcf_time * pTime) {
@@ -111,7 +111,7 @@ static boolean dcf_time_inc(dcf_time * pTime) {
 
 /**
  * Check if a time-value makes sense.
- * \param pTime: pointer to a dcf_time variable
+ * \param pTime pointer to a dcf_time variable
  * \return True if the time is logically correct. Otherwise False.
  */
 static boolean dcf_time_is_valid(dcf_time * pTime) {
@@ -126,7 +126,7 @@ static boolean dcf_time_is_valid(dcf_time * pTime) {
 
 /**
  * Initialize a dcf_date value.
- * \param pDate: pointer to a dcf_date variable
+ * \param pDate pointer to a dcf_date variable
  */
 static void dcf_date_init(dcf_date * pDate) {
     pDate->dayofweek = dcf_sunday;
@@ -137,7 +137,7 @@ static void dcf_date_init(dcf_date * pDate) {
 
 /**
  * Calculate the number of days in a month.
- * \param pDate: pointer to a dcf_time variable
+ * \param pDate pointer to a dcf_time variable
  * \return The number of days in the given month.
  */
 static dcf_sizetype dcf_date_days_in_month(dcf_date * pDate) {
@@ -173,7 +173,7 @@ static dcf_sizetype dcf_date_days_in_month(dcf_date * pDate) {
 
 /**
  * Increment a date-value by one day.
- * \param pDate: pointer to a dcf_date variable
+ * \param pDate pointer to a dcf_date variable
  */
 static void dcf_date_inc(dcf_date * pDate) {
     ++(pDate->dayofweek);
@@ -197,7 +197,7 @@ static void dcf_date_inc(dcf_date * pDate) {
 
 /**
  * Check if a date-value makes sense.
- * \param pDate: pointer to a dcf_date variable
+ * \param pDate pointer to a dcf_date variable
  * \return True if the date is logically correct. Otherwise False.
  */
 static boolean dcf_date_is_valid(dcf_date * pDate) {
@@ -215,7 +215,7 @@ static boolean dcf_date_is_valid(dcf_date * pDate) {
 */
 /**
  * Initialize a dcf_datetime value.
- * \param pDatetime: pointer to a dcf_datetime variable
+ * \param pDatetime pointer to a dcf_datetime variable
  */
 static void dcf_datetime_init(dcf_datetime * pDatetime) {
     pDatetime->is_valid = False;
@@ -226,7 +226,7 @@ static void dcf_datetime_init(dcf_datetime * pDatetime) {
 
 /**
  * Increment a datetime-value by one second.
- * \param pDatetime: pointer to a dcf_datetime variable
+ * \param pDatetime pointer to a dcf_datetime variable
  */
 static void dcf_datetime_inc(dcf_datetime * pDatetime) {
     if (dcf_time_inc(&(pDatetime->time))) {
@@ -240,7 +240,7 @@ static void dcf_datetime_inc(dcf_datetime * pDatetime) {
 
 /**
  * Initialize a dcf_receiving_data value.
- * \param pReceive: pointer to a dcf_receiving_data variable
+ * \param pReceive pointer to a dcf_receiving_data variable
  */
 static void dcf_receiving_data_init(dcf_receiving_data * pReceive) {
     pReceive->current_signal = dcf_signal_no;
@@ -254,7 +254,7 @@ static void dcf_receiving_data_init(dcf_receiving_data * pReceive) {
 
 /**
  * Calculate the time and date while the bits are received.
- * \param signal: True if the received bit is 200ms, False if the bit is 100ms.
+ * \param signal True if the received bit is 200ms, False if the bit is 100ms.
  */
 static void dcf_logic(boolean signal) {
     dcf_data.receiving_data.parity ^= signal;

firmware/dcftime.h

@@ -5,7 +5,7 @@
  * \file dcftime.h
  * \brief Decoder for DCF-77 time signals
  * \author Ronald Schaten & Thomas Stegemann
- * \version $Id: dcftime.h,v 1.1 2007/01/02 21:30:40 rschaten Exp $
+ * \version $Id: dcftime.h,v 1.2 2007/01/03 12:38:55 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -100,7 +100,7 @@ void dcf_init(void);
  * the received bit is a long or a short one, and if it is usable at all. It
  * should be called regularly, the number of calls per second is defined in
  * DCF_RATE.
- * \param signal: True if the input signal is high, False if it is low.
+ * \param signal True if the input signal is high, False if it is low.
  */
 void dcf_signal(boolean signal);
 
@@ -112,14 +112,14 @@ dcf_datetime dcf_current_datetime(void);
 
 /**
  * Get the name of the current weekday.
- * \param dow: Day of the current week. Monday = 1, tuesday = 2...
+ * \param dow Day of the current week. Monday = 1, tuesday = 2...
  * \return Pointer to the name
  */
 const char* dcf_dayofweek_name(dcf_dayofweek dow);
 
 /**
  * Get the name of the current daylight saving time (summertime, wintertime).
- * \param dst: daylight saving time bit from the time signal
+ * \param dst daylight saving time bit from the time signal
  * \return Pointer to the name
  */
 const char* dcf_is_dst_name(dcf_is_dst dst);

firmware/main.c

@@ -2,7 +2,7 @@
  * \file main.c
  * \brief Firmware for the binary DCF-77 clock
  * \author Ronald Schaten
- * \version $Id: main.c,v 1.1 2007/01/02 21:30:40 rschaten Exp $
+ * \version $Id: main.c,v 1.2 2007/01/03 12:38:55 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -15,21 +15,24 @@
 #include "saa1064.h"
 #include "dcftime.h"
 
-uint8_t byte[4] = { 2, 3, 1, 0 }; /** the order of the connected output-LED-rows */
+uint8_t byte[4] = { 2, 3, 1, 0 }; /**< the order of the connected output-LED-rows */
-uint8_t output[4], outputOld[4]; /** current and old content of the LEDs */
+uint8_t output[4]; /**< current content of the LEDs */
+uint8_t outputOld[4]; /**< old content of the LEDs */
 
 /** the display-modes */
 enum modes {
-    timeasbinary,
+    timeasbinary, /**< display hours, minutes and seconds, one byte per row */
-    dateasbinary,
+    dateasbinary, /**< display day of month, month, year and day of week, one byte per row */
-    timeasbcdhorizontal,
+    timeasbcdhorizontal, /**< display hours, minutes and seconds, two BCDs per row */
-    dateasbcdhorizontal,
+    dateasbcdhorizontal, /**< display day of month, month, year and day of week, two BCDs per row */
-    timeasbcdvertical,
+    timeasbcdvertical, /**< display hours, minutes and seconds, one BCD per column */
-    dateasbcdvertical,
+    dateasbcdvertical, /**< display day of month, month and year, one BCD per column */
-    timestamp
+    timestamp /**< display unix timestamp, one byte per row */
 };
+/** the current display-mode */
 enum modes mode;
 
+/** demo mode active */
 uint8_t demomode = 0;
 
 
@@ -48,7 +51,7 @@ void setLeds(void) {
 
 /**
  * Takes the current time and converts it into different output-formats.
- * \param datetime: the current time
+ * \param datetime the current time
  */
 void setOutput(dcf_datetime datetime) {
     uint8_t bcdlow, bcdhigh; /* takes the low and high parts when converting to BCD */

firmware/saa1064.c

@@ -2,7 +2,7 @@
  * \file saa1064.c
  * \brief I2C-connection to the SAA1064 LED-driver
  * \author Ronald Schaten
- * \version $Id: saa1064.c,v 1.1 2007/01/02 21:30:40 rschaten Exp $
+ * \version $Id: saa1064.c,v 1.2 2007/01/03 12:38:55 rschaten Exp $
  *
  * License: See documentation.
  */
@@ -13,33 +13,30 @@
 #include <util/delay.h>
 #include "saa1064.h"
 
-/* The Port used for the connection */
+#define LEDPORT PORTC /**< the Port used for the connection */
-#define LEDPORT PORTC
+#define LEDPIN PINC /**< the Port used for the connection */
-#define LEDPIN PINC
+#define LEDDDR DDRC /**< the Port used for the connection */
-#define LEDDDR DDRC
 
-/* Which pins of the port */
+#define SDAPIN PC4 /**< which pins of the port */
-#define SDAPIN PC4
+#define SCLPIN PC5 /**< which pins of the port */
-#define SCLPIN PC5
 
-/* the I2C addresses of the SAA 1064 LED drivers */
+#define SAA_ADR 0x70 /**< the I2C addresses of the SAA 1064 LED drivers */
-#define SAA_AD1 0x70 // or 0x76?
 
-#define I2C_READ  0x01
+#define I2C_READ  0x01 /**< command used to read from I2C */
-#define I2C_WRITE 0x00
+#define I2C_WRITE 0x00 /**< command used to write to I2C */
 
-/* Should be at least 27 (80 / 3) at 8 MHz */
+#define DELAYVAL 3 /**< pause between certain actions on the bus. Should be at least (10 * freq) / 3, so we set 3 at 1 MHz */
-/* This was the conservative value used for testing. However, half as much should work as well. */
-#define DELAYVAL 3
 
 void led_init(void) {
     /* activate pullups */
     LEDPORT |= (1 << SCLPIN) | (1 << SDAPIN);
 }
 
-/* Send START, defined as high-to-low SDA with SCL high.
+/**
+ * Send START, defined as high-to-low SDA with SCL high.
  * Expects SCL and SDA to be high already!
- * Returns with SDA and SCL low. */
+ * Returns with SDA and SCL low.
+ */
 static void I2C_start(void) {
     /* Change to output mode. */
     LEDDDR |= (1 << SDAPIN) | (1 << SCLPIN);
@@ -51,9 +48,11 @@ static void I2C_start(void) {
     _delay_loop_1(DELAYVAL);
 }
 
-/* Send STOP, defined as low-to-high SDA with SCL high.
+/**
+ * Send STOP, defined as low-to-high SDA with SCL high.
  * Expects SCL and SDA to be low already!
- * Returns with SDA and SCL high. */
+ * Returns with SDA and SCL high.
+ */
 static void I2C_stop(void) {
     /* Set SCL */
     LEDPORT |= (1 << SCLPIN);
@@ -65,10 +64,13 @@ static void I2C_stop(void) {
     LEDDDR &= ~((1 << SDAPIN) | (1 << SCLPIN));
 }
 
-/* Transmits the byte in what.
+/**
+ * Transmits the byte in parameter what.
  * Returns 1 if the byte was ACKed, 0 if not.
  * Expects SCL and SDA to be low already!
- * Returns with SDA and SCL low. */
+ * Returns with SDA and SCL low.
+ * \param what the byte to transmit
+ */
 static uint8_t I2C_transmit_byte(uint8_t what) {
     uint8_t i;
     for (i = 0; i < 8; i++) {
@@ -115,7 +117,7 @@ static uint8_t I2C_transmit_byte(uint8_t what) {
 void set_led_digit(uint8_t digit, uint8_t val) {
     I2C_start();
     /* Address device */
-    I2C_transmit_byte(SAA_AD1 | I2C_WRITE);
+    I2C_transmit_byte(SAA_ADR | I2C_WRITE);
     I2C_transmit_byte((digit & 3) + 1); /* Address Digit Register on device */
     I2C_transmit_byte(val);     /* Send value for Digit */
     I2C_stop();
@@ -123,7 +125,7 @@ void set_led_digit(uint8_t digit, uint8_t val) {
 
 void set_led_brightness(uint8_t led_brightness) {
     I2C_start();
-    I2C_transmit_byte(SAA_AD1 | I2C_WRITE);     /* Address first driver */
+    I2C_transmit_byte(SAA_ADR | I2C_WRITE);     /* Address first driver */
     I2C_transmit_byte(0);       /* Address Config Register on device */
     I2C_transmit_byte(((led_brightness & 0x07) << 4) | 0x07);   /* Send Settings */
     I2C_stop();

firmware/saa1064.h

@@ -5,23 +5,30 @@
  * \file saa1064.h
  * \brief I2C-connection to the SAA1064 LED-driver
  * \author Ronald Schaten
- * \version $Id: saa1064.h,v 1.1 2007/01/02 21:30:40 rschaten Exp $
+ * \version $Id: saa1064.h,v 1.2 2007/01/03 12:38:55 rschaten Exp $
  *
  * License: See documentation.
  */
 
 /* based on http://www.mulder.franken.de/ntpdcfledclock/ */
 
-/* This sets one digit on the LED module.
+/**
- * digit   is the number of the digit (0 - 7)
+ * This sets one digit on the LED module.
- * val     is a bitfield that contains the values to set. */
+ * \param digit the number of the digit (0 - 3)
+ * \param val a bitfield that contains the values to set
+ */
 void set_led_digit(uint8_t digit, uint8_t val);
 
-/* Configures the brightness of the LED module, or rather: the current the driver allows through them.
+/**
- * The values 0 through 7 can be used, corresponding to 0 through 21 mA */
+ * Configures the brightness of the LEDs. Or rather: the current the driver allows through them.
+ * \param led_brightness The values 0 through 7 can be used, corresponding to 0 through 21 mA
+ */
 void set_led_brightness(uint8_t led_brightness);
 
-/* Initialize the LED module... This basically enables the pullups on the I2C Bus pins */
+/**
+ * Initialize the LED module. This basically enables the pullups on the I2C Bus
+ * pins.
+ */
 void led_init(void);
 
 #endif