RTC countdown timer
What this example shows
Use the countdown timer of the onboard real-time clock (RTC). The sketch sets a 15 second timer on the 1 Hz timer clock, keeps showing the time and date, and prints Timer! when the countdown ends.
The sketch polls the timer flag. It also sets GPIO39, which its comments name as the RTC interrupt pin, as an input with the pull-up resistor enabled. Because the sketch calls disableTimer() after the first event, the timer fires once. Remove that line if you want it to repeat, as the sketch comment says.
Example code
In the Arduino IDE, choose the Inkplate 10 board under Tools, Board, Inkplate Boards before you upload.
// Next 3 lines are a precaution, you can ignore those, and the example would also work without them
#if !defined(ARDUINO_INKPLATE10) && !defined(ARDUINO_INKPLATE10V2)
#error "Wrong board selection for this example, please select e-radionica Inkplate10 or Soldered Inkplate10 in the boards menu."
#endif
#include "Inkplate.h" // Include Inkplate library to the sketch
Inkplate display(INKPLATE_1BIT); // Create an object on Inkplate library and also set library into 1-bit mode (BW)
// Set clock
uint8_t hour = 12;
uint8_t minutes = 50;
uint8_t seconds = 30;
// Set date and weekday (NOTE: In weekdays 0 means Sunday, 1 means Monday, ...)
uint8_t weekday = 4;
uint8_t day = 11;
uint8_t month = 11;
uint16_t year = 2021;
// Set up a 15 seconds timer
int countdown_time = 15;
void setup()
{
display.begin(); // Init Inkplate library (you should call this function ONLY ONCE)
display.clearDisplay(); // Clear frame buffer of display
display.display(); // Put clear image on display
display.setTextSize(5); // Set text to be 5 times bigger than classic 5x7 px text
pinMode(39, INPUT_PULLUP); // Set RTC INT pin on ESP32 GPIO39 as input with pullup resistor enabled
display.rtc.setTime(hour, minutes, seconds); // Send time to RTC
display.rtc.setDate(weekday, day, month, year); // Send date to RTC
// Set up a timer
/* source_clock
* RTC::TIMER_CLOCK_4096HZ -> clk = 4096Hz -> min timer = 244uS -> MAX timer = 62.256mS
* RTC::TIMER_CLOCK_64HZ -> clk = 64Hz -> min timer = 15.625mS -> MAX timer = 3.984s
* RTC::TIMER_CLOCK_1HZ -> clk = 1Hz -> min timer = 1s -> MAX timer = 255s
* RTC::TIMER_CLOCK_1PER60HZ -> clk = 1/60Hz -> min timer = 60s -> MAX timer = 4h15min
* value
* coundowntime in seconds
* int_enable
* true = enable interrupt; false = disable interrupt
* int_pulse
* true = interrupt generate a pulse; false = interrupt follows timer flag
*/
display.rtc.timerSet(RTC::TIMER_CLOCK_1HZ, countdown_time, true, false);
}
// Variable that keeps count on how much screen has been partially updated
int n = 0;
void loop()
{
display.rtc.getRtcData(); // Get the time and date from RTC
seconds = display.rtc.getSecond(); // Store senconds in a variable
minutes = display.rtc.getMinute(); // Store minutes in a variable
hour = display.rtc.getHour(); // Store hours in a variable
day = display.rtc.getDay(); // Store day of month in a variable
weekday = display.rtc.getWeekday(); // Store day of week in a variable
month = display.rtc.getMonth(); // Store month in a variable
year = display.rtc.getYear(); // Store year in a variable
display.clearDisplay(); // Clear content in frame buffer
display.setCursor(100, 300); // Set position of the text
printTime(hour, minutes, seconds, day, weekday, month, year); // Print the time on screen
if (n > 9) // Check if you need to do full refresh or you can do partial update
{
display.display(true); // Do a full refresh
n = 0;
}
else
{
display.partialUpdate(false, true); // Do partial update and keep e-papr power supply on
n++; // Keep track on how many times screen has been partially updated
}
delay(700); // Delay between refreshes.
}
void printTime(uint8_t _hour, uint8_t _minutes, uint8_t _seconds, uint8_t _day, uint8_t _weekday, uint8_t _month,
uint16_t _year)
{
// Write time and date info on screen
char *wday[] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};
print2Digits(_hour);
display.print(':');
print2Digits(_minutes);
display.print(':');
print2Digits(_seconds);
display.print(' ');
display.print(wday[_weekday]);
display.print(", ");
print2Digits(_day);
display.print('/');
print2Digits(_month);
display.print('/');
display.print(_year, DEC);
if (display.rtc.checkTimerFlag()) // Check if timer event has occurred
{
display.rtc.clearTimerFlag(); // It's recommended to clear timer flag after timer has occurred
display.rtc.disableTimer(); // Disable timer if you want to make it one time only. Is you want to be repeatable, comment this line
display.setCursor(400, 400); // Set new position for cursor
display.print("Timer!");
}
}
void print2Digits(uint8_t _d)
{
if (_d < 10)
display.print('0');
display.print(_d, DEC);
}
Trimmed from Inkplate10_RTC_Timer.ino: the file header comment is left out. Adapted: the pinned file stores the year as a two-digit number (21), but setDate() expects the full year and subtracts 2000 from it, so this page uses 2021-style values and a uint16_t year. The rest of the code is unchanged. In the timer comment, the clock names are written RTC::TIMER_CLOCK_... to match the code below it.
Functions used
Inkplate(uint8_t mode)returns NoneCreates the Inkplate object and chooses the display mode. `INKPLATE_1BIT` is black and white and supports partial updates. `INKPLATE_3BIT` is grayscale and only supports full updates.
ReturnsConstructor; no return value.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | mode | Display mode: INKPLATE_1BIT (0) or INKPLATE_3BIT (1). |
display.begin()returns voidInitializes the library, the peripherals and the frame buffers. Call it once in `setup()`, later calls are ignored.
ReturnsNothing.
display.clearDisplay()returns voidClears the frame buffer in memory. It does not clear the panel itself, call `display()` afterwards to do that.
ReturnsNothing.
display.display(bool _leaveOn = 0)returns voidRefreshes the whole panel from the frame buffer (a full update).
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
bool | _leaveOn | If true, the e-paper supply stays on after the update, which saves time on the next update. Defaults to 0. |
display.setTextSize(uint8_t s)returns voidSets the text magnification. Size 1 is the classic 5x7 pixel font, size 5 is five times bigger. This comes from the Adafruit GFX base class that the library builds on.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | s | Text size multiplier. |
pinMode(uint8_t pin, uint8_t mode)returns voidArduino function that sets the mode of an ESP32 pin. The sketch sets GPIO 39, the RTC interrupt pin, as an input with the pull-up resistor enabled.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | pin | GPIO number. The sketch passes 39. |
uint8_t | mode | Pin mode. The sketch passes INPUT_PULLUP. |
display.rtc.setTime(uint8_t hour, uint8_t minute, uint8_t sec, bool isPM = false)returns voidWrites the time to the onboard real-time clock (RTC). It also marks the RTC as set, which `isSet()` reports.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | hour | Hour, in 24-hour form unless the RTC is switched to 12-hour mode. |
uint8_t | minute | Minute. |
uint8_t | sec | Second. |
bool | isPM | Only used in 12-hour mode. Defaults to false. |
display.rtc.setDate(uint8_t weekday, uint8_t day, uint8_t month, uint16_t yr)returns voidWrites the date to the RTC. It also marks the RTC as set.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
uint8_t | weekday | Day of the week, 0 to 6. The example sketches print 0 as Sunday and 1 as Monday. |
uint8_t | day | Day of the month. |
uint8_t | month | Month, 1 to 12. |
uint16_t | yr | Full year, for example 2022. The function subtracts 2000 before writing it to the RTC. |
display.rtc.timerSet(rtcCountdownSrcClock source_clock, uint8_t value, bool int_enable, bool int_pulse)returns voidConfigures and starts the RTC countdown timer.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
rtcCountdownSrcClock | source_clock | Timer clock: RTC::TIMER_CLOCK_4096HZ, RTC::TIMER_CLOCK_64HZ, RTC::TIMER_CLOCK_1HZ or RTC::TIMER_CLOCK_1PER60HZ. With the 1 Hz clock one tick is one second. |
uint8_t | value | Countdown value, in ticks of the chosen clock. |
bool | int_enable | true to generate an interrupt from the timer, false for none. |
bool | int_pulse | true for the interrupt to generate a pulse, false for it to follow the timer flag. |
display.rtc.getRtcData()returns voidReads the time and date from the RTC.
ReturnsNothing.
display.rtc.getSecond()returns uint8_tReturns the current second from the RTC.
ReturnsSeconds.
display.rtc.getMinute()returns uint8_tReturns the current minute from the RTC.
ReturnsMinutes.
display.rtc.getHour()returns uint8_tReturns the current hour from the RTC.
ReturnsHours.
display.rtc.getDay()returns uint8_tReturns the current day of the month from the RTC.
ReturnsDay of the month.
display.rtc.getWeekday()returns uint8_tReturns the current day of the week from the RTC.
ReturnsDay of the week, 0 to 6.
display.rtc.getMonth()returns uint8_tReturns the current month from the RTC.
ReturnsMonth, 1 to 12.
display.rtc.getYear()returns uint16_tReturns the current year from the RTC.
ReturnsFull year, for example `2022`.
display.setCursor(int16_t x, int16_t y)returns voidSets where the next printed text starts, in pixels from the top left corner. This comes from the Adafruit GFX base class that the library builds on.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
int16_t | x | X coordinate in pixels. |
int16_t | y | Y coordinate in pixels. |
display.partialUpdate(bool _forced = false, bool leaveOn = false)returns uint32_tUpdates only the parts of the screen that changed, without a full refresh. It works in 1-bit mode only, in 3-bit mode it does nothing and returns 0. A full refresh every 5 to 10 partial updates keeps the image quality good.
ReturnsNumber of pixels that changed from black to white, which are the ones that leave visible blur.
Parameters
| Type | Name | Description |
|---|---|---|
bool | _forced | For advanced use with deep sleep: forces a partial update. Defaults to false. |
bool | leaveOn | If true, the e-paper supply stays on after the update. Defaults to false. |
display.print(value, format)returns size_tPrints text, a character or a number at the cursor position, in the frame buffer. The display object builds on the Adafruit GFX base class, which extends the Arduino `Print` class, so it prints like `Serial` does. Call `display()` or `partialUpdate()` to show the result.
ReturnsNumber of bytes printed.
Parameters
| Type | Name | Description |
|---|---|---|
text, char or number | value | What to print. |
int | format | Optional. Number base for integers, for example DEC. |
display.rtc.checkTimerFlag()returns boolChecks whether the RTC timer flag is set, which means the countdown has finished.
Returns`true` if the timer flag is set.
display.rtc.clearTimerFlag()returns voidClears the RTC timer flag.
ReturnsNothing.
display.rtc.disableTimer()returns voidStops the RTC countdown timer, so it runs only once.
ReturnsNothing.
delay(unsigned long ms)returns voidArduino function that pauses the sketch.
ReturnsNothing.
Parameters
| Type | Name | Description |
|---|---|---|
unsigned long | ms | Time to wait, in milliseconds. |
What to expect
The time and date refresh about every 700 milliseconds. About 15 seconds after start, Timer! appears in the middle of the screen for one refresh. The sketch does not print to Serial.