rtc – Real Time Clock

The rtc module provides support for a Real Time Clock. You can access and manage the RTC using rtc.RTC. It also backs the time.time() and time.localtime() functions using the onboard RTC if present.

Available on these boards
  • 8086 Commander
  • @sarfata shIRtty
  • ARAMCON Badge 2019
  • ARAMCON2 Badge
  • ATMegaZero ESP32-S2
  • Adafruit CLUE nRF52840 Express
  • Adafruit Circuit Playground Bluefruit
  • Adafruit Circuit Playground Express 4-H
  • Adafruit CircuitPlayground Express
  • Adafruit CircuitPlayground Express with Crickit libraries
  • Adafruit EdgeBadge
  • Adafruit Feather Bluefruit Sense
  • Adafruit Feather M0 Adalogger
  • Adafruit Feather M0 Basic
  • Adafruit Feather M0 Express
  • Adafruit Feather M0 Express with Crickit libraries
  • Adafruit Feather M4 CAN
  • Adafruit Feather M4 Express
  • Adafruit Feather MIMXRT1011
  • Adafruit Feather RP2040
  • Adafruit Feather nRF52840 Express
  • Adafruit FunHouse
  • Adafruit Gemma M0
  • Adafruit Gemma M0 PyCon 2018
  • Adafruit Grand Central M4 Express
  • Adafruit Hallowing M4 Express
  • Adafruit ItsyBitsy M0 Express
  • Adafruit ItsyBitsy M4 Express
  • Adafruit ItsyBitsy RP2040
  • Adafruit ItsyBitsy nRF52840 Express
  • Adafruit LED Glasses Driver nRF52840
  • Adafruit Macropad RP2040
  • Adafruit MagTag
  • Adafruit Matrix Portal M4
  • Adafruit Metro ESP32S2
  • Adafruit Metro M0 Express
  • Adafruit Metro M4 Airlift Lite
  • Adafruit Metro M4 Express
  • Adafruit Metro nRF52840 Express
  • Adafruit Monster M4SK
  • Adafruit PyGamer
  • Adafruit PyPortal
  • Adafruit PyPortal Pynt
  • Adafruit PyPortal Titano
  • Adafruit PyRuler
  • Adafruit Pybadge
  • Adafruit QT Py M0
  • Adafruit QT Py M0 Haxpress
  • Adafruit QT Py RP2040
  • Adafruit QT2040 Trinkey
  • Adafruit Trellis M4 Express
  • Adafruit Trinket M0
  • AloriumTech Evo M51
  • Arduino MKR Zero
  • Arduino MKR1300
  • Arduino Nano 33 BLE
  • Arduino Nano 33 IoT
  • Arduino Nano RP2040 Connect
  • Arduino Zero
  • Artisense Reference Design RD00
  • AtelierDuMaker nRF52840 Breakout
  • BDMICRO VINA-D21
  • BDMICRO VINA-D51
  • BLE-SS dev board Multi Sensor
  • BastBLE
  • BastWiFi
  • BlueMicro840
  • CP Sapling M0
  • CP Sapling M0 w/ SPI Flash
  • CP32-M4
  • Capable Robot Programmable USB Hub
  • Cedar Grove StringCar M0 Express
  • Challenger NB RP2040 WiFi
  • Challenger RP2040 LTE
  • Challenger RP2040 WiFi
  • Circuit Playground Express Digi-Key PyCon 2019
  • CircuitBrains Basic
  • CircuitBrains Deluxe
  • CrumpS2
  • Cytron Maker Pi RP2040
  • DynOSSAT-EDU-EPS
  • DynOSSAT-EDU-OBC
  • DynaLoRa_USB
  • ESP 12k NodeMCU
  • Electronic Cats Bast Pro Mini M0
  • Electronic Cats CatWAN USBStick
  • Electronic Cats Hunter Cat NFC
  • Electronic Cats NFC Copy Cat
  • Electronut Labs Blip
  • Electronut Labs Papyr
  • EncoderPad RP2040
  • Escornabot Makech
  • Feather ESP32S2 without PSRAM
  • Feather MIMXRT1011
  • Feather MIMXRT1062
  • FeatherS2
  • FeatherS2 Neo
  • FeatherS2 PreRelease
  • Fluff M0
  • Franzininho WIFI w/Wroom
  • Franzininho WIFI w/Wrover
  • Gravitech Cucumber M
  • Gravitech Cucumber MS
  • Gravitech Cucumber R
  • Gravitech Cucumber RS
  • HMI-DevKit-1.1
  • Hacked Feather M0 Express with 8Mbyte SPI flash
  • HalloWing M0 Express
  • HiiBot BlueFi
  • IMXRT1010-EVK
  • IkigaiSense Vita nRF52840
  • J&J Studios datum-Distance
  • J&J Studios datum-IMU
  • J&J Studios datum-Light
  • J&J Studios datum-Weather
  • Kaluga 1
  • LILYGO TTGO T8 ESP32-S2 w/Display
  • LoC BeR M4 base board
  • MDBT50Q-DB-40
  • MDBT50Q-RX Dongle
  • MORPHEANS MorphESP-240
  • MakerDiary nRF52840 MDK
  • MakerDiary nRF52840 MDK USB Dongle
  • Makerdiary M60 Keyboard
  • Makerdiary Pitaya Go
  • Makerdiary nRF52840 M.2 Developer Kit
  • Melopero Shake RP2040
  • Meow Meow
  • Metro MIMXRT1011
  • Mini SAM M4
  • Oak Dev Tech BREAD2040
  • Oak Dev Tech PixelWing ESP32S2
  • Open Hardware Summit 2020 Badge
  • PCA10056 nRF52840-DK
  • PCA10059 nRF52840 Dongle
  • PCA10100 nRF52833 Dongle
  • Particle Argon
  • Particle Boron
  • Particle Xenon
  • PicoPlanet
  • Pimoroni Interstate 75
  • Pimoroni Keybow 2040
  • Pimoroni PGA2040
  • Pimoroni Pico LiPo (16MB)
  • Pimoroni Pico LiPo (4MB)
  • Pimoroni PicoSystem
  • Pimoroni Plasma 2040
  • Pimoroni Tiny 2040
  • PyCubedv04
  • PyCubedv04-MRAM
  • PyCubedv05
  • PyCubedv05-MRAM
  • PyKey60
  • Raspberry Pi Pico
  • Robo HAT MM1 M4
  • S2Mini
  • SAM E54 Xplained Pro
  • SAM32v26
  • SPRESENSE
  • Saola 1 w/Wroom
  • Saola 1 w/Wrover
  • Seeeduino Wio Terminal
  • Seeeduino XIAO
  • Serpente
  • Silicognition LLC M4-Shim
  • Simmel
  • SparkFun LUMIDrive
  • SparkFun MicroMod RP2040 Processor
  • SparkFun MicroMod SAMD51 Processor
  • SparkFun MicroMod nRF52840 Processor
  • SparkFun Pro Micro RP2040
  • SparkFun Pro nRF52840 Mini
  • SparkFun Qwiic Micro
  • SparkFun RedBoard Turbo
  • SparkFun SAMD21 Dev Breakout
  • SparkFun SAMD21 Mini Breakout
  • SparkFun Thing Plus - RP2040
  • SparkFun Thing Plus - SAMD51
  • Sprite_v2b
  • StackRduino M0 PRO
  • TG-Boards' Datalore IP M4
  • TG-Watch
  • Targett Module Clip w/Wroom
  • Targett Module Clip w/Wrover
  • Teensy 4.0
  • Teensy 4.1
  • Teknikio Bluebird
  • The Open Book Feather
  • TinkeringTech ScoutMakes Azul
  • TinyS2
  • Trinket M0 Haxpress
  • UARTLogger II
  • WarmBit BluePixel nRF52840
  • Winterbloom Sol
  • XinaBox CC03
  • iMX RT 1020 EVK
  • iMX RT 1060 EVK
  • keithp.com snekboard
  • micro:bit v2
  • microS2
  • nanoESP32-S2 w/Wrover
  • nanoESP32-S2 w/Wroom
  • ndGarage[n°] Bit6: FeatherSnow-v2
  • ndGarage[n°]Bit6:FeatherSnow
  • nice!nano
  • senseBox MCU
  • uChip

rtc.set_time_source(rtc: RTC)None

Sets the RTC time source used by time.localtime(). The default is rtc.RTC, but it’s useful to use this to override the time source for testing purposes. For example:

import rtc
import time

class RTC(object):
    @property
    def datetime(self):
        return time.struct_time((2018, 3, 17, 21, 1, 47, 0, 0, 0))

r = RTC()
rtc.set_time_source(r)
class rtc.RTC

Real Time Clock

This class represents the onboard Real Time Clock. It is a singleton and will always return the same instance.

datetime :time.struct_time

The current date and time of the RTC as a time.struct_time.

This must be set to the current date and time whenever the board loses power:

import rtc
import time

r = rtc.RTC()
r.datetime = time.struct_time((2019, 5, 29, 15, 14, 15, 0, -1, -1))

Once set, the RTC will automatically update this value as time passes. You can read this property to get a snapshot of the current time:

current_time = r.datetime
print(current_time)
# struct_time(tm_year=2019, tm_month=5, ...)
calibration :int

The RTC calibration value as an int.

A positive value speeds up the clock and a negative value slows it down. Range and value is hardware specific, but one step is often approximately 1 ppm:

import rtc
import time

r = rtc.RTC()
r.calibration = 1