Weather database

Weather locations (BlobDBIdWeather), keyed by location UUID. More...

Data Structures
struct	WeatherDBEntryV3
	Legacy v3 record. More...
struct	WeatherDBDailyForecast
	One day of daily forecast (v4). More...
struct	WeatherDBDailyMetrics
	Extended metrics of one day (v4 minor 1), parallel to daily (index 0 is today). More...
struct	WeatherDBEntry
	v4 record. More...

Macros
#define	WEATHER_DB_CURRENT_VERSION   (4)
	Current major version of the record schema.
#define	WEATHER_DB_CURRENT_MINOR_VERSION   (5)
	Newest minor version of the v4 schema understood by the firmware.
#define	WEATHER_DB_LEGACY_VERSION   (3)
	Major version of the legacy record schema.
#define	WEATHER_DB_MAX_FORECAST_DAYS   (7)
	Days of daily forecast in a v4 record (today + 6).
#define	WEATHER_DB_HOURLY_COUNT   (24)
	Hours of hourly data in a v4 series (one day, keeps the record small).
#define	WEATHER_DB_V4_0_FIXED_SIZE   (offsetof(WeatherDBEntry, location_utc_offset_min))
	Fixed size of a v4.0 record, the minimum of any v4 record and where its strings start.
#define	WEATHER_DB_V4_1_FIXED_SIZE   (offsetof(WeatherDBEntry, today_wmo_code))
	Fixed size of a v4.1 record, where its strings start.
#define	WEATHER_DB_V4_2_FIXED_SIZE   (offsetof(WeatherDBEntry, today_wind_dir_deg))
	Fixed size of a v4.2 record, where its strings start.
#define	WEATHER_DB_V4_3_FIXED_SIZE   (offsetof(WeatherDBEntry, today_hourly_uv_x10))
	Fixed size of a v4.3 record, where its strings start.
#define	WEATHER_DB_V4_4_FIXED_SIZE   (offsetof(WeatherDBEntry, tomorrow_hourly_count))
	Fixed size of a v4.4 record, where its strings start.
#define	WEATHER_DB_V4_FIXED_SIZE   (offsetof(WeatherDBEntry, pstring16s))
	Fixed size of a current (v4.5) record, everything but the trailing strings.
#define	MIN_ENTRY_SIZE   (sizeof(WeatherDBEntryV3))
	Smallest acceptable record, a legacy v3 record.
#define	MAX_ENTRY_SIZE
	Largest acceptable record.

Typedefs
typedef Uuid	WeatherDBKey
	Record key, the location UUID.
typedef void(*	WeatherDBIteratorCallback) (WeatherDBKey *key, WeatherDBEntry *entry, void *context)
	Callback of weather_db_for_each().

Enumerations
enum	WeatherDbStringIndex { WeatherDbStringIndex_LocationName , WeatherDbStringIndex_ShortPhrase , WeatherDbStringIndexCount }
	Index of the strings in a record's pstring16s. More...

Functions
static bool	weather_db_version_is_supported (uint8_t version)
	Check whether the firmware can parse a major version.
static bool	weather_db_entry_is_supported (const WeatherDBEntry *entry)
	Check whether the firmware can parse a record.
static size_t	weather_db_entry_strings_offset (uint8_t version, uint8_t minor_version)
	Get the offset of the trailing strings for a record version.
static struct pbl_serialized_array *	weather_db_entry_get_strings (WeatherDBEntry *entry)
	Locate the trailing strings of a record.
status_t	weather_db_for_each (WeatherDBIteratorCallback cb, void *context)
	Call a function for every supported record.
void	weather_db_init (void)
	Initialize the weather database.
status_t	weather_db_flush (void)
	Delete all records of the weather database.
status_t	weather_db_compact (void)
	Compact the settings file backing the weather database.
status_t	weather_db_insert (const uint8_t *key, int key_len, const uint8_t *val, int val_len)
	Insert or replace a record in the weather database.
int	weather_db_get_len (const uint8_t *key, int key_len)
	Get the length of a record in the weather database.
status_t	weather_db_read (const uint8_t *key, int key_len, uint8_t *val_out, int val_out_len)
	Read a record from the weather database.
