Wiblocks --- RTC Class for DS1337

RTC Library

Library

The RTC C++ library controls the DS1337 real-time clock IC that is on the NB1A. Functions are available to read and write the DS1337 registers and to setup the alarm functions. A localtime function is provided that formats the time and date as a string.

The RTC library requires the TWI library (I2C). Setup of the TWI library is required prior to accessing the DS1337. The example Arduino loop below reads the time from the DS1337 and prints a time string to the serial port. The example assumes that the TWI has been initialized in the setup block. 
void loop() {
  char timestr[22];
  while(1) {
    rtc.read_regs();
    rtc.localtime(timestr);
    Serial.print(timestr);
    Serial.print("\r");
    delay(1000);
  }
}
Public Member Functions | Static Public Attributes

RTC Class Reference

Class for the Maxim DS1337 Real-time Clock IC. More...

Public Member Functions

 RTC ()
char write_reg_ptr (unsigned char reg)
char write_reg (unsigned char reg, unsigned char v)
char write_regs (unsigned char reg, unsigned char *v, unsigned char n)
unsigned char read_reg (unsigned char reg)
char read_regs ()
unsigned char get_secs ()
unsigned char get_mins ()
unsigned char get_hours ()
unsigned char get_day ()
unsigned char get_month ()
unsigned int get_year ()
unsigned char set_year (unsigned int year)
unsigned char set_month (unsigned char month)
unsigned char set_day (unsigned char day)
unsigned char set_date (unsigned int year, unsigned char month, unsigned char day)
unsigned char set_secs (unsigned char secs)
unsigned char set_mins (unsigned char mins)
unsigned char set_hours12 (unsigned char hours, unsigned char pm_p)
unsigned char set_hours (unsigned char hours)
unsigned char set_time (unsigned char hours, unsigned char mins, unsigned char secs)
unsigned char set_time12 (unsigned char hours, unsigned char mins, unsigned char secs, unsigned char pm_p)
unsigned char set_alarm1 (unsigned char mode, unsigned char day_or_dow, unsigned char hours, unsigned char mins, unsigned char secs)
unsigned char enable_alarm1 (void)
unsigned char clear_alarm1 (void)
void localtime (char *str)
unsigned char get_reg (unsigned char reg)

Static Public Attributes

static const unsigned char _i2c_rd_address = (0x68 << 1) | 0x01
 I2C read address (8 bit).
static const unsigned char _i2c_wr_address = (0x68 << 1) | 0x00
 I2C write address (8 bit).

Detailed Description

Class for the Maxim DS1337 Real-time Clock IC.

The main data structure in the RTC class enables access to the DS1337 register values as bit fields, bytes, or an array of bytes. The union _regs creates overlays three data structures -- reg_bits (bit fields), reg_bytes (byte fields) and reg_array (array of bytes).

Definition at line 83 of file RTC.h.

Constructor & Destructor Documentation

RTC::RTC (  ) 

Constructs an RTC object.

Todo:
Add intialization for the interrupt line connections. By default alarm output 1 is connected to Pin 6 (PD6) and alarm output 2 is connected to Pin 5 (PD5)

Definition at line 40 of file RTC.cpp.

Member Function Documentation

unsigned char RTC::clear_alarm1 ( void   ) 

Clears the alarm1 interrupt flag.

Todo:
add return error codes

Definition at line 444 of file RTC.cpp.

unsigned char RTC::enable_alarm1 ( void   ) 

Enables the interrupt for alarm1

Todo:
add return error codes

Definition at line 456 of file RTC.cpp.

unsigned char RTC::get_day (  ) 

Returns the last value of the day register that was read

Definition at line 167 of file RTC.cpp.

unsigned char RTC::get_hours (  ) 

Returns the last value of hours register that was read

Definition at line 163 of file RTC.cpp.

unsigned char RTC::get_mins (  ) 

Returns the last value of minutes register that was read

Definition at line 159 of file RTC.cpp.

unsigned char RTC::get_month (  ) 

Returns the last value of the month register that was read

Definition at line 171 of file RTC.cpp.

unsigned char RTC::get_reg ( unsigned char  reg  ) 

Returns the last read value of RTC register reg

Parameters:
[in] reg DS1337 register number.
Returns:
the last read value of reg from the DS1337 data structure.

Definition at line 503 of file RTC.cpp.

unsigned char RTC::get_secs (  ) 

Returns the last value of seconds register that was read

Definition at line 155 of file RTC.cpp.

unsigned int RTC::get_year (  ) 

Returns the last value of the year register that was read

Definition at line 175 of file RTC.cpp.

void RTC::localtime ( char *  str  ) 

Returns a 23 character null terminated string containing the most recent date and time that was read from the DS1337. The string format is yyyy-mm-dd hh:mm:mm AM

Parameters:
[out] *str pointer to memory location that will contain the output string

Definition at line 477 of file RTC.cpp.

unsigned char RTC::read_reg ( unsigned char  reg  ) 

Reads and returns the value of a DS1337 register.

Parameters:
[in] reg DS1337 register
Returns:
the value for DS1337 register reg
Todo:
Add TWI transmit error codes

Definition at line 128 of file RTC.cpp.

char RTC::read_regs (  ) 

