esphome::time Namespace Reference

Namespaces
namespace	internal

Data Structures
struct	BcdCalendarLayout
	Layout of a 7-byte BCD calendar: second, minute, hour, weekday and day of the month in either order, month and year since 2000. More...
class	CronTrigger
struct	DSTRule
	Rule for DST transition (packed for 32-bit: 12 bytes) More...
struct	ParsedTimezone
	Parsed POSIX timezone information (packed for 32-bit: 32 bytes) More...
class	RealTimeClock
	The RealTimeClock class exposes common timekeeping functions via the device's local real-time clock. More...

Enumerations
enum class	DSTRuleType : uint8_t { NONE = 0 , MONTH_WEEK_DAY , JULIAN_NO_LEAP , DAY_OF_YEAR }
	Type of DST transition rule. More...
enum class	BcdWeekday : uint8_t { ONE_HOT , FROM_1 , FROM_0 }
	How the weekday byte of a BCD calendar names the day, Sunday first. More...

Functions
	ESPHOME_LOG_TAG (TAG, "automation")
void	set_global_tz (const ParsedTimezone &tz)
	Set the global timezone used by epoch_to_local_tm() when called without a timezone.
const ParsedTimezone &	get_global_tz ()
	Get the global timezone.
	if (dst_start< dst_end)
void	format_designation (int32_t posix_offset, char *buf, size_t buf_size)
	Format a POSIX offset as "+HHMM"/"-HHMM" into buf (must be >= 6 bytes).
bool	epoch_to_local_tm (time_t utc_epoch, const ParsedTimezone &tz, struct tm *out_tm)
	Convert a UTC epoch to local time using the parsed timezone.
bool	is_in_dst (time_t utc_epoch, const ParsedTimezone &tz)
	Check if a given UTC epoch falls within DST for the parsed timezone.
	ESPHOME_LOG_TAG (TAG, "time")
template<BcdCalendarLayout LAYOUT>
	__attribute__ ((noinline)) ESPTime decode_bcd_calendar(const uint8_t *raw)
	Decode the 7-byte BCD calendar at raw in the given layout and fill in the UTC timestamp.