status_t	weather_db_delete (const uint8_t *key, int key_len)
	Delete a record from the weather database.

Detailed Description

Weather locations (BlobDBIdWeather), keyed by location UUID.

Two record schemas coexist:

• v3, the legacy schema (current conditions, today and tomorrow), see WeatherDBEntryV3.
• v4, the rich schema for the full Weather app, see WeatherDBEntry. It appends today's extended metrics, the location coordinates, a multi-day daily forecast and today's hourly series after the v3 prefix, whose offsets are preserved, and before the trailing variable-length pstring16s. The version byte is the single source of compatibility.

The phone only writes v4 records when the firmware advertises weather_db_v4_support; otherwise it keeps writing v3. The firmware parses both.

v4 minor versions append fixed fields before the trailing strings:

• 0: base v4.
• 1: location_utc_offset_min and daily_metrics.
• 2: today's raw warning readings (WMO code, humidity, minimum visibility, precipitation sum) for the weather report's warning line, and daily_feels_like.
• 3: dominant wind direction, today and per day.
• 4: today's hourly UV.
• 5: tomorrow's hourly type and temperature series.

Older minors remain parseable: readers gate the appended fields on minor_version and the record length, and the trailing strings offset is resolved per minor (see weather_db_entry_get_strings()). Unknown future minors are rejected on insert since their strings offset is unknowable, so the phone must gate each new minor on firmware support.

---

Data Structure Documentation

WeatherDBEntryV3

struct WeatherDBEntryV3

Legacy v3 record.

Kept verbatim so records written by older phone apps can still be read. Do not change.

Data Fields
int16_t	current_temp	Current temperature.
WeatherType	current_weather_type	Current conditions.
bool	is_current_location	Whether this is the phone's current location.
int32_t	last_update_time_utc	Time of the last update, UTC.
struct pbl_serialized_array	pstring16s	Location name and short phrase, see WeatherDbStringIndex.
int16_t	today_high_temp	Today's high temperature.
int16_t	today_low_temp	Today's low temperature.
int16_t	tomorrow_high_temp	Tomorrow's high temperature.
int16_t	tomorrow_low_temp	Tomorrow's low temperature.
WeatherType	tomorrow_weather_type	Tomorrow's conditions.
uint8_t	version	Schema version, WEATHER_DB_LEGACY_VERSION.

WeatherDBDailyForecast

struct WeatherDBDailyForecast

One day of daily forecast (v4).

Data Fields
int16_t	high_temp	High temperature, WEATHER_SERVICE_LOCATION_FORECAST_UNKNOWN_TEMP if unknown.
int16_t	low_temp	Low temperature, WEATHER_SERVICE_LOCATION_FORECAST_UNKNOWN_TEMP if unknown.
uint8_t	weather_type	WeatherType stored as a byte, cast on read; 255 if unknown.

WeatherDBDailyMetrics

struct WeatherDBDailyMetrics

Extended metrics of one day (v4 minor 1), parallel to daily (index 0 is today).

Shown on the scrolled forecast and when paging through days. 255 means unknown.

Data Fields
uint8_t	precip_probability	Precipitation probability, 0 to 100 %.
uint8_t	uv_index_x10	UV index times 10, 0 to 110.
uint8_t	wind_speed	Wind speed in whole units, same unit as today_wind_speed.

WeatherDBEntry

struct WeatherDBEntry

v4 record.

Layout: the v3 fixed prefix with unchanged offsets, the v4 fixed fields, then the trailing pstring16s, which must stay last. Fields of a minor are only present when minor_version is at least that minor; use weather_db_entry_get_strings() to locate the strings.

