Colin Grant
5011b2d520
3f379ab (PR #166) added connection verification for the PCF8523 and DS1307 matching that of the DS3231. For each RTC, if begin() returns false, the intended behavior is to print a message, "Couldn't find RTC" to an attached serial terminal and then terminate.
This change is a follow-on that corrects two issues which were not seen as long as begin() always returned true, across all RTClib examples:
1) The method of termination in place was an endless loop: `while(1)`
However, as pointed out in PR #168, the behavior of such a loop is undefined. (See PR for interesting reading!) The `abort()` command effectively starts an endless loop, but without any side effects. It also makes clear to new users what the program is doing. H/T to contributor @edgar-bonet for this advice.
2) The message text "Couldn't find RTC" was not guaranteed to actually print on screen before the processor entered the endless loop.
This has to do with the way serial data is actually buffered and transfered down the line. On some boards, serial data is processed using interrupts. On others, such as the Feather nRF52840 which uses the TinyUSB stack, interrupts are not used at all, and serial processing waits for the CPU to become available. Whatever the case, `Serial.flush()` allows serial processing to finish before terminating with the endless loop.
An alternate way of handling 1 and 2, recommended by the TinyUSB author, is to enter the endless loop immediately, but call `yield()` inside to instruct the processor to go ahead and handle any latent requests that come in. This also makes the loop have defined behavior. E.g.:
```
if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1) {
yield(); // delay(1) would also suffice
}
}
```
A fuller discussion of termination methods can be viewed in PR #166.RTClib 
This is a fork of JeeLab's fantastic real time clock library for Arduino.
Works great with Adafruit RTC breakouts:
Please note that dayOfTheWeek() ranges from 0 to 6 inclusive with 0 being 'Sunday'.
Compatibility
| MCU | Tested Works | Doesn't Work | Not Tested | Notes |
|---|---|---|---|---|
| Atmega328 @ 16MHz | X | |||
| Atmega328 @ 12MHz | X | |||
| Atmega32u4 @ 16MHz | X | Use SDA/SCL on pins D3 & D2 | ||
| Atmega32u4 @ 8MHz | X | Use SDA/SCL on pins D3 & D2 | ||
| ESP8266 | X | SDA/SCL default to pins 4 & 5 but any two pins can be assigned as SDA/SCL using Wire.begin(SDA,SCL) | ||
| Atmega2560 @ 16MHz | X | Use SDA/SCL on Pins 20 & 21 | ||
| ATSAM3X8E | X | Use SDA1 and SCL1 | ||
| ATSAM21D | X | |||
| ATtiny85 @ 16MHz | X | |||
| ATtiny85 @ 8MHz | X | |||
| Intel Curie @ 32MHz | X | |||
| STM32F2 | X |
- ATmega328 @ 16MHz : Arduino UNO, Adafruit Pro Trinket 5V, Adafruit Metro 328, Adafruit Metro Mini
- ATmega328 @ 12MHz : Adafruit Pro Trinket 3V
- ATmega32u4 @ 16MHz : Arduino Leonardo, Arduino Micro, Arduino Yun, Teensy 2.0
- ATmega32u4 @ 8MHz : Adafruit Flora, Bluefruit Micro
- ESP8266 : Adafruit Huzzah
- ATmega2560 @ 16MHz : Arduino Mega
- ATSAM3X8E : Arduino Due
- ATSAM21D : Arduino Zero, M0 Pro
- ATtiny85 @ 16MHz : Adafruit Trinket 5V
- ATtiny85 @ 8MHz : Adafruit Gemma, Arduino Gemma, Adafruit Trinket 3V
Adafruit invests time and resources providing this open source code, please support Adafruit and open-source hardware by purchasing products from Adafruit!
Dependencies
Contributing
Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.
Documentation and doxygen
For the detailed API documentation, see https://adafruit.github.io/RTClib/html/index.html Documentation is produced by doxygen. Contributions should include documentation for any new code added.
Some examples of how to use doxygen can be found in these guide pages:
https://learn.adafruit.com/the-well-automated-arduino-library/doxygen
https://learn.adafruit.com/the-well-automated-arduino-library/doxygen-tips
Written by JeeLabs MIT license, check license.txt for more information All text above must be included in any redistribution
To install, use the Arduino Library Manager and search for "RTClib" and install the library.