Contrato MQTT

O contrato público de código está em packages/mqtt/src/contract.ts. O broker distribui mensagens; este pacote valida como as aplicações representam telemetria.

Tópico

telemetry/{deviceType}/{externalId}

São exatamente três segmentos. As duas partes variáveis devem ser kebab-case não vazio, sem curingas MQTT. Exemplo fictício:

telemetry/solis-inverter/exemplo-01

A identidade do coletor é derivada por identity.ts. Não usar números de série reais em páginas ou fixtures públicas.

Payload

{
  "ts": "2026-10-06T12:00:00Z",
  "metrics": {
    "power_w": 1200,
    "energy_today_kwh": 4.2
  }
}

Exemplo inventado para estudo. Não é uma leitura do campus.

Campo	Regra
ts	Opcional; data ISO 8601 com offset válida
metrics	Objeto obrigatório, não vazio
Chave de métrica	snake_case começando com letra minúscula
Valor	Número finito; não texto, null ou infinito
Campos adicionais	Rejeitados pelo schema strict

Sem ts, a preparação usa receivedAt como aproximação. O contrato valida formato, não a plausibilidade elétrica, a calibração ou a autorização de qualquer hardware.

Publicação e assinatura

publishTelemetry valida antes de enviar com QoS 1. subscribeTelemetry assina telemetry/# com QoS 1, interpreta o texto e entrega a variante válida ou inválida ao handler.

QoS 1 admite repetições. O contrato não deduplica e a persistência não garante exactly-once.

Unidades conhecidas pelo sufixo

_kwh, _kw, _wm2, _w, _v, _a, _hz, _c e _pct são reconhecidos. Ordem e sufixo importam. Uma chave nova pode ser válida mesmo sem unidade reconhecida; nesses casos, decidir a unidade explicitamente.

Para entender a conversão da mensagem em registros, veja preparação.

Revisão: 06/10/2026. Base: contract.ts, publisher.ts, subscriber.ts e identity.ts. Exemplos não devem ser enviados a um broker real sem autorização.