Data Fields
int16_t	current_temp	Current temperature.
WeatherType	current_weather_type	Current conditions.
WeatherDBDailyForecast	daily[WEATHER_DB_MAX_FORECAST_DAYS]	Daily forecast, index 0 is today.
int16_t	daily_feels_like[WEATHER_DB_MAX_FORECAST_DAYS]	Per-day feels-like maximum, parallel to daily; WEATHER_SERVICE_LOCATION_FORECAST_UNKNOWN_TEMP if unknown. Minor 2.
WeatherDBDailyMetrics	daily_metrics[WEATHER_DB_MAX_FORECAST_DAYS]	Per-day extended metrics, parallel to daily. Minor 1.
int16_t	daily_wind_dir_deg[WEATHER_DB_MAX_FORECAST_DAYS]	Per-day dominant wind direction in degrees (0 to 359), -1 if unknown. Minor 3.
bool	is_current_location	Whether this is the phone's current location.
int32_t	last_update_time_utc	Time of the last update, UTC.
int16_t	latitude_e2	Latitude times 100, for the globe; INT16_MIN if unknown.
int16_t	location_utc_offset_min	Location timezone in minutes east of UTC (e.g. Tokyo +540, New York DST -240); INT16_MIN if unknown. Minor 1. Lets the watch show the location's local sunset and hourly times for saved cities.
int16_t	longitude_e2	Longitude times 100, for the globe; INT16_MIN if unknown.
uint8_t	minor_version	Minor version of the v4 schema.
uint8_t	num_daily	Valid entries in daily (0 to WEATHER_DB_MAX_FORECAST_DAYS).
struct pbl_serialized_array	pstring16s	Location name and short phrase, see WeatherDbStringIndex. Must stay last. Only at this offset in current minor records; use weather_db_entry_get_strings().
int16_t	today_feels_like_temp	Today's feels-like temperature, WEATHER_SERVICE_LOCATION_FORECAST_UNKNOWN_TEMP if unknown.
int16_t	today_high_temp	Today's high temperature.
uint8_t	today_hourly_count	Entries in today's hourly series, 0 or WEATHER_DB_HOURLY_COUNT.
int8_t	today_hourly_temp[WEATHER_DB_HOURLY_COUNT]	Temperature of each hour of today, 0 to 23.
uint8_t	today_hourly_uv_x10[WEATHER_DB_HOURLY_COUNT]	UV index times 10 for each hour of today (UV 6.5 is 65), 255 if unknown. Minor 4. Gives the current hour's UV; today_uv_index_x10 stays the day's figure.
uint8_t	today_hourly_weather_type[WEATHER_DB_HOURLY_COUNT]	WeatherType of each hour of today, 0 to 23.
uint8_t	today_humidity_pct	Today's mean relative humidity (0 to 100 %), 0xFF if unknown. Minor 2.
int16_t	today_low_temp	Today's low temperature.
int16_t	today_precip_probability	Today's precipitation probability (0 to 100 %), -1 if unknown.
uint16_t	today_precip_sum_mm	Today's total precipitation in whole mm (clamped to 65534), 0xFFFF if unknown. Minor 2.
int16_t	today_uv_index_x10	Today's UV index times 10 (0 to 110), -1 if unknown.
uint16_t	today_visibility_m	Today's minimum visibility in meters (clamped to 65534), 0xFFFF if unknown. Minor 2.
int16_t	today_wind_dir_deg	Today's dominant wind direction in degrees (0 to 359), -1 if unknown. Minor 3.
uint16_t	today_wind_direction	Today's wind direction in degrees (0 to 359), 0xFFFF if unknown.
uint16_t	today_wind_speed	Today's wind speed in whole units (km/h or mph, as chosen on the phone), 0 if unknown.
uint8_t	today_wmo_code	Today's WMO weather code (Open-Meteo daily weather_code), 0xFF if unknown. Minor 2.
int16_t	tomorrow_high_temp	Tomorrow's high temperature.
uint8_t	tomorrow_hourly_count	Entries in tomorrow's hourly series, 0 or WEATHER_DB_HOURLY_COUNT. Minor 5. Tomorrow's series mirrors today's for the next location-local day, so the clock dial, which shows the next 12 hours, has data past midnight.
int8_t	tomorrow_hourly_temp[WEATHER_DB_HOURLY_COUNT]	Temperature of each hour of tomorrow, 0 to 23. Minor 5.
uint8_t	tomorrow_hourly_weather_type[WEATHER_DB_HOURLY_COUNT]	WeatherType of each hour of tomorrow, 255 if unknown. Minor 5.
int16_t	tomorrow_low_temp	Tomorrow's low temperature.
WeatherType	tomorrow_weather_type	Tomorrow's conditions.
uint8_t	version	Schema version, WEATHER_DB_CURRENT_VERSION.

