Skip to content

Commit

Permalink
Ensure serial message printed and proper termination when RTC not found.
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
colindgrant committed May 19, 2020
1 parent bbea4c8 commit 5011b2d
Show file tree
Hide file tree
Showing 8 changed files with 19 additions and 10 deletions.
3 changes: 2 additions & 1 deletion examples/ds1307/ds1307.ino
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1);
Serial.flush();
abort();
}

if (! rtc.isrunning()) {
Expand Down
3 changes: 2 additions & 1 deletion examples/ds1307SqwPin/ds1307SqwPin.ino
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1);
Serial.flush();
abort();
}

print_mode();
Expand Down
6 changes: 5 additions & 1 deletion examples/ds1307nvram/ds1307nvram.ino
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,11 @@ void setup () {
while (!Serial); // wait for serial port to connect. Needed for native USB
#endif

rtc.begin();
if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
Serial.flush();
abort();
}

// Print old RAM contents on startup.
Serial.println("Current NVRAM values:");
Expand Down
3 changes: 2 additions & 1 deletion examples/ds3231/ds3231.ino
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1);
Serial.flush();
abort();
}

if (rtc.lostPower()) {
Expand Down
4 changes: 2 additions & 2 deletions examples/pcf8523/pcf8523.ino
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
Serial.flush(); // ensure above text prints with nRF52 native USB Serial
while (1);
Serial.flush();
abort();
}

if (! rtc.initialized() || rtc.lostPower()) {
Expand Down
4 changes: 2 additions & 2 deletions examples/pcf8523Countdown/pcf8523Countdown.ino
Original file line number Diff line number Diff line change
Expand Up @@ -41,8 +41,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
Serial.flush(); // ensure above text prints with nRF52 native USB Serial
while (1);
Serial.flush();
abort();
}

pinMode(LED_BUILTIN, OUTPUT);
Expand Down
3 changes: 2 additions & 1 deletion examples/timestamp/timestamp.ino
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1);
Serial.flush();
abort();
}

if (! rtc.isrunning()) {
Expand Down
3 changes: 2 additions & 1 deletion examples/toString/toString.ino
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ void setup () {

if (! rtc.begin()) {
Serial.println("Couldn't find RTC");
while (1);
Serial.flush();
abort();
}

if (! rtc.isrunning()) {
Expand Down

0 comments on commit 5011b2d

Please sign in to comment.