Skip to content

Commit 3a1d86f

Browse files
JChristensenJChristensen
committed
Finish doc for 2.0.0.
1 parent f993c7e commit 3a1d86f

File tree

4 files changed

+176
-215
lines changed

4 files changed

+176
-215
lines changed

‎README.md‎

Lines changed: 166 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,32 @@
22
https://github.com/JChristensen/MCP79412RTC
33
README file
44
Jack Christensen
5-
Sep 2012
5+
May 2025
66

7-
## Introduction
8-
**MCP79412RTC** is an Arduino library that supports the Microchip MCP7941x Real-Time Clock/Calendar chips. This library is intended to be used with [PJRC's Arduino Time library](https://github.com/PaulStoffregen/Time).
7+
## License
8+
Arduino MCP79412 RTC Library Copyright (C) 2012-2025 byJack Christensen GNU GPL v3.0
9+
10+
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License v3.0 as published by the Free Software Foundation.
11+
12+
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
913

10-
The **MCP79412RTC** library is a drop-in replacement for the (older) **DS1307RTC** library by Michael Margolis that is supplied with the [Arduino Time library](https://www.arduino.cc/playground/Code/Time) (but not for [PJRC's newer version of the DS1307RTC library](https://www.pjrc.com/teensy/td_libs_DS1307RTC.html)). To change from using a DS1307 RTC to an MCP7941x RTC, it is only necessary to use `#include <MCP79412RTC.h>` instead of `#include <DS1307RTC.h>`.
14+
You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/gpl.html>
1115

12-
The **MCP79412RTC** library also implements functions to support the additional features of the MCP7941x RTC.
16+
## Important note: Library v2.0.0
17+
The 2.0.0 version of the library has some significant changes and is not completely backwards compatible with earlier versions. These changes provide a more consistent API and reduce the possibility of name collisions. While sketches using this library will likely require changes as a result, these should be mostly straightforward.
18+
19+
- The library no longer defines an `MCP79412RTC` object, therefore each sketch needs to define one. (Previous versions of the library defined an `MCP79412RTC` object named `RTC`, although only for AVR architecture. Consider using a name other than `RTC` as this can cause a name collision on some architectures.)
20+
- The constructor no longer has the capability to initialize the I2C bus and no longer accepts an optional parameter. Therefore, the sketch needs to call `MCP79412RTC::begin()` in the `setup()` function or elsewhere as appropriate.
21+
- To reduce the possibility of name collisions, the enumerations as well as register addresses, etc. are now defined in the header file within the `MCP79412RTC` class. Therefore, when using any of these names, it will be necessary to include the `MCP79412RTC` scope, e.g. `myRTC.alarm(MCP79412RTC::ALARM_1);`
22+
- The example sketches and documentation have been updated to reflect these changes.
23+
24+
## Introduction
25+
**MCP79412RTC** is an Arduino library that supports the Microchip MCP7941x Real-Time Clock/Calendar chips. This library is intended to be used with [PJRC's Arduino Time library](https://github.com/PaulStoffregen/Time).
1326

1427
**For more information on the MCP79412, see:**
28+
The [Microchip MCP79412 Product Page](https://www.microchip.com/en-us/product/MCP79412) for specs, datasheet, etc.
1529
[My Blog Post](http://goo.gl/MkBnjR), summarizing the features and advantages of the MCP79412
1630
[My Power Outage Logger Project](http://goo.gl/RfM5os), an Arduino-based project featuring the MCP79412
17-
The [Microchip MCP79412 Product Page](http://goo.gl/SHfKe0) for specs, datasheet, etc.
1831

1932
## Examples
2033
The following example sketches are included with the **MCP79412RTC** library:
@@ -23,16 +36,74 @@ The following example sketches are included with the **MCP79412RTC** library:
2336
- **rtcSet2:** Similar to **rtcSet1**, a different way to hard-code the date and time.
2437
- **rtcSet3:** Set the RTC to the sketch compile date and time.
2538
- **SetSerial:** Set the RTC's date, time, and calibration register from the Arduino serial monitor.
26-
- **rtcSetSerial:** Set the RTC via input from the Arduino serial monitor.
27-
- **TimeRTC:** Same as the example of the same name provided with the **Time** library, demonstrating the interchangeability of the **MCP79412RTC** library with the **DS1307RTC** library.
39+
- **TimeRTC:** Similar to the example of the same name provided with the **Time** library.
2840
- **PowerOutageLogger:** A comprehensive example that implements a power failure logger using the MCP79412's ability to capture power down and power up times. Power failure events are logged to the MCP79412's SRAM. Output is to the Arduino serial monitor.
2941
- **tiny79412_KnockBang:** Demonstrates interfacing an ATtiny45/85 to the MCP79412.
3042

31-
## Usage notes
32-
Similar to the **DS1307RTC** library, the **MCP79412RTC** library instantiates an RTC object; the user does not need to do this.
43+
## Enumerations
44+
### ALARM_TYPES_t
45+
##### Description
46+
Symbolic names used with the `enableAlarm()` function described below.
47+
##### Values
48+
- ALM_MATCH_SECONDS -- Triggers alarm when the seconds in the RTC time keeping register match the seconds in the alarm register.
49+
- ALM_MATCH_MINUTES -- Triggers when RTC time minutes match alarm minutes.
50+
- ALM_MATCH_HOURS -- Triggers when RTC time hours match alarm hours.
51+
- ALM_MATCH_DAY -- Triggers when day of the week matches. (Triggers at midnight.)
52+
- ALM_MATCH_DATE -- Triggers when date matches. (Triggers at midnight.)
53+
- ALM_MATCH_DATETIME -- Triggers when seconds, minutes, hours, day of week, date and month all match.
54+
- ALM_DISABLE -- Disables the alarm.
55+
56+
### ALARM_NBR_t
57+
##### Description
58+
Symbolic names used with alarm functions.
59+
##### Values
60+
- ALARM_0
61+
- ALARM_1
3362

34-
## Functions for setting and reading the time
63+
### SQWAVE_FREQS_t
64+
##### Description
65+
Symbolic names used with the squareWave() function (described below).
66+
##### Values
67+
- SQWAVE_1_HZ,
68+
- SQWAVE_4096_HZ,
69+
- SQWAVE_8192_HZ,
70+
- SQWAVE_32768_HZ,
71+
- SQWAVE_NONE
72+
73+
## Constructor
74+
### MCP79412RTC()
75+
##### Description
76+
Instantiates an `MCP79412RTC` object.
77+
##### Syntax
78+
`MCP79412RTC myRTC;`
79+
##### Parameters
80+
None.
81+
##### Returns
82+
None.
83+
##### Example
84+
```c++
85+
MCP79412RTC myRTC;
86+
```
87+
88+
## Initialization function
89+
### begin()
90+
##### Description
91+
Initializes the I2C bus. Calls `Wire.begin()`.
92+
##### Syntax
93+
`begin();`
94+
##### Parameters
95+
None.
96+
##### Returns
97+
None.
98+
##### Example
99+
```c++
100+
MCP79412RTC myRTC;
101+
void setup() {
102+
myRTC.begin();
103+
}
104+
```
35105

106+
## Functions for setting and reading the time
36107
### get()
37108
##### Description
38109
Reads the current date and time from the RTC and returns it as a *time_t* value. Returns zero if an I2C error occurs (RTC not present, etc.).
@@ -124,6 +195,89 @@ else
124195
//do something else
125196
```
126197

198+
## Alarm functions
199+
The MCP79412 RTC has two alarms (Alarm-0 and Alarm-1) that can be used separately or simultaneously. When an alarm is triggered, a flag is set in the RTC that can be detected with the `alarm()` function below. Optionally, the RTC's Multi-Function Pin (MFP) can be driven to either a low or high logic level when an alarm is triggered. When using the MFP with both alarms, be sure to read the comments on the `alarmPolarity()` function below.
200+
201+
### setAlarm(byte alarmNumber, time_t alarmTime)
202+
##### Description
203+
Sets an alarm date and time. This *sets* the alarm registers only, it does not *enable* the alarm, this is done using the `enableAlarm()` function. *alarmNumber* is 0 or 1, but is ruthlessly masked to ensure a valid value. Note that depending on the alarm type chosen (see `enableAlarm()` below), only selected date or time parts may act as alarm critera. Nevertheless, valid values should be specified in the *alarmTime* parameter.
204+
##### Syntax
205+
`RTC.setAlarm(alarmNumber, alarmTime);`
206+
##### Parameters
207+
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
208+
**alarmTime:** Date and time to set the alarm to *(time_t)*
209+
##### Returns
210+
None.
211+
##### Example
212+
```c++
213+
//set alarm-1 for 30 seconds after midnight on 21Dec2012
214+
tmElements_t tm;
215+
tm.Hour = 0;
216+
tm.Minute = 0;
217+
tm.Second = 30;
218+
tm.Year = CalendarYrToTm(2012);
219+
tm.Month = 12;
220+
tm.Day = 21;
221+
RTC.setAlarm(ALARM_1, makeTime(tm));
222+
```
223+
224+
### enableAlarm(byte alarmNumber, byte alarmType)
225+
##### Description
226+
Enable or disable the given alarm.
227+
##### Syntax
228+
`RTC.enableAlarm(alarmNumber, alarmType);`
229+
##### Parameters
230+
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
231+
**alarmType:** One of the following: ALM_MATCH_SECONDS, ALM_MATCH_MINUTES, ALM_MATCH_HOURS, ALM_MATCH_DAY, ALM_MATCH_DATE, ALM_MATCH_DATETIME, ALM_DISABLE. (ALM_MATCH_DATETIME triggers the alarm when seconds, minutes, hours, day, date and month *all* match.)
232+
##### Returns
233+
None.
234+
##### Example
235+
```c++
236+
//disable alarm-0
237+
RTC.enableAlarm(ALARM_0, ALM_DISABLE);
238+
239+
//enable alarm-1 to trigger when the minutes match.
240+
//assuming alarm-1 is set as in the example above, this will trigger the
241+
//alarm every hour, on the hour (minutes=0).
242+
RTC.enableAlarm(ALARM_1, ALM_MATCH_MINUTES);
243+
244+
//enable alarm-1 to trigger when the seconds match.
245+
//assuming alarm-1 is set as in the example above, this will trigger the
246+
//alarm once a minute, at 30 seconds past the minute.
247+
RTC.enableAlarm(ALARM_1, ALM_MATCH_SECONDS);
248+
```
249+
250+
### alarm(byte alarmNumber)
251+
##### Description
252+
Tests whether the given alarm has been triggered, and returns a corresponding boolean value. Clears the alarm flag to ensure that the next trigger event can be trapped.
253+
##### Syntax
254+
`RTC.alarm(byte alarmNumber);`
255+
##### Parameters
256+
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
257+
##### Returns
258+
True if the alarm was triggered, else false *(boolean)*
259+
##### Example
260+
```c++
261+
if ( RTC.alarm(ALARM_0) )
262+
//alarm-0 has triggered
263+
else
264+
//alarm-0 has not triggered
265+
```
266+
267+
### alarmPolarity(boolean polarity)
268+
##### Description
269+
Specifies the logic level on the Multi-Function Pin (MFP) when an alarm is triggered. The default is LOW. When both alarms are active, the two are ORed together to determine the level of the MFP. With alarm polarity set to LOW (the default), this causes the MFP to go low only when BOTH alarms are triggered. With alarm polarity set to HIGH, the MFP will go high when EITHER alarm is triggered. Note that the state of the MFP is independent of the RTC's (so-called) alarm "interrupt" flags, and that the `alarm()` function will indicate when an alarm is triggered regardless of the polarity.
270+
##### Syntax
271+
`RTC.alarmPolarity(boolean polarity);`
272+
##### Parameters
273+
**polarity:** HIGH or LOW *(boolean)*
274+
##### Returns
275+
None.
276+
##### Example
277+
```c++
278+
RTC.alarmPolarity(HIGH); //drives MFP high when an alarm is triggered
279+
```
280+
127281
## Functions for reading and writing static RAM (SRAM)
128282
The MCP79412 RTC has 64 bytes of battery-backed SRAM that can be read and written with the following functions using addresses between 0 and 63. Addresses passed to these functions are constrained to the valid range by an AND function.
129283

@@ -192,7 +346,7 @@ No function value returned. Bytes read from SRAM are returned to the **values**
192346
byte buf[8];
193347
RTC.sramRead(56, buf, 8);
194348
```
195-
349+
196350
## Functions for Reading and writing EEPROM
197351
The MCP79412 RTC has 128 bytes of non-volatile EEPROM that can be read and written with the following functions using addresses between 0 and 127. Addresses passed to these functions are constrained to the valid range by an AND function.
198352

@@ -264,91 +418,7 @@ byte buf[8];
264418
RTC.eepromRead(120, buf, 8);
265419
```
266420

267-
## Alarm functions
268-
The MCP79412 RTC has two alarms (Alarm-0 and Alarm-1) that can be used separately or simultaneously. When an alarm is triggered, a flag is set in the RTC that can be detected with the `alarm()` function below. Optionally, the RTC's Multi-Function Pin (MFP) can be driven to either a low or high logic level when an alarm is triggered. When using the MFP with both alarms, be sure to read the comments on the `alarmPolarity()` function below.
269-
270-
### setAlarm(byte alarmNumber, time_t alarmTime)
271-
##### Description
272-
Sets an alarm date and time. This *sets* the alarm registers only, it does not *enable* the alarm, this is done using the `enableAlarm()` function. *alarmNumber* is 0 or 1, but is ruthlessly masked to ensure a valid value. Note that depending on the alarm type chosen (see `enableAlarm()` below), only selected date or time parts may act as alarm critera. Nevertheless, valid values should be specified in the *alarmTime* parameter.
273-
##### Syntax
274-
`RTC.setAlarm(alarmNumber, alarmTime);`
275-
##### Parameters
276-
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
277-
**alarmTime:** Date and time to set the alarm to *(time_t)*
278-
##### Returns
279-
None.
280-
##### Example
281-
```c++
282-
//set alarm-1 for 30 seconds after midnight on 21Dec2012
283-
tmElements_t tm;
284-
tm.Hour = 0;
285-
tm.Minute = 0;
286-
tm.Second = 30;
287-
tm.Year = CalendarYrToTm(2012);
288-
tm.Month = 12;
289-
tm.Day = 21;
290-
RTC.setAlarm(ALARM_1, makeTime(tm));
291-
```
292-
293-
### enableAlarm(byte alarmNumber, byte alarmType)
294-
##### Description
295-
Enable or disable the given alarm.
296-
##### Syntax
297-
`RTC.enableAlarm(alarmNumber, alarmType);`
298-
##### Parameters
299-
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
300-
**alarmType:** One of the following: ALM_MATCH_SECONDS, ALM_MATCH_MINUTES, ALM_MATCH_HOURS, ALM_MATCH_DAY, ALM_MATCH_DATE, ALM_MATCH_DATETIME, ALM_DISABLE. (ALM_MATCH_DATETIME triggers the alarm when seconds, minutes, hours, day, date and month *all* match.)
301-
##### Returns
302-
None.
303-
##### Example
304-
```c++
305-
//disable alarm-0
306-
RTC.enableAlarm(ALARM_0, ALM_DISABLE);
307-
308-
//enable alarm-1 to trigger when the minutes match.
309-
//assuming alarm-1 is set as in the example above, this will trigger the
310-
//alarm every hour, on the hour (minutes=0).
311-
RTC.enableAlarm(ALARM_1, ALM_MATCH_MINUTES);
312-
313-
//enable alarm-1 to trigger when the seconds match.
314-
//assuming alarm-1 is set as in the example above, this will trigger the
315-
//alarm once a minute, at 30 seconds past the minute.
316-
RTC.enableAlarm(ALARM_1, ALM_MATCH_SECONDS);
317-
```
318-
319-
### alarm(byte alarmNumber)
320-
##### Description
321-
Tests whether the given alarm has been triggered, and returns a corresponding boolean value. Clears the alarm flag to ensure that the next trigger event can be trapped.
322-
##### Syntax
323-
`RTC.alarm(byte alarmNumber);`
324-
##### Parameters
325-
**alarmNumber:** ALARM_0 or ALARM_1 *(byte)*
326-
##### Returns
327-
True if the alarm was triggered, else false *(boolean)*
328-
##### Example
329-
```c++
330-
if ( RTC.alarm(ALARM_0) )
331-
//alarm-0 has triggered
332-
else
333-
//alarm-0 has not triggered
334-
```
335-
336-
### alarmPolarity(boolean polarity)
337-
##### Description
338-
Specifies the logic level on the Multi-Function Pin (MFP) when an alarm is triggered. The default is LOW. When both alarms are active, the two are ORed together to determine the level of the MFP. With alarm polarity set to LOW (the default), this causes the MFP to go low only when BOTH alarms are triggered. With alarm polarity set to HIGH, the MFP will go high when EITHER alarm is triggered. Note that the state of the MFP is independent of the RTC's (so-called) alarm "interrupt" flags, and that the `alarm()` function will indicate when an alarm is triggered regardless of the polarity.
339-
##### Syntax
340-
`RTC.alarmPolarity(boolean polarity);`
341-
##### Parameters
342-
**polarity:** HIGH or LOW *(boolean)*
343-
##### Returns
344-
None.
345-
##### Example
346-
```c++
347-
RTC.alarmPolarity(HIGH); //drives MFP high when an alarm is triggered
348-
```
349-
350421
## Calibration, power failure, and other functions
351-
352422
### calibWrite(int value)
353423
##### Description
354424
Writes the given value to the RTC calibration register. This is an adjustment factor in PPM (approximately), and must be between -127 and 127. Negative numbers cause the RTC to run faster, positive numbers cause it to run slower.

0 commit comments

Comments
 (0)