Use a ponte de dispositivo do IoT Central para conectar outras nuvens IoT ao IoT Central

Artigo
10/27/2023

A ponte de dispositivo do IoT Central é uma solução de código aberto que conecta outras nuvens de IoT, como Sigfox, Particle Device Cloud e The Things Network, ao seu aplicativo IoT Central. A ponte de dispositivo funciona encaminhando dados de dispositivos conectados a outras nuvens IoT para seu aplicativo IoT Central. A ponte do dispositivo apenas encaminha dados para o IoT Central, não envia comandos ou atualizações de propriedade do IoT Central de volta para os dispositivos.

A ponte de dispositivo permite combinar o poder do IoT Central com dispositivos como:

Dispositivos de rastreamento de ativos conectados à rede de área ampla de baixa potência da Sigfox.
Dispositivos de monitorização da qualidade do ar na nuvem de dispositivos de partículas.
Dispositivos de monitorização da humidade do solo na The Things Network.

Você pode usar recursos de aplicativo do IoT Central, como regras e análises nos dados, criar fluxos de trabalho nos aplicativos Power Automate e Azure Logic ou exportar os dados.

A solução de ponte de dispositivo provisiona vários recursos do Azure em sua assinatura do Azure que trabalham juntos para transformar e encaminhar mensagens de dispositivo para o IoT Central.

Pré-requisitos

Para concluir as etapas neste guia de instruções, você precisa:

Uma subscrição ativa do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
Um aplicativo IoT Central criado a partir do modelo de aplicativo personalizado. Para saber mais, consulte Criar um aplicativo do IoT Central e Sobre seu aplicativo.

Descrição geral

A ponte de dispositivo IoT Central é uma solução de código aberto no GitHub. Ele usa um modelo personalizado do Azure Resource Manager para implantar vários recursos em sua assinatura do Azure, incluindo um aplicativo de função no Azure Functions.

O aplicativo de função é a peça central da ponte do dispositivo. Ele recebe solicitações HTTP POST de outras plataformas IoT por meio de um webhook simples. O repositório do Azure IoT Central Device Bridge inclui exemplos que mostram como conectar as nuvens Sigfox, Partícula e The Things Network. Você pode estender essa solução para se conectar à sua nuvem IoT personalizada se sua plataforma puder enviar solicitações HTTP POST para seu aplicativo de função.

O aplicativo de função transforma os dados em um formato aceito pelo IoT Central e os encaminha usando o serviço de provisionamento de dispositivo e as APIs de cliente de dispositivo:

Screenshot of an Azure Functions definition showing the code.

Se seu aplicativo IoT Central reconhecer o ID do dispositivo na mensagem encaminhada, a telemetria do dispositivo aparecerá no IoT Central. Se o seu aplicativo IoT Central não reconhecer a ID do dispositivo, o aplicativo de função tentará registrar um novo dispositivo com a ID do dispositivo. O novo dispositivo aparece como um dispositivo não atribuído na página Dispositivos do seu aplicativo IoT Central. Na página Dispositivos, você pode atribuir o novo dispositivo a um modelo de dispositivo e, em seguida, exibir a telemetria.

Implantar a ponte de dispositivo

Para implantar a ponte de dispositivo na sua assinatura:

Em seu aplicativo IoT Central, navegue até a página Grupos de conexão de Dispositivo de Permissões>.
1. Anote o escopo da ID. Você usa esse valor ao implantar a ponte de dispositivo.
2. Na mesma página, abra o grupo de inscrição SAS-IoT-Devices . Na página do grupo SAS-IoT-Devices , copie a chave primária. Você usa esse valor ao implantar a ponte de dispositivo.
Use o seguinte botão Implantar no Azure para abrir o modelo personalizado do Gerenciador de Recursos que implanta o aplicativo de função em sua assinatura. Use o Escopo da ID e a Chave primária da etapa anterior:

Após a conclusão da implantação, você precisa instalar os pacotes npm que a função requer:

No portal do Azure, abra o aplicativo de função que foi implantado em sua assinatura. Em seguida, vá para o Console de Ferramentas de>Desenvolvimento. No console, execute os seguintes comandos para instalar os pacotes:
```
cd IoTCIntegration
npm install
```
Esses comandos podem levar vários minutos para serem executados. Você pode ignorar com segurança todas as mensagens de aviso.
Após a conclusão da instalação do pacote, selecione Reiniciar na página Visão geral do aplicativo de função:
A função está agora pronta a utilizar. Os sistemas externos podem usar solicitações HTTP POST para enviar dados do dispositivo através da ponte do dispositivo para seu aplicativo IoT Central. Para obter o URL da função, navegue até Functions > IoTCIntegration > Code + Test > Get function URL:

Os corpos das mensagens enviadas para a ponte do dispositivo devem ter o seguinte formato:

"device": {
  "deviceId": "my-cloud-device"
},
"measurements": {
  "temp": 20.31,
  "pressure": 50,
  "humidity": 8.5,
  "ledColor": "blue"
}

