Utility Functions

This section covers various useful functions that don't fit anywhere else. More...

Data Structures
struct	watch_duration_t

Functions
const char *	watch_utility_get_weekday (watch_date_time date_time)
	Returns a two-letter weekday for the given timestamp, suitable for display in positions 0-1 of the watch face.
uint8_t	watch_utility_get_iso8601_weekday_number (uint16_t year, uint8_t month, uint8_t day)
	Returns a number between 1-7 representing the weekday according to ISO8601 : week starts on Monday and has index 1, Sunday has index 7.
uint8_t	watch_utility_get_weeknumber (uint16_t year, uint8_t month, uint8_t day)
	Returns a number between 1-53 representing the weeknumber according to ISO8601 : First week of the year always contains Thursday. If it overlaps on previous year, current year has 53 weeks.
uint16_t	watch_utility_days_since_new_year (uint16_t year, uint8_t month, uint8_t day)
	Returns a number between 1-366 representing the elapsed days since January 1st the same year.
uint8_t	is_leap (uint16_t year)
	Returns 1 if year is leap and 0 otherwise.
uint32_t	watch_utility_convert_to_unix_time (uint16_t year, uint8_t month, uint8_t day, uint8_t hour, uint8_t minute, uint8_t second, uint32_t utc_offset)
	Returns the UNIX time (seconds since 1970) for a given date/time in UTC.
uint32_t	watch_utility_date_time_to_unix_time (watch_date_time date_time, uint32_t utc_offset)
	Returns the UNIX time (seconds since 1970) for a given watch_date_time struct.
watch_duration_t	watch_utility_seconds_to_duration (uint32_t seconds)
	Converts a duration in seconds to a watch_duration_t struct.
watch_date_time	watch_utility_date_time_from_unix_time (uint32_t timestamp, uint32_t utc_offset)
	Returns a watch_date_time struct for a given UNIX time and UTC offset.
bool	watch_utility_convert_to_12_hour (watch_date_time *date_time)
	Converts a watch_date_time for 12-hour display.
watch_date_time	watch_utility_date_time_convert_zone (watch_date_time date_time, uint32_t origin_utc_offset, uint32_t destination_utc_offset)
	Converts a time from a given time zone to another time zone.
float	watch_utility_thermistor_temperature (uint16_t value, bool highside, float b_coefficient, float nominal_temperature, float nominal_resistance, float series_resistance)
	Returns a temperature in degrees Celsius for a given thermistor voltage divider circuit.
uint32_t	watch_utility_offset_timestamp (uint32_t now, int8_t hours, int8_t minutes, int8_t seconds)
	Offset a timestamp by a given amount.
uint8_t	days_in_month (uint8_t month, uint16_t year)
	Returns the number of days in a month. It also handles Leap Years for February.

Variables
uint8_t	watch_duration_t::seconds
uint8_t	watch_duration_t::minutes
uint8_t	watch_duration_t::hours
uint32_t	watch_duration_t::days

Detailed Description

This section covers various useful functions that don't fit anywhere else.

Function Documentation

days_in_month()

uint8_t days_in_month	(	uint8_t	month,
		uint16_t	year
	)

Returns the number of days in a month. It also handles Leap Years for February.

Parameters

month	The month of the date (1-12)
year	The year of the date (ex. 2022)

is_leap()

uint8_t is_leap

(

uint16_t

year

)

Returns 1 if year is leap and 0 otherwise.

Parameters

year	The year (ex. 2022)

watch_utility_convert_to_12_hour()

bool watch_utility_convert_to_12_hour

(

watch_date_time *

date_time

)

Converts a watch_date_time for 12-hour display.

Parameters

date_time

A pointer to the watch_date_time that you wish to convert for display. Note that this function will OVERWRITE the original date/time, rendering it invalid for date/time calculations. Midnight (hour 0) will become 12, and hours in the afternoon will wrap back around to values from 1-11.

Returns

True if the value is in the afternoon. You can use this value to determine whether to set the PM indicator on the LCD.

Note

This function sort of abuses the watch_date_time struct; the date/time that results from calling this function is clamped to the hours of 1:00:00 AM through 12:59:59 PM. It no longer reflects a valid watch_date_time for writing to an RTC register.

watch_utility_convert_to_unix_time()

uint32_t watch_utility_convert_to_unix_time	(	uint16_t	year,
		uint8_t	month,
		uint8_t	day,
		uint8_t	hour,
		uint8_t	minute,
		uint8_t	second,
		uint32_t	utc_offset
	)

Returns the UNIX time (seconds since 1970) for a given date/time in UTC.

Parameters

date_time	The watch_date_time that you wish to convert.
year	The year of the date you wish to convert.
month	The month of the date you wish to convert.
day	The day of the date you wish to convert.
hour	The hour of the date you wish to convert.
minute	The minute of the date you wish to convert.
second	The second of the date you wish to convert.
utc_offset	The number of seconds that date_time is offset from UTC, or 0 if the time is UTC.

Returns

A UNIX timestamp for the given date/time and UTC offset.

Note

Implemented by Wesley Ellis (tahnok) and based on BSD-licensed code by Josh Haberman: https://blog.reverberate.org/2020/05/12/optimizing-date-algorithms.html

watch_utility_date_time_convert_zone()

watch_date_time watch_utility_date_time_convert_zone	(	watch_date_time	date_time,
		uint32_t	origin_utc_offset,
		uint32_t	destination_utc_offset
	)

