Protocol Buffers

A TechFab oferece um serviço de infraestrutura gerenciada e uma API GraphQL que você pode conferir aqui, para se comunicar com dispositivos de forma transparente. Mas se mesmo assim a sua empresa escolher gerenciar a própria infraestrutura, você precisará se comunicar com os dispositivos através de Protocol Buffers (ou simplesmente protobuf), que é um protocolo padrão de indústria para serialização de dados em binário.

Se você não conhece protobuf, pode saber mais no site oficial.

Codificação e decodificação de mensagens

Para codificar e decodificar mensagens protobuf, é necessário possuir o esquema dos dados em arquivos .proto, que podem ser encontrados no repositório dedicado no GitHub. Além disso, os dados precisam passar por um processo de normalização, pois frequentemente são aplicadas técnicas para reduzir o binário trafegado.

Cada linguagem de programação possui sua implementação de protobuf. Confira a documentação de cada uma para saber mais sobre codificação e decodificação de mensagens. Este guia abordará as particularidades de cada tipo de mensagem, e como ocorre a normalização dos dados.

Decodificando telemetria

Chamamos de telemetria os dados enviados pelos dispositivos. Estes dados são mensagens do tipo TelemetryPack.

TelemetryPack envia várias medições através do campo records, que é uma lista de mensagens do tipo Record.

Record possui os seguntes campos:

resource: tipo de recurso como temperatura, umidade, tensão, corrente, etc. Confira o enum Resource para conhecer todos os recursos possíveis.
time: Unix timestamp em que a medição foi realizada. Caso seja entre 0 e 2²⁸ (268.435.456), representa quantos segundos se passaram relativo a base_time em TelemetryPack.
value: valor de medidas numéricas, tanto de números inteiros como decimais.
int_value: valor de medidas de números inteiros. Similar ao value, porém utilizado para economizar banda.
bool_value: valor de medidas booleanas. Exemplo: switch, que representa o estado ligado ou desligado.
string_value: valor de medidas em texto, como log.
data_value: valor de medidas em dados binários.
severity: nível de urgência da mensagem. Medições acima de 0 são consideradas anomalias. Confira o enum Severity para saber todos os valores possíveis.
alert_id: identificador da mensagem de alerta emitido. Costuma vir em mensagens com severity acima de 0. Confira a tabela de alert IDs disponível na documentação do seu produto.

name e unit são usados apenas para fins de desenvolvimento em produtos onde é possível personalizar o firmware.

Além de records, TelemetryPack também possui os seguintes campos:

base_resource: os registros do pacote que não possuem resource definido usam este valor como alternativa.
base_time: Unix timestamp de referência para todos os registros do TelemetryPack que possuem tempo relativo, ou seja, time entre 0 e 2²⁸ (268.435.456).

Exemplo: um TelemetryPack tem base_time: 1713881407. Se um record tem time: 60, o time normalizado será 1713881467. Já se um record tem time: 1713880051, o time normalizado será ele mesmo, 1713880051.

Se o base_time também for entre 0 e 2²⁸ (268.435.456), é considerado relativo ao tempo atual. É apenas usado em redes de baixa latência.

base_name e base_unit são usados apenas para fins de desenvolvimento em produtos onde é possível personalizar o firmware.

Codificando comandos

Chamamos de comandos os dados enviados para os dispositivos. Estes dados são mensagens do tipo CommandPack.

Os comandos costumam ser bastante particulares para cada dispositivo e qual ação você deseja realizar. Consulte a documentação do seu dispositivo para saber mais.