User:Darqchild
Contents
using the shield
API
setCH()
void setCH(bool halt)
Description
The method setCH modifies the value of the Clock Halt register on the DS1307. Setting CH will disable the oscillator, stopping both the clock and the square wave generator.
Arguments
- bool halt - If halt is true the DS1307 oscillator will be halted.
Return Value
None
Example
RTCShield clock; clock.setCH(true);
See Also
getCH()
bool getCH();
Description
Returns the value of the DS1307's Clock Halt register. See #getCH() for more information about the [Clock Halt] register.
Arguments
None
Return Value
Returns true if the DS1307's Clock Halt bit is set high.
Example
RTCShield clock;
if(clock.getCH()) {
Serial.println("Error: Clock is halted");
}
See Also
set12hour()
void set12hour(bool mode)
Description
Setting the value of the 12/24 register on the DS1307 configures the clock for 12 or 24 hour operation. The contents of the time registers are undefined after setting this bit. By default, after reset() is called the clock will be running in 24 hour mode.
Arguments
- bool mode - If mode is true the clock will use 12 hour mode. You must reset the time on the clock after changing the mode.
Return Value
None
Example
RTCShield clock;
struct Time time;
clock.getTime(&time); // read time out from shield
clock.set12hour(true) // switch shield in to 12 hour mode.
if (time.hours > 12) { // if it's afternoon
clock.hours -= 12; // subtract 12 hours from time
clock.ap = 1; // and set PM bit.
}
clock.setTime(&time); // write time back in to shield
See Also
get12hour()
bool get12hour()
Description
Returns the value of the 12/24 register on the DS1307. If this returns true the shield is running in 12 hour mode, and will set the Time.ap bit to indicate the afternoon.
Arguments
None
Return Value
The function returns a boolean value where true indicates 12 hour mode, and false indicates 24 hour mode.
Example =
RTCShield clock;
if(clock.get12Hour()) {
Serial.println("Clock is in 12 hour mode");
} else {
Serial.println("Clock is in 24 hour mode");
}
See Also
getTime
void getTime(struct Time * theTime)
Description
Reads the current time in from the RTCShield and places it in the Time structure theTime.
Arguments
- struct Time * theTime - a pointer to a Time structure that will hold the time as read from the clock.
Return Value
None
Example
RTCShield clock;
struct Time time;
clock.getTime( (struct Time *) &time );
if (time.hours < 12) {
Serial.println("Good Morning");
}
See Also
setTime()
void setTime(struct Time * theTime)
Description
Set the clock's to the date and time specified in the Time structure in theTime. All values in the clock will be set in one operation. To set individual fields, read the time in using getTime(), modify the time and write it back out again.
Arguments
- struct Time * theTime - A pointer to a Time structure that will be used to initialize the DS1307's time registers.
Return Value
None
Example
struct Time myBirthday = { 0,20,14,0,5,23,8,2012};
RTCShield clock;
clock.setTime((struct Time *)&myBirthday);
See Also
setSQW()
void setSQW(sqw_parm parm);
Description
Configures the Square Wave pin on the DS1307 to be LOW, HIGH, or to generate a square wave at 1Hz, 4096Hz, 8192Hz or 32768Hz. See Square Wave for a detailed description on how to use this pin.
Arguments
- sqw_parm parm - A constant representing the desired mode for the SQW pin. Valid modes are:
- RTC_SQW_LOW - SWQ is held LOW
- RTC_SQW_HIGH - SQW is held HIGH
- RTC_SQW_1 - SQW oscillates at 1Hz
- RTC_SQW_4K - SQW oscillates at 4KHz
- RTC_SQW_8K - SQW oscillates at 8KHz
- RTC_SQW_32K - SQW oscillates at 32KHz
Return Value
None
Example
RTCShield clock; clock.setSQW(RTC_SQW_1); // 1Hz square wave
See Also
getSWQ()
sqw_parm getSQW()
Description
Returns the active SQW configuration from the clock.
Arguments
None
Return Value
Returns the current value of the SQW register. See setRTC() for a list of possible values.
Example
RTCShield clock;
if(clock.getSQW() != RTC_SQW_1) {
clock.setSQW() =
}
See Also
readNVRAM()
byte readNVRAM(byte offset) int readNVRAM(byte offset, byte len, byte *buffer)
Description
In the first form readNVRAM() returns the value stored at offset in the RTCShield's Non-volatile RAM. In the second form it attempts to copy len bytes in to buffer starting at offset, and returns the number of bytes actually copied. The underlying Wire library limits the maximum number of bytes that can be copied at once to 32 bytes.
Arguments
- byte offset - Read data starting at this offset in NVRAM. Valid addresses are 0 - 55.
- byte len - The number of bytes to copy. This should be a number between 1 and 32
- byte * buffer - A pointer to the buffer that the NVRAM will be copied to.
Return Value
Returns the number of bytes actually read from NVRAM. This may be smaller than the number requested.
Example
RTCShield clock;
byte buffer[8];
int count = clock.readNVRAM(4 , 8, (byte*)&buffer );
if (count != 8) {
Serial.print("ERROR: Short Read");
}
See Also
writeNVRAM()
void writeNVRAM(byte offset, byte data) int writeNVRAM(byte offset, byte len, byte *buffer);
Description
In the first form writeNVRAM() writes the single byte data out to the RTC at the byte specified by offset. In the second form it requests len bytes from the RTC and stores them at the address specified by buffer, returning the actual number of bytes written.
Arguments
- byte offset - A value in the range of 0-55, specifying the address in NVRAM.
- byte data - The value to be written to RAM
- byte len - The number of bytes to be written. The underlying Wire library restricts this value to a maximum of 32 bytes.
- byte * buffer - A pointer to a buffer large enough to contain len bytes.
Return Value
The first form of writeNVRAM() returns no value.
The second form of writeNVRAM returns the number of bytes actually written.
TODO
rename getCH. also make it return 1 or 0 instead of true or false. fix get/set 12 hour to preserve the time and keep the clock values sane. rename Time.ap to make it more clear. maybe Time.pm? actually test all of the code in the examples. Add errors that can be returned by each method fix NVRAM functions so that maximum is BUFFER_LENGTH (Wire.h) instead of 32 writeNVRAM(offset,data) - does the error reporting logic of this make sense? should we be using a return value? offsets should be unsigned len should be unsigned
