maix.time

maix.time module

You can use maix.time to access this module with MaixPy
This module is generated from MaixPy and MaixCDK

1. Module#

No module

2. Enum#

3. Variable#

4. Function#

4.1. time#

def time() -> float

Get current time in s

item description
return current time in s, double type
attention If board have no RTC battery, when bootup and connect to network,
system will automatically sync time by NTP, will cause time() have big change,
e.g. before NTP: 10(s), after: 1718590639.5149617(s).
If you want to calculate time interval, please use ticks_s().

C++ defination code:

double time()

4.2. time_ms#

def time_ms() -> int

Get current time in ms

item description
return current time in ms, uint64_t type
attention If board have no RTC battery, when bootup and connect to network,
system will automatically sync time by NTP, will cause time() have big change,
e.g. before NTP: 10000(ms), after: 1718590639000(ms)
If you want to calculate time interval, please use ticks_ms().

C++ defination code:

uint64_t time_ms()

4.3. time_s#

def time_s() -> int

Get current time in s

item description
return current time in s, uint64_t type
attention If board have no RTC battery, when bootup and connect to network,
system will automatically sync time by NTP, will cause time() have big change,
e.g. before NTP: 10(s), after: 1718590639(s)

C++ defination code:

uint64_t time_s()

4.4. time_us#

def time_us() -> int

Get current time in us

item description
return current time in us, uint64_t type
attention If board have no RTC battery, when bootup and connect to network,
system will automatically sync time by NTP, will cause time() have big change,
e.g. before NTP: 10000000(us), after: 1718590639000000(s)
If you want to calculate time interval, please use ticks_us().

C++ defination code:

uint64_t time_us()

4.5. time_diff#

def time_diff(last: float, now: float = -1) -> float

Calculate time difference in s.

item description
param last: last time
now: current time, can be -1 if use current time
return time difference
attention If board have no RTC battery, when bootup and connect to network,
system will automatically sync time by NTP, will cause time() have big change, and lead to big value.
e.g. before NTP: 1(s), after: 1718590500(s)
If you want to calculate time interval, please use ticks_diff().

C++ defination code:

double time_diff(double last, double now = -1)

4.6. ticks_s#

def ticks_s() -> float

Get current time in s since bootup

item description
return current time in s, double type

C++ defination code:

double ticks_s()

4.7. ticks_ms#

def ticks_ms() -> int

Get current time in ms since bootup

item description
return current time in ms, uint64_t type

C++ defination code:

uint64_t ticks_ms()

4.8. ticks_us#

def ticks_us() -> int

Get current time in us since bootup

item description
return current time in us, uint64_t type

C++ defination code:

uint64_t ticks_us()

4.9. ticks_diff#

def ticks_diff(last: float, now: float = -1) -> float

Calculate time difference in s.

item description
param last: last time
now: current time, can be -1 if use current time
return time difference

C++ defination code:

double ticks_diff(double last, double now = -1)

4.10. sleep#

Sleep seconds

item description
param s: seconds, double type

C++ defination code:

void sleep(double s)

4.11. sleep_ms#

Sleep milliseconds

item description
param ms: milliseconds, uint64_t type

C++ defination code:

void sleep_ms(uint64_t ms)

4.12. sleep_us#

Sleep microseconds

item description
param us: microseconds, uint64_t type

C++ defination code:

void sleep_us(uint64_t us)

4.13. fps#

def fps() -> float

Calculate FPS since last call this method.\nAttention, this method is not multi thread safe, only call this method in one threads.\nIf you want to use in multi threads, please use time.FPS class.\nFPS is average value of recent n(buff_len) times, and you can call fps_set_buff_len(10) to change buffer length, default is 20.\nMultiple invoke this function will calculate fps between two invoke, and you can also call fps_start() fisrt to manually assign fps calulate start point.

item description
return float type, current fps since last call this method

C++ defination code:

float fps()

4.14. fps_start#

def fps_start() -> None

Manually set fps calculation start point, then you can call fps() function to calculate fps between fps_start() and fps().

C++ defination code:

void fps_start()

4.15. fps_set_buff_len#

def fps_set_buff_len(len: int) -> None

Set fps method buffer length, by default the buffer length is 10.

item description
param len: Buffer length to store recent fps value.

C++ defination code:

void fps_set_buff_len(int len)

4.16. now#

def now() -> DateTime

Get current UTC date and time

item description
return current date and time, DateTime type

C++ defination code:

time::DateTime *now()

4.17. localtime#

def localtime() -> DateTime