Converts a time from a given time zone to another time zone.

Parameters

date_time	The watch_date_time that you wish to convert
origin_utc_offset	The number of seconds from UTC in the origin time zone
destination_utc_offset	The number of seconds from UTC in the destination time zone

Returns

A watch_date_time for the given UNIX timestamp and UTC offset, or if outside the range that watch_date_time can represent, a watch_date_time with all fields set to 0.

Note

Adapted from MIT-licensed code from musl, Copyright © 2005-2014 Rich Felker, et al.: https://github.com/esmil/musl/blob/1cc81f5cb0df2b66a795ff0c26d7bbc4d16e13c6/src/time/__secs_to_tm.c

watch_utility_date_time_from_unix_time()

watch_date_time watch_utility_date_time_from_unix_time	(	uint32_t	timestamp,
		uint32_t	utc_offset
	)

Returns a watch_date_time struct for a given UNIX time and UTC offset.

Parameters

timestamp	The UNIX timestamp that you wish to convert.
utc_offset	The number of seconds that you wish date_time to be offset from UTC.

Returns

A watch_date_time for the given UNIX timestamp and UTC offset, or if outside the range that watch_date_time can represent, a watch_date_time with all fields set to 0.

Note

Adapted from MIT-licensed code from musl, Copyright © 2005-2014 Rich Felker, et al.: https://github.com/esmil/musl/blob/1cc81f5cb0df2b66a795ff0c26d7bbc4d16e13c6/src/time/__secs_to_tm.c

watch_utility_date_time_to_unix_time()

uint32_t watch_utility_date_time_to_unix_time	(	watch_date_time	date_time,
		uint32_t	utc_offset
	)

Returns the UNIX time (seconds since 1970) for a given watch_date_time struct.

Parameters

date_time	The watch_date_time that you wish to convert.
utc_offset	The number of seconds that date_time is offset from UTC, or 0 if the time is UTC.

Returns

A UNIX timestamp for the given watch_date_time and UTC offset.

watch_utility_days_since_new_year()

uint16_t watch_utility_days_since_new_year	(	uint16_t	year,
		uint8_t	month,
		uint8_t	day
	)

Returns a number between 1-366 representing the elapsed days since January 1st the same year.

Parameters

year	The year of the date
month	The month of the date (1-12)
day	The day of the date (1-31)

watch_utility_get_iso8601_weekday_number()

uint8_t watch_utility_get_iso8601_weekday_number	(	uint16_t	year,
		uint8_t	month,
		uint8_t	day
	)

Returns a number between 1-7 representing the weekday according to ISO8601 : week starts on Monday and has index 1, Sunday has index 7.

Parameters

year	The year of the date
month	The month of the date (1-12)
day	The day of the date (1-31)

watch_utility_get_weekday()

const char * watch_utility_get_weekday

(

watch_date_time

date_time

)

Returns a two-letter weekday for the given timestamp, suitable for display in positions 0-1 of the watch face.

Parameters

date_time

The watch_date_time whose weekday you want.

watch_utility_get_weeknumber()

uint8_t watch_utility_get_weeknumber	(	uint16_t	year,
		uint8_t	month,
		uint8_t	day
	)

Returns a number between 1-53 representing the weeknumber according to ISO8601 : First week of the year always contains Thursday. If it overlaps on previous year, current year has 53 weeks.

Parameters

year	The year of the date
month	The month of the date (1-12)
day	The day of the date (1-31)

watch_utility_offset_timestamp()

uint32_t watch_utility_offset_timestamp	(	uint32_t	now,
		int8_t	hours,
		int8_t	minutes,
		int8_t	seconds
	)

Offset a timestamp by a given amount.

Parameters

now	Timestamp to offset from
hours	Number of hours to offset
minutes	Nmber of minutes to offset
seconds	Number of secodns to offset

watch_utility_seconds_to_duration()

watch_duration_t watch_utility_seconds_to_duration

(

uint32_t

seconds

)

Converts a duration in seconds to a watch_duration_t struct.

Parameters

seconds

A positive number of seconds that you wish to convert to a formatted duration.

Returns

A populated struct with the number of days, hours, minutes and seconds elapsed.

watch_utility_thermistor_temperature()

float watch_utility_thermistor_temperature	(	uint16_t	value,
		bool	highside,
		float	b_coefficient,
		float	nominal_temperature,
		float	nominal_resistance,
		float	series_resistance
	)

Returns a temperature in degrees Celsius for a given thermistor voltage divider circuit.

Parameters

value	The raw analog reading from the thermistor pin (0-65535)
highside	True if the thermistor is connected to VCC and the series resistor is connected to GND; false if the thermistor is connected to GND and the series resistor is connected to VCC.
b_coefficient	From your thermistor's data sheet, the B25/85 coefficient. A typical value will be between 2000 and 5000.
nominal_temperature	From your thermistor's data sheet, the temperature (in Celsius) at which the thermistor's resistance is at its nominal value.
nominal_resistance	The thermistor's resistance at the nominal temperature.
series_resistance	The value of the other resistor in the voltage divider.

Note

Ported from Adafruit's MIT-licensed CircuitPython thermistor code, (c) 2017 Scott Shawcroft: https://github.com/adafruit/Adafruit_CircuitPython_Thermistor/blob/main/adafruit_thermistor.py