template<BcdCalendarLayout LAYOUT>
	__attribute__ ((noinline)) void encode_bcd_calendar(const ESPTime &time
	Encode time into the 7-byte BCD calendar at raw in the given layout, always in 24-hour mode.
	for (size_t i=0;i< 7;i++) raw[i]
if	constexpr (LAYOUT.weekday==BcdWeekday::ONE_HOT)

Variables
bool const ParsedTimezone &	tz
time_t	dst_start = internal::calculate_dst_transition(year, tz.dst_start, tz.std_offset_seconds)
time_t	dst_end = internal::calculate_dst_transition(year, tz.dst_end, tz.dst_offset_seconds)
	else
ESPTime	__attribute__ ((noinline)) RealTimeClock
constexpr BcdCalendarLayout	EPSON_BCD_CALENDAR {.weekday = BcdWeekday::ONE_HOT}
	Epson RX8025T, RX8111, RX8130.
constexpr BcdCalendarLayout	DS_BCD_CALENDAR
	DS1307, DS3231.
constexpr BcdCalendarLayout	PCF_BCD_CALENDAR {.weekday = BcdWeekday::FROM_0, .weekday_before_day = false}
	PCF8563, PCF85063, BM8563.
uint8_t *	raw
	value [LAYOUT.day_index()] = time.day_of_month

Enumeration Type Documentation

BcdWeekday

enum class esphome::time::BcdWeekday : uint8_t

strong

How the weekday byte of a BCD calendar names the day, Sunday first.

Enumerator
ONE_HOT	one bit per day, bit 0 is Sunday
FROM_1	1 is Sunday
FROM_0	0 is Sunday

Definition at line 48 of file real_time_clock.h.

DSTRuleType

enum class esphome::time::DSTRuleType : uint8_t

strong

Type of DST transition rule.

Enumerator
NONE	No DST rule (used to indicate no DST)
MONTH_WEEK_DAY	M format: Mm.w.d (e.g., M3.2.0 = 2nd Sunday of March)
JULIAN_NO_LEAP	J format: Jn (day 1-365, Feb 29 not counted)
DAY_OF_YEAR	Plain number: n (day 0-365, Feb 29 counted in leap years)

Definition at line 11 of file posix_tz.h.

Function Documentation

__attribute__() [1/2]

template<BcdCalendarLayout LAYOUT>

esphome::time::__attribute__

(

(noinline)

)

const

Decode the 7-byte BCD calendar at raw in the given layout and fill in the UTC timestamp.

Bits each byte does not use for its value, such as a chip's flag bits, are dropped; day_of_year is not worked out. Kept out of line so that drivers sharing a layout share one copy.

Definition at line 79 of file real_time_clock.h.

__attribute__() [2/2]

template<BcdCalendarLayout LAYOUT>

esphome::time::__attribute__

(

(noinline)

)

const &

Encode time into the 7-byte BCD calendar at raw in the given layout, always in 24-hour mode.

time must be valid (is_valid()); the year must be 2000 to 2099 unless the layout has a century bit.

constexpr()

if esphome::time::constexpr ( LAYOUT. weekday = = BcdWeekday::ONE_HOT )

constexpr

Definition at line 125 of file real_time_clock.h.

epoch_to_local_tm()

bool esphome::time::epoch_to_local_tm	(	time_t	utc_epoch,
		const ParsedTimezone &	tz,
		struct tm *	out_tm )

Convert a UTC epoch to local time using the parsed timezone.

This replaces libc's localtime() to avoid scanf dependency.

Parameters

	utc_epoch	Unix timestamp in UTC
	tz	The parsed timezone
[out]	out_tm	Output tm struct with local time

Returns

true on success

Definition at line 268 of file posix_tz.cpp.

ESPHOME_LOG_TAG() [1/2]

esphome::time::ESPHOME_LOG_TAG	(	TAG	,
		"automation"	)

ESPHOME_LOG_TAG() [2/2]

esphome::time::ESPHOME_LOG_TAG	(	TAG	,
		"time"	)

for()

esphome::time::for

(

)

format_designation()

void esphome::time::format_designation	(	int32_t	posix_offset,
		char *	buf,
		size_t	buf_size )

Format a POSIX offset as "+HHMM"/"-HHMM" into buf (must be >= 6 bytes).

Definition at line 258 of file posix_tz.cpp.

get_global_tz()

const ParsedTimezone & esphome::time::get_global_tz

(

)

Get the global timezone.

Definition at line 16 of file posix_tz.cpp.

if()

esphome::time::if

(

)

Definition at line 247 of file posix_tz.cpp.

is_in_dst()

bool esphome::time::is_in_dst	(	time_t	utc_epoch,
		const ParsedTimezone &	tz )

Check if a given UTC epoch falls within DST for the parsed timezone.

Parameters

utc_epoch	Unix timestamp in UTC
tz	The parsed timezone

Returns

true if DST is in effect at the given time

set_global_tz()

void esphome::time::set_global_tz

(

const ParsedTimezone &

tz

)

Set the global timezone used by epoch_to_local_tm() when called without a timezone.

This enables ESPTime::from_epoch_local() to work without libc's localtime().

Definition at line 14 of file posix_tz.cpp.

Variable Documentation

__attribute__

bool esphome::time::__attribute__

(

(noinline)

)

Definition at line 26 of file real_time_clock.cpp.

DS_BCD_CALENDAR

BcdCalendarLayout esphome::time::DS_BCD_CALENDAR

inlineconstexpr

Initial value:

{
    .weekday = BcdWeekday::FROM_1, .century_bit = true, .hour_12h = true}

DS1307, DS3231.

Definition at line 71 of file real_time_clock.h.

dst_end

time_t esphome::time::dst_end = internal::calculate_dst_transition(year, tz.dst_end, tz.dst_offset_seconds)

Definition at line 245 of file posix_tz.cpp.

dst_start

time_t esphome::time::dst_start = internal::calculate_dst_transition(year, tz.dst_start, tz.std_offset_seconds)

Definition at line 243 of file posix_tz.cpp.

else

esphome::time::else

Initial value:

{
    
    return (utc_epoch >= dst_start || utc_epoch < dst_end)

Definition at line 250 of file posix_tz.cpp.

EPSON_BCD_CALENDAR

BcdCalendarLayout esphome::time::EPSON_BCD_CALENDAR {.weekday = BcdWeekday::ONE_HOT}

inlineconstexpr

Epson RX8025T, RX8111, RX8130.

Definition at line 69 of file real_time_clock.h.

PCF_BCD_CALENDAR

BcdCalendarLayout esphome::time::PCF_BCD_CALENDAR {.weekday = BcdWeekday::FROM_0, .weekday_before_day = false}

inlineconstexpr

PCF8563, PCF85063, BM8563.

Definition at line 74 of file real_time_clock.h.

raw

uint8_t* esphome::time::raw

Initial value:

{
  uint8_t value[7] = {time.second, time.minute, time.hour, 0, 0, time.month, static_cast<uint8_t>(time.year % 100)}

Definition at line 120 of file real_time_clock.h.

tz

bool const ParsedTimezone& esphome::time::tz

Initial value:

{
  if (!tz.has_dst()) {
    return false;
  }
 
  int year = internal::epoch_to_year(utc_epoch)

Definition at line 234 of file posix_tz.cpp.

value

esphome::time::value[LAYOUT.day_index()] = time.day_of_month

Definition at line 122 of file real_time_clock.h.