Preferências da conta: fuso e idioma
A placa sabe o fuso horário e o idioma da conta dona sem nada disso no firmware. A nuvem manda as preferências da conta (o fuso IANA, a regra POSIX dele e o idioma) a cada conexão com dono e de novo quando o dono as troca no portal. O SDK as guarda na NVS e, por padrão, aplica a regra com setenv("TZ", …) e tzset(): daí em diante, localtime() e strftime() já saem no fuso da conta, também num boot sem nuvem. O exemplo é o examples/hora-local.
O que chega
Campo de devui_prefs_t | O que é | Exemplo |
|---|---|---|
time_zone | o nome IANA do fuso, de 1 a 64 caracteres (a placa não tem a base IANA) | America/Sao_Paulo |
posix_tz | o mesmo fuso como regra POSIX do TZ, de 1 a 64 caracteres | <-03>3, EST5EDT,M3.2.0,M11.1.0 |
locale | a etiqueta de idioma da conta, de 2 a 35 caracteres | pt-BR, en |
São sempre as preferências da conta dona: quem opera a placa por convite vê o próprio fuso na interface, mas a placa segue o do dono. Cada texto termina em NUL e foi conferido pelo SDK; um conjunto fora das regras (uma regra POSIX fora da gramática) é recusado, e nada muda.
No firmware
O app fica sabendo pelo evento DEVUI_EV_PREFS e lê as guardadas com devui_get_prefs():
static void on_event(const devui_event_t *ev, void *ctx)
{
if (ev->type == DEVUI_EV_PREFS) {
if (ev->prefs) {
printf("fuso %s (regra %s), idioma %s\n", ev->prefs->time_zone, ev->prefs->posix_tz, ev->prefs->locale);
} else {
printf("sem dono: o TZ voltou ao do firmware\n");
}
}
}
/* depois do devui_start, com nuvem ou sem */
devui_prefs_t p;
if (devui_get_prefs(&p) == ESP_OK) {
time_t t = time(NULL);
struct tm lt;
localtime_r(&t, <); /* já no fuso da conta */
}
DEVUI_EV_PREFSvem quando um dos três muda, a primeira vez também; quando ele chega, o SDK já guardou as preferências e já aplicou oTZ. ComprefsNULL, a placa foi para o limbo (desvinculada, também enquanto estava desligada, ou revendida): o SDK apagou as preferências do dono anterior, e oTZvoltou ao do firmware.devui_get_prefs(&p)respondeESP_OKcom as guardadas, também sem nuvem e de dentro de um callback;ESP_ERR_NOT_FOUNDquando a placa ainda não as recebeu, depois do limbo ou dodevui_factory_reset(), ou antes dodevui_start.- O relógio é o que o SDK acerta pela hora da nuvem (
DEVUI_EV_CLOCK_SET), ou o SNTP do app. O fuso só diz como mostrar a hora. - No modo local, o
/_devui/envda placa diz olocalee otime_zoneda conta (ounull), para a interface servida na rede local (Modo local).
Fuso manual
devui_config_t.manual_tz = true: o SDK nunca mexe no TZ, e o app faz o que quiser com devui_prefs_t.posix_tz (um fuso próprio do produto, um menu na tela). O evento e o devui_get_prefs continuam iguais.
Com manual_tz = false (o padrão), quando as preferências vão embora (o limbo, o devui_factory_reset()), o TZ volta ao que o firmware tinha antes de o SDK mexer nele, ou a UTC se ele não tinha nenhum.
Uma regra que a placa lê errado
Uma regra que a newlib do ESP-IDF lê errado não é aplicada. Medido num ESP32-S3 com o ESP-IDF 5.5.5, contra todas as transições de 2027 da tzdata 2026f: as horas de transição acima de 24 (/26 de Asia/Jerusalem, /50 de Asia/Gaza) saem certas, e a hora com sinal (/-1 de America/Nuuk) sai errada. Para um fuso assim, o TZ fica o do firmware (UTC, se ele não tem um) e um aviso vai para o log; as preferências chegam ao app do mesmo jeito.
Com uma nuvem ou um SDK de antes
O SDK anuncia que conhece as preferências no HELLO; uma nuvem que não as manda deixa a placa sem elas (devui_get_prefs responde ESP_ERR_NOT_FOUND) e o TZ como o firmware o deixou. Um SDK anterior não as anuncia, e a nuvem não as manda a ele (Compatibilidade).
Na biblioteca Arduino, a leitura é DevUI.getPrefs(&p), e o evento chega pelo DevUI.onEvent (A biblioteca Arduino). O binding Rust ainda não tem as preferências: o evento chega como Event::Other(17), e o SDK aplica o TZ como no C, por padrão. A referência completa: devui_get_prefs e devui_prefs_t.
