Usare il bridge di dispositivi IoT Central per connettere altri cloud IoT a IoT Central

Articolo
06/14/2023

Il bridge di dispositivi IoT Central è una soluzione open source che connette altri cloud IoT, ad esempio Sigfox, Particle Device Cloud e The Things Network all'applicazione IoT Central. Il bridge di dispositivi funziona inoltrando i dati dai dispositivi connessi ad altri cloud IoT tramite l'applicazione IoT Central. Il bridge del dispositivo inoltra solo i dati a IoT Central, non invia comandi o aggiornamenti delle proprietà da IoT Central ai dispositivi.

Il bridge di dispositivi consente di combinare la potenza di IoT Central con dispositivi come:

Dispositivi di rilevamento degli asset connessi alla rete a bassa potenza dell'area di sigfox.
Dispositivi di monitoraggio della qualità dell'aria nel cloud dei dispositivi di particella.
Dispositivi di monitoraggio dell'umidità del suolo in The Things Network.

È possibile usare le funzionalità dell'applicazione IoT Central, ad esempio regole e analisi sui dati, creare flussi di lavoro in Power Automate e app per la logica di Azure o esportare i dati.

La soluzione device bridge effettua il provisioning di diverse risorse di Azure nella sottoscrizione di Azure che interagiscono per trasformare e inoltrare i messaggi dei dispositivi a IoT Central.

Prerequisiti

Per completare la procedura descritta in questa guida pratica, sono necessari gli elementi seguenti:

Una sottoscrizione di Azure attiva. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.
Applicazione IoT Central creata dal modello applicazione personalizzata. Per altre informazioni, vedere Creare un'applicazione IoT Central e Informazioni sull'applicazione.

Panoramica

Il bridge di dispositivi IoT Central è una soluzione open source in GitHub. Usa un modello personalizzato di Azure Resource Manager per distribuire diverse risorse nella sottoscrizione di Azure, inclusa un'app per le funzioni in Funzioni di Azure.

L'app per le funzioni è la parte principale del bridge del dispositivo. Riceve richieste HTTP POST da altre piattaforme IoT tramite un semplice webhook. Il repository Azure IoT Central Device Bridge include esempi che illustrano come connettere cloud Sigfox, Particle e The Things Network. È possibile estendere questa soluzione per connettersi al cloud IoT personalizzato se la piattaforma può inviare richieste HTTP POST all'app per le funzioni.

L'app per le funzioni trasforma i dati in un formato accettato da IoT Central e lo inoltra usando il servizio device provisioning e le API client del dispositivo:

Screenshot of an Azure Functions definition showing the code.

Se l'applicazione IoT Central riconosce l'ID dispositivo nel messaggio inoltrato, i dati di telemetria del dispositivo vengono visualizzati in IoT Central. Se l'applicazione IoT Central non riconosce l'ID dispositivo, l'app per le funzioni tenta di registrare un nuovo dispositivo con l'ID dispositivo. Il nuovo dispositivo viene visualizzato come dispositivo non assegnato nella pagina Dispositivi dell'applicazione IoT Central. Dalla pagina Dispositivi è possibile assegnare il nuovo dispositivo a un modello di dispositivo e quindi visualizzare i dati di telemetria.

Distribuire il bridge del dispositivo

Per distribuire il bridge del dispositivo nella sottoscrizione:

Nell'applicazione IoT Central passare alla pagina Autorizzazioni Gruppi > di connessioni dispositivo.
1. Prendere nota dell'Ambito ID. Questo valore viene usato quando si distribuisce il bridge del dispositivo.
2. Nella stessa pagina aprire il gruppo di registrazione SAS-IoT-Devices . Nella pagina del gruppo SAS-IoT-Devices copiare la chiave primaria. Questo valore viene usato quando si distribuisce il bridge del dispositivo.
Usare il pulsante Distribuisci in Azure seguente per aprire il modello di Resource Manager personalizzato che distribuisce l'app per le funzioni nella sottoscrizione. Usare l'ambito ID e la chiave primaria del passaggio precedente:

Al termine della distribuzione, è necessario installare i pacchetti npm necessari per la funzione:

