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.
Combines and extends #133 and #134 to additional examples, with some progress toward #132.
Each updated example sets the RTC to compile time after a power loss, as detected by the function specific to that RTC.
The same time-setting statements appear commented out later on for re-setting time on a running RTC, for whatever reason.
The PCF8523 initialized() state wasn't obvious to me. I found that when an unpowered PCF8523 is powered up it goes into standby mode, with Control_3 register set to a default value 0xE0, and in this state initialized() will return false. So it is closely associated with reporting whether power was lost. I made a brief comment to this effect in the member function.
The behavior is explained in section 8.5.1 of the datasheet https://www.nxp.com/docs/en/data-sheet/PCF8523.pdf
These changes tested on Feather M4 Express and Arduino Mega with DS1307 and PCF8523.
The DS3231 example has only cosmetic changes for consistency.
Fixes #156
Prompted by RTClib issue #137 for PCF8523.ino, but upon inspection, all of the RTClib examples that waited for a native USB connection were checking Serial status before it was actually started.
Further, some examples exempted ESP8266 from the Serial check, others did not have a check at all.
This change standardizes the Serial opening steps across all RTClib examples.
Tested on:
Feather M4 Express w/DS1307
Feather M4 Express w/PCF8523
Feather nRF52840 Sense w/DS1307
Feather nRF52840 Sense w/PCF8523
(in the case of the DS1307, 5v power was supplied, with SDA/SCL pulled up to Feather's 3v supply)
Unfortunately, I do not have an ESP8266 or DS3231 to test with. However, all examples connected to the Arduino IDE built-in Serial monitor without issue.
Useful reference: https://www.arduino.cc/reference/en/language/functions/communication/serial/ifserial
Resolves #137
caternuson
Colin Grant
Szymon Klause