Get local time

item description
return local time, DateTime type

C++ defination code:

time::DateTime *localtime()

4.18. strptime#

def strptime(str: str, format: str) -> DateTime

DateTime from string

item description
param str: date time string
format: date time format
return DateTime

C++ defination code:

time::DateTime *strptime(const std::string &str, const std::string &format)

4.19. gmtime#

def gmtime(timestamp: float) -> DateTime

timestamp to DateTime(time zone is UTC (value 0))

item description
param timestamp: double timestamp
return DateTime

C++ defination code:

time::DateTime *gmtime(double timestamp)

4.20. timezone#

def timezone(timezone: str = '') -> str

Set or get timezone

item description
param timezone: string type, can be empty and default to empty, if empty, only return crrent timezone, a "region/city" string, e.g. Asia/Shanghai, Etc/UTC, you can get all by list_timezones function.
return string type, return current timezone setting.
attention when set new timezone, time setting not take effect in this process for some API, so you need to restart program.

C++ defination code:

std::string timezone(const std::string &timezone = "")

4.21. timezone2#

def timezone2(region: str = '', city: str = '') -> list[str]

Set or get timezone

item description
param region: string type, which region to set, can be empty means only get current, default empty.
city: string type, which city to set, can be empty means only get current, default empty.
return list type, return current timezone setting, first is region, second is city.
attention when set new timezone, time setting not take effect in this process for some API, so you need to restart program.

C++ defination code:

std::vector<std::string> timezone2(const std::string &region = "", const std::string &city = "")

4.22. list_timezones#

def list_timezones() -> dict[str, list[str]]

List all timezone info

item description
return A dict with key are regions, and value are region's cities.

C++ defination code:

std::map<std::string, std::vector<std::string>> list_timezones()

4.23. ntp_timetuple#

def ntp_timetuple(host: str, port: int = -1, retry: int = 3, timeout_ms: int = 0) -> list[int]

Retrieves time from an NTP server\nThis function fetches the current time from the specified NTP server and port,\nreturning a tuple containing the time details.

item description
param host: The hostname or IP address of the NTP server.
port: The port number of the NTP server. Use -1 for the default port 123.
retry: The number of retry attempts. Must be at least 1.
timeout_ms: The timeout duration in milliseconds. Must be non-negative.
return A list of 6 elements: [year, month, day, hour, minute, second]

C++ defination code:

std::vector<int> ntp_timetuple(std::string host, int port=-1, uint8_t retry=3, int timeout_ms=0)

4.24. ntp_timetuple_with_config#

def ntp_timetuple_with_config(path: str) -> list[int]

Retrieves time from an NTP server using a configuration file\nThis function reads the configuration from a YAML file to fetch the current time\nfrom a list of specified NTP servers, returning a tuple containing the time details.

item description
param path: The path to the YAML configuration file, which should include:
- Config:
- retry: Number of retry attempts (must be at least 1)
- total_timeout_ms: Total timeout duration in milliseconds (must be non-negative)
- NtpServers:
- host: Hostname or IP address of the NTP server
- port: Port number of the NTP server (use 123 for default)
Example YAML configuration:
Config:
- retry: 3
- total_timeout_ms: 10000
NtpServers:
- host: "pool.ntp.org"
port: 123
- host: "time.nist.gov"
port: 123
- host: "time.windows.com"
port: 123
return A list of 6 elements: [year, month, day, hour, minute, second]

C++ defination code:

std::vector<int> ntp_timetuple_with_config(std::string path)

4.25. ntp_sync_sys_time#

def ntp_sync_sys_time(host: str, port: int = -1, retry: int = 3, timeout_ms: int = 0) -> list[int]

Retrieves time from an NTP server and synchronizes the system time\nThis function fetches the current time from the specified NTP server and port,\nthen synchronizes the system time with the retrieved time.

item description
param host: The hostname or IP address of the NTP server.
port: The port number of the NTP server. Use 123 for the default port.
retry: The number of retry attempts. Must be at least 1.
timeout_ms: The timeout duration in milliseconds. Must be non-negative.
return A list of 6 elements: [year, month, day, hour, minute, second]

C++ defination code:

std::vector<int> ntp_sync_sys_time(std::string host, int port=-1, uint8_t retry=3, int timeout_ms=0)

4.26. ntp_sync_sys_time_with_config#

def ntp_sync_sys_time_with_config(path: str) -> list[int]

