Pular para o conteúdo
ThingFace

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_tO que éExemplo
time_zoneo nome IANA do fuso, de 1 a 64 caracteres (a placa não tem a base IANA)America/Sao_Paulo
posix_tzo mesmo fuso como regra POSIX do TZ, de 1 a 64 caracteres<-03>3, EST5EDT,M3.2.0,M11.1.0
localea etiqueta de idioma da conta, de 2 a 35 caracterespt-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, &lt); /* já no fuso da conta */
}
  • DEVUI_EV_PREFS vem quando um dos três muda, a primeira vez também; quando ele chega, o SDK já guardou as preferências e já aplicou o TZ. Com prefs NULL, a placa foi para o limbo (desvinculada, também enquanto estava desligada, ou revendida): o SDK apagou as preferências do dono anterior, e o TZ voltou ao do firmware.
  • devui_get_prefs(&p) responde ESP_OK com as guardadas, também sem nuvem e de dentro de um callback; ESP_ERR_NOT_FOUND quando a placa ainda não as recebeu, depois do limbo ou do devui_factory_reset(), ou antes do devui_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/env da placa diz o locale e o time_zone da conta (ou null), 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.