Cada chave no objeto deve corresponder ao measurements nome de um tipo de telemetria no modelo de dispositivo no aplicativo IoT Central. Esta solução não suporta a especificação do ID da interface no corpo da mensagem. Portanto, se duas interfaces diferentes tiverem um tipo de telemetria com o mesmo nome, a medição aparecerá em ambos os fluxos de telemetria em seu aplicativo IoT Central.

Você pode incluir um timestamp campo no corpo para especificar a data e hora UTC da mensagem. Este campo deve estar no formato ISO 8601. Por exemplo, 2020-06-08T20:16:54.602Z. Se você não incluir um carimbo de data/hora, a data e a hora atuais serão usadas.

Você pode incluir um modelId campo no corpo. Use este campo para atribuir o dispositivo a um modelo de dispositivo durante o provisionamento.

O deviceId deve ser alfanumérico, minúsculo e pode conter hífenes.

Se você não incluir o campo ou se o modelId IoT Central não reconhecer a ID do modelo, uma mensagem com um não reconhecido deviceId criará um novo dispositivo não atribuído no IoT Central. Um operador pode migrar manualmente o dispositivo para o modelo de dispositivo correto. Para saber mais, consulte Gerenciar dispositivos em seu aplicativo > do Azure IoT Central Migrando dispositivos para um modelo.

Nota

Até que o dispositivo seja atribuído a um modelo, todas as chamadas HTTP para a função retornam um status de erro 403.

Para ativar o registro em log para o aplicativo de função com o Application Insights, navegue até Logs de Monitoramento > em seu aplicativo de função no portal do Azure. Selecione Ativar Application Insights.

Recursos provisionados

O modelo do Resource Manager provisiona os seguintes recursos em sua assinatura do Azure:

Aplicação de funções
Plano do Serviço de Aplicações
Storage account
Key Vault

O cofre de chaves armazena a chave de grupo SAS para seu aplicativo IoT Central.

O aplicativo de função é executado em um plano de consumo. Embora essa opção não ofereça recursos de computação dedicados, ela permite que a ponte de dispositivo lide com centenas de mensagens de dispositivo por minuto, adequado para frotas menores de dispositivos ou dispositivos que enviam mensagens com menos frequência. Se o seu aplicativo depender do streaming de um grande número de mensagens do dispositivo, substitua o plano de consumo por um plano de serviço de aplicativo dedicado. Este plano oferece recursos de computação dedicados, que proporcionam tempos de resposta mais rápidos ao servidor. Usando um Plano de Serviço de Aplicativo padrão, o desempenho máximo observado da função do Azure neste repositório foi de cerca de 1.500 mensagens de dispositivo por minuto. Para saber mais, consulte Opções de hospedagem do Azure Functions.

Para usar um plano dedicado do Serviço de Aplicativo em vez de um plano de consumo, edite o modelo personalizado antes de implantar. Selecione Editar modelo.

Screenshot that shows the edit template option for an Azure Resource Manager template.

Substitua o seguinte segmento:

{
  "type": "Microsoft.Web/serverfarms",
  "apiVersion": "2015-04-01",
  "name": "[variables('planName')]",
  "location": "[resourceGroup().location]",
  "properties": {
    "name": "[variables('planName')]",
    "computeMode": "Dynamic",
    "sku": "Dynamic"
  }
},

com o

{
  "type": "Microsoft.Web/serverfarms",
  "sku": {
      "name": "S1",
      "tier": "Standard",
      "size": "S1",
      "family": "S",
      "capacity": 1
  },
  "kind": "app",
  "name": "[variables('planName')]",
  "apiVersion": "2016-09-01",
  "location": "[resourceGroup().location]",
  "tags": {
      "iotCentral": "device-bridge",
      "iotCentralDeviceBridge": "app-service-plan"
  },
  "properties": {
      "name": "[variables('planName')]"
  }
},

Em seguida, edite o modelo a ser incluído "alwaysOn": true na configuração do functionapp recurso em A configuração alwaysOn garante que o aplicativo de função esteja sempre em "properties": {"SiteConfig": {...}} execução.

Exemplos

Os exemplos a seguir descrevem como configurar a ponte de dispositivo para várias nuvens IoT:

Exemplo 1: Conectando dispositivos de partículas através da ponte de dispositivo

Para conectar um dispositivo Particle através da ponte de dispositivo ao IoT Central, vá para o console Particle e crie uma nova integração webhook. Defina o formato de solicitação como JSON. Em Configurações avançadas, use o seguinte formato de corpo personalizado:

{
  "device": {
    "deviceId": "{{{PARTICLE_DEVICE_ID}}}"
  },
  "measurements": {
    "{{{PARTICLE_EVENT_NAME}}}": "{{{PARTICLE_EVENT_VALUE}}}"
  }
}

Cole a URL da função do seu aplicativo de função e você verá Dispositivos de partículas aparecerem como dispositivos não atribuídos no IoT Central. Para saber mais, consulte a postagem do blog Veja como integrar seus projetos baseados em partículas com o Azure IoT Central .

Exemplo 2: Conectando dispositivos Sigfox através da ponte de dispositivo