Retrieves time from an NTP server using a configuration file and synchronizes the system time\nThis function reads the configuration from a YAML file to fetch the current time\nfrom a list of specified NTP servers, then synchronizes the system time with the retrieved time.

item description
param path: The path to the YAML configuration file, which should include:
- Config:
- retry: Number of retry attempts (must be at least 1)
- total_timeout_ms: Total timeout duration in milliseconds (must be non-negative)
- NtpServers:
- host: Hostname or IP address of the NTP server
- port: Port number of the NTP server (use 123 for default)
Example YAML configuration:
Config:
- retry: 3
- total_timeout_ms: 10000
NtpServers:
- host: "pool.ntp.org"
port: 123
- host: "time.nist.gov"
port: 123
- host: "time.windows.com"
port: 123
return A vector of integers containing the time details: [year, month, day, hour, minute, second]

C++ defination code:

std::vector<int> ntp_sync_sys_time_with_config(std::string path)

5. Class#

5.1. FPS#

FPS class to use average filter to calculate FPS.

C++ defination code:

class FPS

5.1.1. __init__#

def __init__(self, buff_len: int = 20) -> None

FPS class constructor

item description
type func
param buff_len: Average buffer length, default 20, that is, fps() function will return the average fps in recent buff_len times fps.
static False

C++ defination code:

FPS(int buff_len = 20)

5.1.2. start#

def start(self) -> None

Manually set fps calculation start point, then you can call fps() function to calculate fps between start() and fps().

item description
type func
static False

C++ defination code:

void start()

5.1.3. fps#

def fps(self) -> float

The same as end function.

item description
type func
return float type, current fps since last call this method
static False

C++ defination code:

float fps()

5.1.4. end#

def end(self) -> float

Calculate FPS since last call this method.\nFPS is average value of recent n(buff_len) times, and you can call fps_set_buff_len(10) to change buffer length, default is 20.\nMultiple invoke this function will calculate fps between two invoke, and you can also call fps_start() fisrt to manually assign fps calulate start point.

item description
type func
return float type, current fps since last call this method
static False

C++ defination code:

float end()

5.1.5. set_buff_len#

def set_buff_len(self, len: int) -> None

Set fps method buffer length, by default the buffer length is 10.

item description
type func
param len: Buffer length to store recent fps value.
static False

C++ defination code:

void set_buff_len(int len)

5.2. DateTime#

Date and time class

C++ defination code:

class DateTime

5.2.1. year#

Year

item description
type var
static False
readonly False

C++ defination code:

int year

5.2.2. month#

Month, 1~12

item description
type var
static False
readonly False

C++ defination code:

int month

5.2.3. day#

Day

item description
type var
static False
readonly False

C++ defination code:

int day

5.2.4. hour#

Hour

item description
type var
static False
readonly False

C++ defination code:

int hour

5.2.5. minute#

Minute

item description
type var
static False
readonly False

C++ defination code:

int minute

5.2.6. second#

Second

item description
type var
static False
readonly False

C++ defination code:

int second

5.2.7. microsecond#

Microsecond

item description
type var
static False
readonly False

C++ defination code:

int microsecond

5.2.8. yearday#

Year day

item description
type var
static False
readonly False

C++ defination code:

int yearday

5.2.9. weekday#

Weekday, 0 is Monday, 6 is Sunday

item description
type var
static False
readonly False

C++ defination code:

int weekday

5.2.10. zone#

Time zone

item description
type var
static False
readonly False

C++ defination code:

float zone

5.2.11. zone_name#

Time zone name

item description
type var
static False
readonly False

C++ defination code:

std::string zone_name

5.2.12. __init__#

def __init__(self, year: int = 0, month: int = 0, day: int = 0, hour: int = 0, minute: int = 0, second: int = 0, microsecond: int = 0, yearday: int = 0, weekday: int = 0, zone: int = 0) -> None

Constructor

item description
type func
param year: year
month: month
day: day
hour: hour
minute: minute
second: second
microsecond: microsecond
yearday: year day
weekday: weekday
zone: time zone
static False

C++ defination code:

DateTime(int year = 0, int month = 0, int day = 0, int hour = 0, int minute = 0, int second = 0, int microsecond = 0, int yearday = 0, int weekday = 0, int zone = 0)

5.2.13. strftime#

def strftime(self, format: str) -> str

Convert to string

item description
type func
return date time string
static False

C++ defination code:

std::string strftime(const std::string &format)

5.2.14. timestamp#

def timestamp(self) -> float

Convert to float timestamp

item description
type func
return float timestamp
static False

C++ defination code:

double timestamp()