Macro Definition Documentation

MAX_ENTRY_SIZE

#define MAX_ENTRY_SIZE

Value:

  (sizeof(WeatherDBEntry) + WEATHER_SERVICE_MAX_WEATHER_LOCATION_BUFFER_SIZE + \
   WEATHER_SERVICE_MAX_SHORT_PHRASE_BUFFER_SIZE)

Largest acceptable record.

MIN_ENTRY_SIZE

#define MIN_ENTRY_SIZE   (sizeof(WeatherDBEntryV3))

Smallest acceptable record, a legacy v3 record.

WEATHER_DB_CURRENT_MINOR_VERSION

#define WEATHER_DB_CURRENT_MINOR_VERSION   (5)

Newest minor version of the v4 schema understood by the firmware.

WEATHER_DB_CURRENT_VERSION

#define WEATHER_DB_CURRENT_VERSION   (4)

Current major version of the record schema.

WEATHER_DB_HOURLY_COUNT

#define WEATHER_DB_HOURLY_COUNT   (24)

Hours of hourly data in a v4 series (one day, keeps the record small).

WEATHER_DB_LEGACY_VERSION

#define WEATHER_DB_LEGACY_VERSION   (3)

Major version of the legacy record schema.

WEATHER_DB_MAX_FORECAST_DAYS

#define WEATHER_DB_MAX_FORECAST_DAYS   (7)

Days of daily forecast in a v4 record (today + 6).

WEATHER_DB_V4_0_FIXED_SIZE

#define WEATHER_DB_V4_0_FIXED_SIZE   (offsetof(WeatherDBEntry, location_utc_offset_min))

Fixed size of a v4.0 record, the minimum of any v4 record and where its strings start.

WEATHER_DB_V4_1_FIXED_SIZE

#define WEATHER_DB_V4_1_FIXED_SIZE   (offsetof(WeatherDBEntry, today_wmo_code))

Fixed size of a v4.1 record, where its strings start.

WEATHER_DB_V4_2_FIXED_SIZE

#define WEATHER_DB_V4_2_FIXED_SIZE   (offsetof(WeatherDBEntry, today_wind_dir_deg))

Fixed size of a v4.2 record, where its strings start.

WEATHER_DB_V4_3_FIXED_SIZE

#define WEATHER_DB_V4_3_FIXED_SIZE   (offsetof(WeatherDBEntry, today_hourly_uv_x10))

Fixed size of a v4.3 record, where its strings start.

WEATHER_DB_V4_4_FIXED_SIZE

#define WEATHER_DB_V4_4_FIXED_SIZE   (offsetof(WeatherDBEntry, tomorrow_hourly_count))

Fixed size of a v4.4 record, where its strings start.

WEATHER_DB_V4_FIXED_SIZE

#define WEATHER_DB_V4_FIXED_SIZE   (offsetof(WeatherDBEntry, pstring16s))

Fixed size of a current (v4.5) record, everything but the trailing strings.

Typedef Documentation

WeatherDBIteratorCallback

typedef void(* WeatherDBIteratorCallback) (WeatherDBKey *key, WeatherDBEntry *entry, void *context)

Callback of weather_db_for_each().

Parameters

key	Location UUID; only valid during the call.
entry	Record, possibly a v3 record; only valid during the call.
context	User data.

WeatherDBKey

typedef Uuid WeatherDBKey

Record key, the location UUID.

Enumeration Type Documentation

WeatherDbStringIndex

enum WeatherDbStringIndex

Index of the strings in a record's pstring16s.

Enumerator
WeatherDbStringIndex_LocationName	Location name.
WeatherDbStringIndex_ShortPhrase	Short description of the conditions.
WeatherDbStringIndexCount	Number of strings.

Function Documentation

weather_db_compact()

status_t weather_db_compact

(

void

)

Compact the settings file backing the weather database.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_delete()

status_t weather_db_delete	(	const uint8_t *	key,
		int	key_len
	)

Delete a record from the weather database.

