Payload Parser*

*Ainda estamos trabalhando nisso!

Visão Geral

O Payload Parser é um componente essencial na integração de dispositivos IoT, pois sensores ou fontes de dados externas transmitem dados em diversos formatos como binário, hexadecimal, JSON e outros. Sua principal função é decodificar os payloads brutos e convertê-los em um Valeiot Data Point. Isso garante que os dados de qualquer sensor ou componente externo possam ser facilmente interpretados, armazenados e utilizados dentro da plataforma, como ilustrado no diagrama abaixo.

O Payload Parser é um script em JavaScript, que processa os dados recebidos dos sensores e os converte em valores legíveis. O script segue as especificações do protocolo definidas pela documentação do fabricante do hardware, para decodificar corretamente os campos de dados.

Características Principais (TO DO)

• Linguagem suportada: JavaScript
• Variáveis de ambiente: Ainda estamos trabalhando nisso!
• Bibliotecas integradas: Ainda estamos trabalhando nisso!

Casos de Uso

• Decodificação de Dados: O Payload Parser decodifica os payloads brutos transmitidos por sensores ou fontes de dados externas, convertendo dados binários ou hexadecimais em valores significativos como latitude, longitude, voltagem da bateria, velocidade e outras métricas do dispositivo.
• Normalização de Valeiot Data Point: Ajuste de JSONs personalizados para conformidade com a estrutura do Valeiot Data Point, garantindo inserção bem-sucedida nos Data Sources.
• Flexibilidade: Capacidade de lidar com diferentes tipos de mensagens de uplink e permitir processamento customizado antes da inserção no Data Source.
• Tratamento de Erros: Detecção e tratamento de formatos de dados inesperados, garantindo robustez mesmo em casos de dados corrompidos ou incompletos.
• Personalização: O parser pode ser adaptado para atender a requisitos específicos, como ignorar determinados pontos de dados ou adicionar metadados adicionais aos dados decodificados.

Estrutura do Payload Parser

O Payload Parser deve conter obrigatoriamente uma função de entrada chamada parse, executada sempre que uma requisição for enviada. Essa função recebe como parâmetro o payload, que contém a mensagem da requisição. Ao final, ela deve retornar um array de Valeiot Data Points.

function parse(payload) {
  let dataList = [];

  // sua lógica vai aqui

  return dataList;
}

Exemplo

Abaixo está um exemplo de um Payload Parser baseado em JavaScript, que decodifica o payload enviado do dispositivo e o converte em Valeiot Data Points:

parserExample.js

function parse(payload) {
  let dataList = [];

  if (typeof payload === "string") {
    const buffer = hexToUint8Array(payload);

    if (buffer[0]) {
      const batteryValue = buffer[0];
      dataList.push({
        variable: "battery",
        value: batteryValue,
      });
    }

    if (buffer[1]) {
      const temperatureValue = buffer[1];
      dataList.push({
        variable: "temperature",
        value: temperatureValue,
      });
    }

    if (buffer[3]) {
      const doorBit = buffer[3] & 0x08;
      let doorState = "";
      if (doorBit > 0x00) {
        doorState = "Closed";
      } else {
        doorState = "Open";
      }
      dataList.push({
        variable: "door_state",
        value: doorState,
      });
    }

    dataList = dataList.concat({ variable: "payload", value: payload });
  } else {
    dataList = dataList.concat(payload);
  }

  const ignoreVars = ["snr", "rssi", "gateway_eui", "fcnt", "fport"];
  dataList = dataList.filter((x) => !ignoreVars.includes(x.variable));

  return dataList;
}

O parser espera um payload como entrada, usando o seguinte exemplo de payload:

"621b6310";

O resultado esperado são os data points:

[
  { variable: "battery", value: 98 },
  { variable: "temperature", value: 27 },
  { variable: "position_state", value: "Open" },
  { variable: "payload", value: "621b6310" },
];

Explicação

O processo de decodificação é livre - você pode fazer basicamente o que quiser com JavaScript. Para o exemplo mencionado, o script decodifica a bateria, temperatura e estado da porta a partir do payload. Ele converte de hexadecimal para decimal e aplica uma simples operação de bitmask. Também remove algumas variáveis indesejadas como snr, rssi, gateway_eui, fcnt e fport.

function parse(payload) {
  let dataList = [];

  if (typeof payload === "string") {
    const buffer = hexToUint8Array(payload);

    if (buffer[0]) {
      const batteryValue = buffer[0];
      dataList.push({
        variable: "battery",
        value: batteryValue,
      });
    }

    if (buffer[1]) {
      const temperatureValue = buffer[1];
      dataList.push({
        variable: "temperature",
        value: temperatureValue,
      });
    }

    if (buffer[3]) {
      const doorBit = buffer[3] & 0x08;
      let doorState = "";
      if (doorBit > 0x00) {
        doorState = "Closed";
      } else {
        doorState = "Open";
      }
      dataList.push({
        variable: "door_state",
        value: doorState,
      });
    }

    dataList = dataList.concat({ variable: "payload", value: payload });
  } else {
    dataList = dataList.concat(payload);
  }

  const ignoreVars = ["snr", "rssi", "gateway_eui", "fcnt", "fport"];
  dataList = dataList.filter((x) => !ignoreVars.includes(x.variable));

  return dataList;
}

A calculadora abaixo mostra os valores hexadecimal e binário.

Bateria: 0110 0010 ou 0x62 ou 98

Temperatura: 0001 1011 ou 0x1B ou 27

Estado da Porta: 0001 0000 que é 0x10 quando operado 0x10 & 0x08 o resultado é 0x00

  00010000   (0x10)
& 00001000   (0x08)
  --------
  00000000   (Result)

Este exemplo demonstra como o Payload Parser pode ser usado para decodificar dados do dispositivo e convertê-los no formato Valeiot Data Point.