Algumas plataformas podem não permitir que você especifique o formato das mensagens do dispositivo enviadas por meio de um webhook. Para esses sistemas, você deve converter a carga útil da mensagem para o formato de corpo esperado antes que a ponte do dispositivo a processe. Você pode fazer a conversão na mesma função que executa a ponte do dispositivo.

Esta seção mostra como converter a carga útil de uma integração de webhook Sigfox para o formato de corpo esperado pela ponte do dispositivo. A nuvem Sigfox transmite dados do dispositivo em um formato de cadeia hexadecimal. Por conveniência, a ponte do dispositivo inclui uma função de conversão para este formato, que aceita um subconjunto dos possíveis tipos de campo em uma carga útil do dispositivo Sigfox: int e de 8, 16, 32 ou 64 bits, de 32 bits ou 64 bitsfloat, little-endian e uint big-endian. Para processar mensagens de uma integração de webhook do Sigfox, faça as seguintes alterações no arquivo IoTCIntegration/index.js no aplicativo de função.

Para converter a carga útil da mensagem, adicione o seguinte código antes da chamada para handleMessage a linha 21, substituindo payloadDefinition pela sua definição de carga útil Sigfox:

const payloadDefinition = 'gforce::uint:8 lat::uint:8 lon::uint:16'; // Replace this with your payload definition

req.body = {
    device: {
        deviceId: req.body.device
    },
    measurements: require('./converters/sigfox')(payloadDefinition, req.body.data)
};

Os dispositivos Sigfox esperam um código de 204 resposta. Adicione o seguinte código após a chamada na handleMessage linha 21:

context.res = {
    status: 204
};

Exemplo 3: Conectando dispositivos da The Things Network através da ponte de dispositivo

Para conectar os dispositivos da The Things Network ao IoT Central:

Adicione uma nova integração HTTP ao seu aplicativo em The Things Network: Application > Integrations > add integration > HTTP Integration.
Certifique-se de que a sua aplicação inclui uma função de descodificador que converte automaticamente a carga útil das mensagens do seu dispositivo em JSON antes de ser enviada para a função: Descodificador de Funções de Carga Útil > da Aplicação>.

O exemplo a seguir mostra uma função de decodificador JavaScript que você pode usar para decodificar tipos numéricos comuns de dados binários:

function Decoder(bytes, port) {
  function bytesToFloat(bytes, decimalPlaces) {
    var bits = (bytes[3] << 24) | (bytes[2] << 16) | (bytes[1] << 8) | bytes[0];
    var sign = (bits >>> 31 === 0) ? 1.0 : -1.0;
    var e = bits >>> 23 & 0xff;
    var m = (e === 0) ? (bits & 0x7fffff) << 1 : (bits & 0x7fffff) | 0x800000;
    var f = Math.round((sign * m * Math.pow(2, e - 150)) * Math.pow(10, decimalPlaces)) / Math.pow(10, decimalPlaces);
    return f;
  }

  function bytesToInt32(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8) | (bytes[2] << 16) | (bytes[3] << 24);
    var sign = 1;

    if (signed && bits >>> 31 === 1) {
      sign = -1;
      bits = bits & 0x7FFFFFFF;
    }

    return bits * sign;
  }

  function bytesToShort(bytes, signed) {
    var bits = bytes[0] | (bytes[1] << 8);
    var sign = 1;

    if (signed && bits >>> 15 === 1) {
      sign = -1;
      bits = bits & 0x7FFF;
    }

    return bits * sign;
  }

  return {
    temperature: bytesToFloat(bytes.slice(0, 4), 2),
    presscounter: bytesToInt32(bytes.slice(4, 8), true),
    blueLux: bytesToShort(bytes.slice(8, 10), false)
  };
}

Depois de definir a integração, adicione o seguinte código antes da chamada na handleMessage linha 21 do arquivo IoTCIntegration/index.js do seu aplicativo de função. Este código traduz o corpo da sua integração HTTP para o formato esperado.

req.body = {
  device: {
    deviceId: req.body.end_device_ids.device_id.toLowerCase()
  },
  measurements: req.body.uplink_message.decoded_payload
};

Nota

O trecho anterior usa o ID do dispositivo amigável para humanos. A mensagem Things Network também inclui uma ID técnica que você pode acessar usando o req.body.dev_eui.toLowerCase(). Para saber mais, consulte The Things Network - Data Formats.

Limitações

A ponte de dispositivo apenas encaminha mensagens para o IoT Central e não envia mensagens de volta para dispositivos. Essa limitação é o motivo pelo qual as propriedades e os comandos não funcionam para dispositivos que se conectam ao IoT Central por meio dessa ponte de dispositivo. Como as operações de gêmeo de dispositivo não são suportadas, não é possível atualizar as propriedades do dispositivo por meio da ponte do dispositivo. Para usar esses recursos, um dispositivo deve se conectar diretamente ao IoT Central usando um dos SDKs de dispositivo IoT do Azure.

Próximos passos

Agora que você aprendeu como implantar a ponte de dispositivo do IoT Central, aqui está a próxima etapa sugerida:

Gerir os seus dispositivos