9.16. Tempo e NTP

Uma câmera recém-ligada não faz ideia de que horas são. O relógio interno começa em algum instante arbitrário (1970-01-01 na maioria das placas) e conta a partir daí até que algo lhe diga o contrário. O NTP – o Network Time Protocol – é como a câmera pede à rede a hora real do mundo (wall-clock) e ajusta seu próprio relógio com base na resposta.

9.16.1. Por que a câmera precisa saber a hora

Para muitos scripts o relógio da câmera não importa – um laço de captura de quadros não se importa com o dia em que está. Para algumas situações comuns, porém, importa muito:

  • Timestamps em logs ou em dados enviados. Entradas que dizem todas 1970-01-01 são difíceis de interpretar depois.

  • Tarefas agendadas. “Executar às 03:00” exige que a câmera saiba o que são 03:00.

9.16.2. O que o NTP faz

O NTP é um pequeno serviço público: uma rede de servidores que respondem “que horas são?” por meio de uma única troca UDP. A câmera envia uma requisição curta a um servidor NTP conhecido; o servidor responde com um timestamp preciso (com exatidão de poucos milissegundos para qualquer servidor público comum); a câmera usa isso para ajustar seu próprio relógio. O servidor padrão que a câmera usa é pool.ntp.org, um pool com balanceamento de carga global projetado exatamente para esse tipo de cliente.

9.16.3. A API Python: ntptime

O MicroPython encapsula o protocolo em uma única chamada. O padrão comum é primeiro estabelecer o enlace e depois pedir a hora ao NTP:

import network
import ntptime
import time

wlan = network.WLAN(network.WLAN.IF_STA)
wlan.active(True)
wlan.connect("my-network", "my-password")

while not wlan.isconnected():
    time.sleep_ms(100)

ntptime.settime()                 # cam's clock is now UTC
print(time.localtime())

Depois que ntptime.settime() retorna, o relógio de tempo real interno e time.localtime() refletem a hora UTC atual. Dois parâmetros ajustam os padrões:

  • ntptime.host é o nome do servidor a consultar. Sobrescreva-o (ntptime.host = "time.google.com") antes de chamar settime() para apontar para um servidor diferente.

  • ntptime.timeout é o número de segundos a aguardar por uma resposta antes de desistir; o padrão é curto.

9.16.4. Quando chamá-la

  • Após o enlace de rede estar ativo. O NTP roda sobre UDP, que roda sobre uma configuração IP estabelecida. Aguarde primeiro isconnected() retornar True.

  • Periodicamente em câmeras de longa execução. O relógio interno deriva ao longo de horas e dias. Um settime() diário ou semanal o mantém preciso.

9.16.5. Fusos horários

O NTP retorna UTC. O MicroPython não inclui um banco de dados de fusos horários, então converter UTC para a hora local é tarefa do script. Um deslocamento fixo para o fuso da implantação é a abordagem usual:

import time

offset = -5 * 3600                  # hours -> seconds, US Eastern
local = time.localtime(time.time() + offset)
print(local)

O Horário de Verão, os segundos bissextos e as mudanças históricas de fuso não são tratados por essa abordagem. Para a maioria das implantações de câmera um deslocamento fixo é suficiente; se um script realmente precisar de hora civil com Horário de Verão, faça a conversão no lado do servidor.

9.16.6. O que pode dar errado

  • Rede ainda não disponível. ntptime.settime() levanta OSError se não conseguir alcançar o servidor. Ou o enlace não está ativo, ou a resolução de nome falhou, ou o servidor está inacessível, ou nenhuma resposta chegou dentro de ntptime.timeout. Tente novamente assim que o enlace estiver estável.

  • Portais cativos. Uma rede Wi-Fi que intercepta o DNS pode responder o nome do servidor NTP com o próprio IP do portal, e as requisições NTP enviadas a ele retornam dados sem sentido. A câmera vai achar que a rede está ativa, mas o ajuste da hora falhará ou ficará completamente errado. Mude para uma rede limpa ou fixe um IP no código.

  • Sobrecarregar pools públicos. Os pools NTP públicos limitam a taxa de clientes abusivos. Uma vez por hora é mais que suficiente; uma vez por minuto fará a câmera ser banida.

Para a referência completa de ntptime, veja ntptime — cliente NTP simples.