Reads all of the DS1337 registers into the RTC data structure

Return values:
0 success
-1 TWI transmit error

Definition at line 107 of file RTC.cpp.

unsigned char RTC::set_alarm1 ( unsigned char  mode,
unsigned char  day_or_dow,
unsigned char  hours,
unsigned char  mins,
unsigned char  secs 
)

Setup alarm mode and conditions for alarm1. After the alarm is setup it needs to be enabled using enable_alarm1.

Parameters:
[in] mode one of values listed below.

RTC_ALARM1_MODE1   once per second
RTC_ALARM1_MODE2   when the seconds match
RTC_ALARM1_MODE3   when the minutes and seconds match
RTC_ALARM1_MODE4   when the hours, minutes, seconds, match
RTC_ALARM1_MODE5   when the day, hours, minutes, seconds, match
RTC_ALARM1_MODE6   when the dow, hours, minutes, seconds, match
Parameters:
[in] day_or_dow 1..31 for RTC_ALARM_MODE5 1..7 for RTC_ALARM_MODE6
[in] hours 0..23
[in] mins 0..59
[in] secs 0..59
Todo:

add return error codes

add bounds checking for parameters

Definition at line 396 of file RTC.cpp.

unsigned char RTC::set_date ( unsigned int  year,
unsigned char  month,
unsigned char  day 
)

Sets the RTC date.

Parameters:
[in] year valid values are from 2000..2099 inclusive
[in] month valid values are from 1..12 inclusive
[in] day valid values are from 1..31 inclusive
Return values:
0 success
-1 invalid parameter value
Todo:
check for valid values for year, month and day prior to calling any functions

Definition at line 246 of file RTC.cpp.

unsigned char RTC::set_day ( unsigned char  day  ) 

Sets the RTC day register.

Parameters:
[in] day valid values are from 1..31 inclusive
Return values:
0 success
-1 invalid parameter value

Definition at line 228 of file RTC.cpp.

unsigned char RTC::set_hours ( unsigned char  hours  ) 

Sets the RTC hours register, in 24 hour mode, to hours. If hours is greater than 23 than an error code is returned and the RTC register is not changed.

Definition at line 329 of file RTC.cpp.

unsigned char RTC::set_hours12 ( unsigned char  hours,
unsigned char  pm_p 
)

Sets the RTC hours register, in 12 hour mode, to hours. If hours is greater than 12 than an error code is returned and the RTC register is not changed.

Definition at line 313 of file RTC.cpp.

unsigned char RTC::set_mins ( unsigned char  mins  ) 

Sets the RTC minutes register.

Parameters:
[in] mins valid values are from 0..59 inclusive
Return values:
0 success
-1 invalid parameter value

Definition at line 275 of file RTC.cpp.

unsigned char RTC::set_month ( unsigned char  month  ) 

Sets the RTC month register.

Parameters:
[in] month valid values are from 1..12 inclusive
Return values:
0 success
-1 invalid parameter value

Definition at line 213 of file RTC.cpp.

unsigned char RTC::set_secs ( unsigned char  secs  ) 

Sets the RTC seconds register.

Parameters:
[in] secs valid values are from 0..59 inclusive
Return values:
0 success
-1 invalid parameter value

Definition at line 261 of file RTC.cpp.

unsigned char RTC::set_time ( unsigned char  hours,
unsigned char  mins,
unsigned char  secs 
)

Sets the RTC time (24 hour mode) to hours, mins, secs

Definition at line 342 of file RTC.cpp.

unsigned char RTC::set_time12 ( unsigned char  hours,
unsigned char  mins,
unsigned char  secs,
unsigned char  pm_p 
)

Sets the RTC time (12 hour mode).

Parameters:
[in] hours 
[in] mins 
[in] secs 
[in] pm_p =1 for PM, =0 for AM

Definition at line 358 of file RTC.cpp.

unsigned char RTC::set_year ( unsigned int  year  ) 

Sets the RTC year register.

Parameters:
[in] year valid values are from 2000..2099 inclusive
Return values:
0 success
-1 invalid parameter value

Definition at line 196 of file RTC.cpp.

char RTC::write_reg ( unsigned char  reg,
unsigned char  v 
)

Writes a value to a DS1337 register

Parameters:
[in] reg DS1337 register
[in] v value to write
Return values:
0 success
-1 invalid parameter value
Todo:
Add TWI transmit error codes

Definition at line 54 of file RTC.cpp.

char RTC::write_reg_ptr ( unsigned char  reg  ) 

Sets the DS1337 register pointer

Parameters:
[in] reg register number
Return values:
0 success
-1 invalid parameter value
Todo:
Add error codes

Definition at line 93 of file RTC.cpp.

char RTC::write_regs ( unsigned char  reg,
unsigned char *  v,
unsigned char  n 
)

Writes values to a sequential block of registers.

Parameters:
[in] reg first register in the block
[in] *v pointer to the block of values to write
[in] n number of values in the block
Return values:
0 success
-1 invalid parameter value
Todo:
Add TWI transmit error codes

Definition at line 72 of file RTC.cpp.

The documentation for this class was generated from the following files:
Generated on Sun Aug 5 2012 15:29:45 by  doxygen 1.7.1