Nella portale di Azure aprire l'app per le funzioni distribuita nella sottoscrizione. Passare quindi a Console strumenti>di sviluppo. Nella console eseguire i comandi seguenti per installare i pacchetti:
```
cd IoTCIntegration
npm install
```
L'esecuzione di questi comandi può richiedere alcuni minuti. È possibile ignorare in modo sicuro tutti i messaggi di avviso.
Al termine dell'installazione del pacchetto, selezionare Riavvia nella pagina Panoramica dell'app per le funzioni:
La funzione è ora pronta per l'uso. I sistemi esterni possono usare richieste HTTP POST per inviare i dati dei dispositivi tramite il bridge di dispositivi nell'applicazione IoT Central. Per ottenere l'URL della funzione, passare a Funzioni IoTCIntegration Code + Test Get function URL :To get function URL ( Funzioni > IoTCIntegration > Code + Test > Get function URL:

I corpi dei messaggi inviati al bridge del dispositivo devono avere il formato seguente:

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

Ogni chiave nell'oggetto measurements deve corrispondere al nome di un tipo di telemetria nel modello di dispositivo nell'applicazione IoT Central. Questa soluzione non supporta la specifica dell'ID interfaccia nel corpo del messaggio. Pertanto, se due interfacce diverse hanno un tipo di telemetria con lo stesso nome, la misurazione viene visualizzata in entrambi i flussi di telemetria nell'applicazione IoT Central.

È possibile includere un timestamp campo nel corpo per specificare la data e l'ora UTC del messaggio. Questo campo deve essere in formato ISO 8601. Ad esempio, 2020-06-08T20:16:54.602Z. Se non si include un timestamp, viene usata la data e l'ora correnti.

È possibile includere un modelId campo nel corpo. Usare questo campo per assegnare il dispositivo a un modello di dispositivo durante il provisioning.

Deve deviceId essere alfanumerico, minuscolo e può contenere trattini.

Se non si include il modelId campo o se IoT Central non riconosce l'ID modello, un messaggio con un dispositivo non riconosciuto deviceId crea un nuovo dispositivo non assegnato in IoT Central. Un operatore può eseguire manualmente la migrazione del dispositivo al modello di dispositivo corretto. Per altre informazioni, vedere Gestire i dispositivi nell'applicazione > Azure IoT Central Migrazione dei dispositivi a un modello.

Nota

Finché il dispositivo non viene assegnato a un modello, tutte le chiamate HTTP alla funzione restituiscono uno stato di errore 403.

Per attivare la registrazione per l'app per le funzioni con Application Insights, passare a Monitoraggio > dei log nell'app per le funzioni nella portale di Azure. Selezionare Attiva Application Insights.

Risorse di cui è stato effettuato il provisioning

Il modello di Resource Manager effettua il provisioning delle risorse seguenti nella sottoscrizione di Azure:

App per le funzioni
Piano di servizio app
Storage account
Key Vault

L'insieme di credenziali delle chiavi archivia la chiave del gruppo di firma di accesso condiviso per l'applicazione IoT Central.

L'app per le funzioni viene eseguita in un piano a consumo. Anche se questa opzione non offre risorse di calcolo dedicate, consente al bridge del dispositivo di gestire centinaia di messaggi del dispositivo al minuto, adatti per più piccole flotta di dispositivi o dispositivi che inviano messaggi meno frequentemente. Se l'applicazione dipende dallo streaming di un numero elevato di messaggi del dispositivo, sostituire il piano a consumo con un piano di servizio app dedicato. Questo piano offre risorse di calcolo dedicate, che offrono tempi di risposta server più rapidi. Usando un piano di servizio app standard, le prestazioni massime osservate della funzione da Azure in questo repository erano circa 1.500 messaggi del dispositivo al minuto. Per altre informazioni, vedere Funzioni di Azure opzioni di hosting.

Per usare un piano di servizio app dedicato anziché un piano a consumo, modificare il modello personalizzato prima della distribuzione. Selezionare Modifica modello.

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

Sostituire il segmento seguente:

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

con

{
  "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')]"
  }
},

Modificare quindi il modello da includere "alwaysOn": true nella configurazione per la functionapp risorsa in "properties": {"SiteConfig": {...}} Configurazione alwaysOn garantisce che l'app per le funzioni sia sempre in esecuzione.

Esempi