The key is the location UUID. Returns E_RANGE when the phone does not support the weather service, so it stops sending records.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_entry_get_strings()

static struct pbl_serialized_array * weather_db_entry_get_strings ( WeatherDBEntry *  entry )

inlinestatic

Locate the trailing strings of a record.

Use this instead of &entry->pstring16s, which is only valid for current minor records.

Parameters

entry

Record of any supported version.

Returns

Pointer to the pstring16s array.

References WeatherDBEntry::minor_version, WeatherDBEntry::version, WEATHER_DB_CURRENT_VERSION, and weather_db_entry_strings_offset().

weather_db_entry_is_supported()

static bool weather_db_entry_is_supported ( const WeatherDBEntry *  entry )

inlinestatic

Check whether the firmware can parse a record.

A v4 record with a minor newer than WEATHER_DB_CURRENT_MINOR_VERSION is rejected: a newer minor appends fixed fields, which moves the trailing strings.

Parameters

entry

Record.

Returns

true if supported.

References WeatherDBEntry::minor_version, WeatherDBEntry::version, WEATHER_DB_CURRENT_MINOR_VERSION, WEATHER_DB_CURRENT_VERSION, and weather_db_version_is_supported().

weather_db_entry_strings_offset()

static size_t weather_db_entry_strings_offset ( uint8_t  version, uint8_t  minor_version  )

inlinestatic

Get the offset of the trailing strings for a record version.

Each minor places them differently: at the first field the next minor appends.

Parameters

version	Major version.
minor_version	Minor version, ignored for v3.

Returns

Byte offset of the pstring16s array.

References WEATHER_DB_CURRENT_VERSION, WEATHER_DB_V4_0_FIXED_SIZE, WEATHER_DB_V4_1_FIXED_SIZE, WEATHER_DB_V4_2_FIXED_SIZE, WEATHER_DB_V4_3_FIXED_SIZE, and WEATHER_DB_V4_4_FIXED_SIZE.

Referenced by weather_db_entry_get_strings().

weather_db_flush()

status_t weather_db_flush

(

void

)

Delete all records of the weather database.

Returns E_RANGE when the phone does not support the weather service, so it stops sending records.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_for_each()

status_t weather_db_for_each	(	WeatherDBIteratorCallback	cb,
		void *	context
	)

Call a function for every supported record.

The database is locked during the iteration.

Parameters

cb	Callback.
context	User data passed to cb.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_get_len()

int weather_db_get_len	(	const uint8_t *	key,
		int	key_len
	)

Get the length of a record in the weather database.

The key is the location UUID.

Parameters

key	Key data.
key_len	Length of key in bytes.

Returns

Length of the value in bytes, 0 if not found, or a negative error code.

weather_db_init()

void weather_db_init

(

void

)

Initialize the weather database.

weather_db_insert()

status_t weather_db_insert	(	const uint8_t *	key,
		int	key_len,
		const uint8_t *	val,
		int	val_len
	)

Insert or replace a record in the weather database.

The key is the location UUID and the value a v3 or v4 record, bounds-checked against its version. Returns E_RANGE when the phone does not support the weather service, so it stops sending records.

Parameters

key	Key data.
key_len	Length of key in bytes.
val	Value data.
val_len	Length of val in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_read()

status_t weather_db_read	(	const uint8_t *	key,
		int	key_len,
		uint8_t *	val_out,
		int	val_out_len
	)

Read a record from the weather database.

The key is the location UUID. Unsupported records are deleted and reported as E_DOES_NOT_EXIST.

Parameters

	key	Key data.
	key_len	Length of key in bytes.
[out]	val_out	Buffer for the value.
	val_out_len	Size of val_out in bytes.

Returns

S_SUCCESS on success, an error code otherwise.

weather_db_version_is_supported()

static bool weather_db_version_is_supported ( uint8_t  version )

inlinestatic

Check whether the firmware can parse a major version.

Parameters

version

Major version.

Returns

true for WEATHER_DB_CURRENT_VERSION and WEATHER_DB_LEGACY_VERSION.

References WEATHER_DB_CURRENT_VERSION, and WEATHER_DB_LEGACY_VERSION.

Referenced by weather_db_entry_is_supported().