:mod:`time`
===========
.. py:module:: time
.. autoapi-nested-parse::
time and timing related functions
The `time` module is a strict subset of the CPython `cpython:time` module. So, code
using `time` written in CircuitPython will work in CPython but not necessarily the other
way around.
.. raw:: html
Available on these boards
- 8086 Commander
- @sarfata shIRtty
- AITHinker ESP32-C3S_Kit
- ARAMCON Badge 2019
- ARAMCON2 Badge
- ATMegaZero ESP32-S2
- Adafruit BLM Badge
- Adafruit CLUE nRF52840 Express
- Adafruit Circuit Playground Bluefruit
- Adafruit Circuit Playground Express 4-H
- Adafruit CircuitPlayground Express
- Adafruit CircuitPlayground Express with Crickit libraries
- Adafruit CircuitPlayground Express with displayio
- Adafruit EdgeBadge
- Adafruit Feather Bluefruit Sense
- Adafruit Feather ESP32-S2 TFT
- Adafruit Feather ESP32S2
- Adafruit Feather M0 Adalogger
- Adafruit Feather M0 Basic
- Adafruit Feather M0 Express
- Adafruit Feather M0 Express with Crickit libraries
- Adafruit Feather M0 RFM69
- Adafruit Feather M0 RFM9x
- Adafruit Feather M4 CAN
- Adafruit Feather M4 Express
- Adafruit Feather MIMXRT1011
- Adafruit Feather RP2040
- Adafruit Feather STM32F405 Express
- 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 KB2040
- 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 NeoKey Trinkey M0
- Adafruit NeoPixel Trinkey M0
- Adafruit ProxLight Trinkey M0
- Adafruit PyGamer
- Adafruit PyPortal
- Adafruit PyPortal Pynt
- Adafruit PyPortal Titano
- Adafruit PyRuler
- Adafruit Pybadge
- Adafruit QT Py ESP32S2
- Adafruit QT Py M0
- Adafruit QT Py M0 Haxpress
- Adafruit QT Py RP2040
- Adafruit QT2040 Trinkey
- Adafruit Rotary Trinkey M0
- Adafruit Slide Trinkey M0
- 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 Nano RP2040
- 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
- Espruino Pico
- Espruino Wifi
- Feather ESP32S2 without PSRAM
- Feather MIMXRT1011
- Feather MIMXRT1062
- FeatherS2
- FeatherS2 Neo
- FeatherS2 PreRelease
- Fluff M0
- Fomu
- 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
- MEOWBIT
- 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
- MicroDev microC3
- MicroDev microS2
- Mini SAM M4
- NUCLEO STM32F746
- NUCLEO STM32F767
- NUCLEO STM32H743
- OPENMV-H7 R1
- Oak Dev Tech BREAD2040
- Oak Dev Tech PixelWing ESP32S2
- Open Hardware Summit 2020 Badge
- PCA10056 nRF52840-DK
- PCA10059 nRF52840 Dongle
- PCA10100 nRF52833 DK
- PYB LR Nano V2
- Particle Argon
- Particle Boron
- Particle Xenon
- PewPew 10.2
- PewPew 13
- PewPew M4
- 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
- PyboardV1_1
- RP2040 Stamp
- Raspberry Pi 4B
- Raspberry Pi Compute Module 4 IO Board
- Raspberry Pi Pico
- Raspberry Pi Zero 2W
- Robo HAT MM1 M4
- S2Mini
- S2Pico
- SAM E54 Xplained Pro
- SAM32v26
- SPRESENSE
- ST STM32F746G Discovery
- STM32F411E_DISCO
- STM32F412G_DISCO
- STM32F4_DISCO
- Saola 1 w/Wroom
- Saola 1 w/Wrover
- Seeeduino Wio Terminal
- Seeeduino XIAO
- Seeeduino XIAO KB
- 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 STM32 MicroMod Processor
- SparkFun Thing Plus - RP2040
- SparkFun Thing Plus - SAMD51
- Sprite_v2b
- StackRduino M0 PRO
- Swan R5
- TG-Boards' Datalore IP M4
- TG-Watch
- THUNDERPACK_v11
- THUNDERPACK_v12
- Targett Module Clip w/Wroom
- Targett Module Clip w/Wrover
- Teensy 4.0
- Teensy 4.1
- Teknikio Bluebird
- The Open Book Feather
- Thingz - Galaxia
- TinkeringTech ScoutMakes Azul
- TinyS2
- Trinket M0 Haxpress
- UARTLogger II
- WarmBit BluePixel nRF52840
- Winterbloom Big Honking Button
- Winterbloom Sol
- XinaBox CC03
- XinaBox CS11
- iMX RT 1020 EVK
- iMX RT 1060 EVK
- keithp.com snekboard
- micro:bit v2
- nanoESP32-S2 w/Wrover
- nanoESP32-S2 w/Wroom
- ndGarage[n°] Bit6: FeatherSnow-v2
- ndGarage[n°]Bit6:FeatherSnow
- nice!nano
- senseBox MCU
- stm32f411ce-blackpill
- stm32f411ce-blackpill-with-flash
- uChip
- uGame10
.. py:function:: monotonic() -> float
Returns an always increasing value of time with an unknown reference
point. Only use it to compare against other values from `time.monotonic()`.
On most boards, `time.monotonic()` converts a 64-bit millisecond tick counter
to a float. Floats on most boards are encoded in 30 bits internally, with
effectively 22 bits of precision. The float returned by `time.monotonic()` will
accurately represent time to millisecond precision only up to 2**22 milliseconds
(about 1.165 hours).
At that point it will start losing precision, and its value will change only
every second millisecond. At 2**23 milliseconds it will change every fourth
millisecond, and so forth.
If you need more consistent precision, use `time.monotonic_ns()`, or `supervisor.ticks_ms()`.
`time.monotonic_ns()` is not available on boards without long integer support.
`supervisor.ticks_ms()` uses intervals of a millisecond, but wraps around, and is not
CPython-compatible.
:return: the current monotonic time
:rtype: float
.. py:function:: sleep(seconds: float) -> None
Sleep for a given number of seconds.
:param float seconds: the time to sleep in fractional seconds
.. py:class:: struct_time(time_tuple: Sequence[int])
Structure used to capture a date and time. Can be constructed from a `struct_time`, `tuple`, `list`, or `namedtuple` with 9 elements.
:param Sequence time_tuple: Sequence of time info: ``(tm_year, tm_mon, tm_mday, tm_hour, tm_min, tm_sec, tm_wday, tm_yday, tm_isdst)``
* ``tm_year``: the year, 2017 for example
* ``tm_mon``: the month, range [1, 12]
* ``tm_mday``: the day of the month, range [1, 31]
* ``tm_hour``: the hour, range [0, 23]
* ``tm_min``: the minute, range [0, 59]
* ``tm_sec``: the second, range [0, 61]
* ``tm_wday``: the day of the week, range [0, 6], Monday is 0
* ``tm_yday``: the day of the year, range [1, 366], -1 indicates not known
* ``tm_isdst``: 1 when in daylight savings, 0 when not, -1 if unknown.
.. py:function:: time() -> int
Return the current time in seconds since since Jan 1, 1970.
:return: the current time
:rtype: int
.. py:function:: monotonic_ns() -> int
Return the time of the monotonic clock, which cannot go backward, in nanoseconds.
Not available on boards without long integer support.
:return: the current time
:rtype: int
.. py:function:: localtime(secs: int) -> struct_time
Convert a time expressed in seconds since Jan 1, 1970 to a struct_time in
local time. If secs is not provided or None, the current time as returned
by time() is used.
The earliest date for which it can generate a time is Jan 1, 2000.
:return: the current time
:rtype: time.struct_time
.. py:function:: mktime(t: struct_time) -> int
This is the inverse function of localtime(). Its argument is the
struct_time or full 9-tuple (since the dst flag is needed; use -1 as the
dst flag if it is unknown) which expresses the time in local time, not UTC.
The earliest date for which it can generate a time is Jan 1, 2000.
:return: seconds
:rtype: int