Gli esempi seguenti illustrano come configurare il bridge di dispositivi per vari cloud IoT:

Esempio 1: Connessione ing di dispositivi particella tramite il bridge del dispositivo

Per connettere un dispositivo Particella tramite il bridge del dispositivo a IoT Central, passare alla console Di particella e creare una nuova integrazione webhook. Impostare Formato richiesta su JSON. In Advanced Impostazioni (Avanzate Impostazioni) usare il formato del corpo personalizzato seguente:

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

Incollare l'URL della funzione dall'app per le funzioni e i dispositivi Particella vengono visualizzati come dispositivi non assegnati in IoT Central. Per altre informazioni, vedere il post di blog Here's how to integrate your Particle-powered projects with Azure IoT Central (Come integrare i progetti basati su particelle con Azure IoT Central ).

Esempio 2: Connessione di dispositivi Sigfox tramite il bridge del dispositivo

Alcune piattaforme potrebbero non consentire di specificare il formato dei messaggi del dispositivo inviati tramite un webhook. Per questi sistemi, è necessario convertire il payload del messaggio nel formato del corpo previsto prima dell'elaborazione del bridge del dispositivo. È possibile eseguire la conversione nella stessa funzione che esegue il bridge del dispositivo.

Questa sezione illustra come convertire il payload di un'integrazione di webhook Sigfox nel formato del corpo previsto dal bridge del dispositivo. Il cloud Sigfox trasmette i dati del dispositivo in formato stringa esadecimale. Per praticità, il bridge di dispositivo include una funzione di conversione per questo formato, che accetta un subset dei tipi di campo possibili in un payload del dispositivo Sigfox: int e uint di 8, 16, 32 o 64 bit; float di 32 bit o 64 bit; little-endian e big-endian. Per elaborare i messaggi da un'integrazione webhook Sigfox, apportare le modifiche seguenti al file IoTCIntegration/index.js nell'app per le funzioni.

Per convertire il payload del messaggio, aggiungere il codice seguente prima della chiamata a handleMessage alla riga 21, sostituendo payloadDefinition con la definizione del payload 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)
};

I dispositivi Sigfox prevedono un codice di 204 risposta. Aggiungere il codice seguente dopo la chiamata a handleMessage nella riga 21:

context.res = {
    status: 204
};

Esempio 3: Connessione dispositivi da The Things Network tramite il bridge del dispositivo

Per connettere i dispositivi Di rete Things a IoT Central:

Aggiungere una nuova integrazione HTTP all'applicazione in The Things Network: > Application Integrations >aggiunge integrazione > HTTP.
Assicurarsi che l'applicazione includa una funzione di decodificatore che converte automaticamente il payload dei messaggi del dispositivo in JSON prima dell'invio alla funzione: decodificatore di Funzioni > payload dell'applicazione>.

L'esempio seguente mostra una funzione decodificatore JavaScript che è possibile usare per decodificare i tipi numerici comuni dai dati binari:

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)
  };
}

Dopo aver definito l'integrazione, aggiungere il codice seguente prima della chiamata a handleMessage nella riga 21 del file IoTCIntegration/index.js dell'app per le funzioni. Questo codice converte il corpo dell'integrazione HTTP nel formato previsto.

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

Nota

Il frammento precedente usa l'ID dispositivo descrittivo. Il messaggio Things Network include anche un ID tecnico a cui è possibile accedere tramite req.body.dev_eui.toLowerCase(). Per altre informazioni, vedere The Things Network - Data Formats.

Limiti

Il bridge del dispositivo inoltra solo i messaggi a IoT Central e non invia messaggi ai dispositivi. Questa limitazione è il motivo per cui le proprietà e i comandi non funzionano per i dispositivi che si connettono a IoT Central tramite questo bridge di dispositivi. Poiché le operazioni del dispositivo gemello non sono supportate, non è possibile aggiornare le proprietà del dispositivo tramite il bridge del dispositivo. Per usare queste funzionalità, un dispositivo deve connettersi direttamente a IoT Central usando uno degli SDK per dispositivi IoT di Azure.

Passaggi successivi

Dopo aver appreso come distribuire il bridge di dispositivi IoT Central, ecco il passaggio successivo consigliato:

Gestire i dispositivi

Condividi tramite