Skip to content
ThingFace

The account's preferences: time zone and language

The board knows the time zone and the language of its owner account with none of it in the firmware. The cloud sends the account's preferences (the IANA zone, its POSIX rule and the language) at each connection with an owner and again when the owner changes them in the portal. The SDK keeps them in the NVS and, by default, applies the rule with setenv("TZ", …) and tzset(): from then on, localtime() and strftime() already give the account's time zone, also at a boot with no cloud. The example is examples/hora-local (in Portuguese).

What comes

Field of devui_prefs_tWhat it isExample
time_zonethe zone's IANA name, 1 to 64 characters (the board has no IANA database)America/Sao_Paulo
posix_tzthe same zone as a POSIX TZ rule, 1 to 64 characters<-03>3, EST5EDT,M3.2.0,M11.1.0
localethe account's language tag, 2 to 35 characterspt-BR, en

They are always the owner account's preferences: whoever operates the board by invitation sees their own time zone in the interface, but the board follows the owner's. Each text ends in NUL and was checked by the SDK; a set out of the rules (a POSIX rule out of the grammar) is refused, and nothing changes.

In the firmware

The app learns of them by the event DEVUI_EV_PREFS and reads the kept ones with devui_get_prefs():

static void on_event(const devui_event_t *ev, void *ctx)
{
    if (ev->type == DEVUI_EV_PREFS) {
        if (ev->prefs) {
            printf("zone %s (rule %s), language %s\n", ev->prefs->time_zone, ev->prefs->posix_tz, ev->prefs->locale);
        } else {
            printf("no owner: TZ is back to the firmware's\n");
        }
    }
}

/* after devui_start, with the cloud or without it */
devui_prefs_t p;
if (devui_get_prefs(&p) == ESP_OK) {
    time_t t = time(NULL);
    struct tm lt;
    localtime_r(&t, &lt); /* already in the account's zone */
}
  • DEVUI_EV_PREFS comes when one of the three changes, the first time too; when it comes, the SDK has already kept the preferences and applied TZ. With prefs NULL, the board went to the limbo (unlinked, also while it was off, or sold): the SDK erased the former owner's preferences, and TZ is back to the firmware's.
  • devui_get_prefs(&p) answers ESP_OK with the kept ones, also with no cloud and from inside a callback; ESP_ERR_NOT_FOUND when the board has not got them yet, after the limbo or devui_factory_reset(), or before devui_start.
  • The clock is the one the SDK sets from the cloud's time (DEVUI_EV_CLOCK_SET), or the app's SNTP. The time zone only says how to show the time.
  • In the local mode, the board's /_devui/env says the account's locale and time_zone (or null), for the interface served on the local network (Local mode).

Manual time zone

devui_config_t.manual_tz = true: the SDK never touches TZ, and the app does what it wants with devui_prefs_t.posix_tz (a zone of the product's own, a menu on the display). The event and devui_get_prefs stay the same.

With manual_tz = false (the default), when the preferences go (the limbo, devui_factory_reset()), TZ goes back to what the firmware had before the SDK touched it, or to UTC if it had none.

A rule the board reads wrong

A rule that ESP-IDF's newlib reads wrong is not applied. Measured on an ESP32-S3 with ESP-IDF 5.5.5, against every transition of 2027 of the tzdata 2026f: transition hours above 24 (/26 of Asia/Jerusalem, /50 of Asia/Gaza) come out right, and the signed hour (/-1 of America/Nuuk) comes out wrong. For such a zone, TZ stays the firmware's (UTC, if it has none) and a warning goes to the log; the preferences reach the app all the same.

With an earlier cloud or SDK

The SDK announces in the HELLO that it knows the preferences; a cloud that does not send them leaves the board without them (devui_get_prefs answers ESP_ERR_NOT_FOUND) and TZ as the firmware left it. An earlier SDK does not announce them, and the cloud does not send them to it (Compatibility).

In the Arduino library, the reading is DevUI.getPrefs(&p), and the event comes through DevUI.onEvent (The Arduino library). The Rust binding does not have the preferences yet: the event comes as Event::Other(17), and the SDK applies TZ as in C, by default. The whole reference: devui_get_prefs and devui_prefs_t.