System Time
Overview
System time represents the time and date in a computer system. It is usually measured in ticks from a certain starting point using the system clock.
In most systems, time is an essential part. QuecPython devices have several time-related features, including the Real-Time Clock (RTC) module, the utime module, the timer module, and the Network Identity and Time Zone (NITZ) module and Network Time Protocol (NTP) module for time synchronization.
The application of QuecPython device time functions is shown in the following diagram:
RTC
The Real-Time Clock (RTC) is an integrated circuit that can be used to establish and maintain system time in a computer system. It helps to obtain accurate real-time time and provides a precise time reference for electronic systems.
The RTC can provide independent timekeeping services that are not dependent on the operating system. It can maintain time accuracy even when the device is powered off.
QuecPython has a built-in RTC, which can be accessed using the machine module. For all the usages of the RTC, please refer to the RTC – Real Time Clock section. The following mainly introduces common operations and precautions.
QuecPython supports multiple module models, and the RTC time accuracy may vary depending on the module model. For applications that require high time accuracy, you can choose according to the hardware manual of each chip.
Configuring the RTC time and ALARM in QuecPython modules will erase the FLASH, so it is not recommended to call them frequently.
RTC Time Retrieval and Configuration
The following interface can be used to retrieve the RTC time and configure the RTC time according to the usage requirements.
from machine import RTC
# Initialize the RTC
rtc = RTC()
# Set the RTC time
rtc.datetime([2026, 3, 12, 1, 12, 12, 12, 0])
# Get the RTC time
rtc_time = rtc.datetime()
# Print the RTC time
print(rtc_time)
RTC ALARM
An alarm clock is designed to send a signal to people at specific times to remind them of other tasks.
In QuecPython, the alarm clock is designed to set the expiration time of the RTC and call the registered callback function when the time is up. This method can also be used for low-power wake-up. In low-power mode, the device can be woken up by the RTC.
EC600U series / EC200U series / EC600M series / EC800M series support automatic power-on. that is, once the module is turned off after setting the ALARM function, it will power on automatically when the ALARM time is reached. This feature is not supported on other platforms.
from machine import RTC
# Initialize the RTC
rtc = RTC()
# Define the wake-up callback function, which will be executed after waking up.
def callback(args):
print('RTC alarm')
# Register the wake-up callback function.
rtc.register_callback(callback)
# Set the alarm clock to wake up at a certain time.
rtc.set_alarm([2026, 7, 9, 5, 12, 30, 0, 0])
# Enable the alarm clock.
rtc.enable_alarm(1)
Utime
Time is a scale, which is a scalar in physical definition. With time, the sequence of events can be determined in terms of past-present-future (time points/moments), and the duration of events and the intervals between events can be measured (time intervals).
In QuecPython, the utime module provides functions for obtaining the current time and date (UTC time), measuring time intervals, and delays. utime is a software-level time. For all the usages of utime, please refer to the standard library utime - Time-related functions section.
System Tick
System tick usually refers to the CPU clock, which is the heart of the operating system and maintains the stability of the entire system. To implement time management in an operating system, it must rely on system ticks.
The system tick is a continuously increasing counter from the start of the system, and its time accuracy depends on the underlying clock of the hardware platform.
Principle
The system tick is generally generated by a crystal oscillator, which triggers an electrical signal at a precise and fixed time interval. Each tick represents the processing of data by the device. For example, if a crystal oscillator has a frequency of 12 MHz, it generates 12,000,000 pulses per second, so the time for each pulse is the clock cycle, which is 1/12 microseconds. It is also called the system clock cycle, which is the smallest and most basic time unit in a computer.
Application
System tick is the smallest time scale in the system, so it can be used to implement high-precision time management based on this interface.
Note: Due to the execution mechanism of Python, high-precision implementation cannot be achieved at the Python layer.
System Timer
Implement system timers in Python based on ticks.
from machine import Timer
# Timer timeout callback function.
def timer_callback(t):
print('timeout occurred!')
# Create a timer object.
t = Timer(Timer.Timer1)
# Start the timer and execute the timer callback every 1 second.
t.start(period=1000, mode=t.PERIODIC, callback=timer_callback)
Time Difference
The utime.tick interface can be used to measure the execution efficiency of code by calculating the time difference.
import utime
# Start timing the print statement.
start = utime.ticks_us()
# Execute the print statement.
print('Hello QuecPython!')
# End timing the print statement.
end = utime.ticks_us()
# Calculate the time difference in microseconds.
utime.ticks_diff(end, start)
UTC Time
Coodinated Universal Time (UTC) is a time measurement system based on the atomic time second. It aims to be as close as possible to the world time in terms of moments.
Although UTC is a globally unified time, the time of sunrise and sunset observed by people in different regions varies due to the rotation of the Earth. Therefore, the concept of local time is introduced based on UTC, which divides the Earth into 24 different time zones according to geographical locations. Therefore, local time is calculated by adding the time zone difference to UTC.
Local Time = UTC Time + Time Zone Difference. For example, Beijing is in the GMT+8 time zone, which is 8 hours ahead of UTC. If you want to obtain the local time in Beijing, you need to configure the time zone to the East 8th time zone.
QuecPython provides interfaces for local time and time zone configuration. The system is configured to the GMT+8 time zone by default. If you are in a different time zone, you can configure it to your local time zone according to your needs.
import utime
# Configure the GMT+8 time zone. This configuration may conflict with the time zone configuration in NTP time synchronization. We recommend using ntptime to configure the time zone.
utime.setTimeZone(8)
# Get local UTC time.
utime.localtime()
Time Synchronization
Time synchronization refers to the requirement that the absolute time between different points is the same. In our daily life, we may encounter situations where clocks need to be manually adjusted after running for a long time to prevent significant time deviation. Why does the time deviate after a device runs for a long time? How does it synchronize time on connected devices? How to handle situations where time consistency between devices is highly required?
Devices with time rely on local clock sources to control the passage of time. When they run for a long time, they may be affected by their own accuracy or the environment, resulting in deviation. In scenarios where time is highly required, it is necessary to synchronize the device time to ensure stability. The commonly used method is to synchronize the device time with the standard time server through NTP (such as the global NTP time server, pool.ntp.org) or a self-designed time server.
QuecPython provides NITZ and NTP time synchronization protocols to facilitate time synchronization operations for customers.
Base Station Time Synchronization
NITZ (Network Identity and Time Zone) is a mechanism used to automatically configure the local time and date. It requires support from the network operator. For cellular wireless devices, after accessing the network of the network operator, the network operator provides the mobile device with local date, time, time zone, daylight saving time offset, and other information.
The time provided may deviate significantly from the standard time.
NITZ does not provide an external interface. It is only an internal time synchronization mechanism and performs time synchronization during startup.
NTP Time Synchronization
NTP (Network Time Protocol) is a time synchronization protocol defined by RFC 1305. It is used for time synchronization between distributed time servers and clients. NTP uses UDP packets for transmission and uses UDP port number 123.
The packet format is shown in the following figure. Based on the content of the protocol packet, we can compare the reported time with the server time and calculate the link transmission time to calibrate the current device to keep it consistent with the server time. For all usages of NTP on QuecPython devices, refer to the ntptime - Network Time Protocolsection.
API Description
Time Synchronization
If the current time is inconsistent with the standard time or the time of your own server, NTP can be used for time calibration.
Note that for devices that require time calibration, consider whether the time used will cause confusion in program logic due to time calibration.
import ntptime
# Set the NTP server address. pool.ntp.org is a global NTP time server.
ntptime.sethost('pool.ntp.org')
# Synchronize with the NTP service time.
ntptime.settime()
Get UTC Time
In QuecPython system, the utime standard is based on the UTC time standard. You can directly obtain the local time. The default representation is the time in UTC+8. Adjust the time zone according to your needs.
import utime
# Get local UTC time.
utime.localtime()
Get RTC Time
RTC obtains the date and time format of year, month, day, hour, minute, and second, with a minimum accuracy of milliseconds.
from machine import RTC
# Create an RTC object.
rtc = RTC()
# Get the RTC time.
rtc.datetime()
Get Time Difference
Depending on the platform, the time difference can be calculated using ticks, and the time difference can be obtained at the microsecond level.
Use the utime.ticks_diff interface to calculate the time difference. After the tick value reaches the maximum, it will be reset, which may cause problems.
# Calculate the time difference for executing the print statement.
import utime
# Start time of executing the print statement.
start = utime.ticks_us()
# Execute the print statement.
print('Hello QuecPython !')
# End time of executing the print statement.
end = utime.ticks_us()
# Calculate the time difference in microseconds.
utime.ticks_diff(end, start)
Time Zone Synchronization
By default, QuecPython modules use UTC+8 as the time zone. For different regions, adjust it to the local time according to the time zone configuration.
import utime
# Configure the time zone to UTC+8. The time zone configuration here may conflict with the time zone configuration in NTP time synchronization. We recommend using ntptime to configure the time zone.
utime.setTimeZone(8)
# Get local UTC time.
utime.localtime()
Sleep
QuecPython provides interfaces for second-level, millisecond-level, and microsecond-level sleep, which can be called according to usage requirements.
Note: The actual sleep time is not accurate.
import utime
# Set the sleep time to 1 second.
utime.sleep(1)
utime.sleep_ms(1000)
utime.sleep_us(1000*1000)
System Timer
The system timer is used to perform a certain task at a scheduled or periodic time. The timer is implemented based on the hardware timer function and can generally create up to 4 timers. For all usages of the system timer on QuecPython devices, refer to the Timer - Control Hardware Timerssection.
from machine import Timer
# Timer timeout callback function.
def timer_callback(t):
print('timeout occurred!')
# Create a timer object.
t = Timer(Timer.Timer1)
# Start the timer and execute the timer callback every 1 second.
t.start(period=1000, mode=t.PERIODIC, callback=timer_callback)
RTC Alarm
Used to perform a specified task when the time expires. This function can also be used for low-power sleep wake-up, as well as wake-up from shutdown.
from machine import RTC
# Initialize the RTC
rtc = RTC()
# Define the wake-up callback function interface, which is executed after waking up.
def callback(args):
print('RTC alarm')
# Register the wake-up callback function.
rtc.register_callback(callback)
# Set the alarm to wake up at a certain time.
rtc.set_alarm([2026, 7, 9, 5, 12, 30, 0, 0])
# Enable the alarm.
rtc.enable_alarm(1)
Frequently Asked Questions
When the module is powered off (without power failure), does the RTC still run?
After the module is powered on, regardless of the module status (operating mode, low-power mode, reset state, or shutdown state), as long as the power supply voltage is within the working range, the RTC will continue to run and the previous time will not be lost. Except for the EC200A series modules.
Where does the time sync from when the module is powered off?
After the module is powered off, the circuit cannot work as normal and the current time will be lost. When powered on again, the module will synchronize the time with the base station using the NITZ method after connecting to the network. Users can also synchronize the time through the NTP custom server.