Difference between revisions of "User:Darqchild"

From Hackstrich
m (Description =)
 
(4 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
 
== using the shield==
 
== using the shield==
  
Line 141: Line 140:
 
None
 
None
 
==== Return Value ====
 
==== Return Value ====
Returns the current value of the SQW register.
+
Returns the current value of the SQW register. See [[setRTC()]] for a list of possible values.
 +
 
 
==== Example ====
 
==== Example ====
 
  RTCShield clock;
 
  RTCShield clock;
Line 174: Line 174:
 
* [[writeNVRAM()]]
 
* [[writeNVRAM()]]
  
int writeNVRAM(byte offset, byte len, byte *buffer);
+
=== 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 =
 
= TODO =
Line 183: Line 197:
 
Add errors that can be returned by each method
 
Add errors that can be returned by each method
 
fix NVRAM functions so that maximum is BUFFER_LENGTH (Wire.h) instead of 32
 
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

Latest revision as of 23:10, 25 February 2012

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