improved comments

This commit is contained in:
Ronald Schaten 2007-01-03 12:38:55 +00:00
parent 8c0e19cf1c
commit 1f77141a10
5 changed files with 69 additions and 57 deletions

View File

@ -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;

View File

@ -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);

View File

@ -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 output[4], outputOld[4]; /** current and old content of the LEDs */
uint8_t byte[4] = { 2, 3, 1, 0 }; /**< the order of the connected output-LED-rows */
uint8_t output[4]; /**< current content of the LEDs */
uint8_t outputOld[4]; /**< old content of the LEDs */
/** the display-modes */
enum modes {
timeasbinary,
dateasbinary,
timeasbcdhorizontal,
dateasbcdhorizontal,
timeasbcdvertical,
dateasbcdvertical,
timestamp
timeasbinary, /**< display hours, minutes and seconds, one byte per row */
dateasbinary, /**< display day of month, month, year and day of week, one byte per row */
timeasbcdhorizontal, /**< display hours, minutes and seconds, two BCDs per row */
dateasbcdhorizontal, /**< display day of month, month, year and day of week, two BCDs per row */
timeasbcdvertical, /**< display hours, minutes and seconds, one BCD per column */
dateasbcdvertical, /**< display day of month, month and year, one BCD per column */
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 */

View File

@ -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
#define LEDPIN PINC
#define LEDDDR DDRC
#define LEDPORT PORTC /**< the Port used for the connection */
#define LEDPIN PINC /**< the Port used for the connection */
#define LEDDDR DDRC /**< the Port used for the connection */
/* Which pins of the port */
#define SDAPIN PC4
#define SCLPIN PC5
#define SDAPIN PC4 /**< which pins of the port */
#define SCLPIN PC5 /**< which pins of the port */
/* the I2C addresses of the SAA 1064 LED drivers */
#define SAA_AD1 0x70 // or 0x76?
#define SAA_ADR 0x70 /**< the I2C addresses of the SAA 1064 LED drivers */
#define I2C_READ 0x01
#define I2C_WRITE 0x00
#define I2C_READ 0x01 /**< command used to read from I2C */
#define I2C_WRITE 0x00 /**< command used to write to I2C */
/* Should be at least 27 (80 / 3) at 8 MHz */
/* This was the conservative value used for testing. However, half as much should work as well. */
#define DELAYVAL 3
#define DELAYVAL 3 /**< pause between certain actions on the bus. Should be at least (10 * freq) / 3, so we set 3 at 1 MHz */
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();

View File

@ -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)
* val is a bitfield that contains the values to set. */
/**
* This sets one digit on the LED module.
* \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