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

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 tracciamento degli asset connessi alla rete a bassa potenza e ampia 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 i passaggi descritti in questa guida pratica, è necessario:

• 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 Come ottenere informazioni sull'applicazione?

Informazioni generali

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:

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:

1. Nell'applicazione IoT Central, vai alla pagina >.

   1. Prendere nota dell'ID Scope. Questo valore viene usato quando si distribuisce il device bridge.

   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 device bridge.

2. Usare il pulsante Distribuisci in Azure seguente per aprire il modello personalizzato di Resource Manager che distribuisce l'applicazione di funzione nella tua 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:

1. Nel portale di Azure aprire l'app per le funzioni distribuita nella sottoscrizione. Passare quindi a Strumenti di sviluppo>Console. Nella console eseguire i comandi seguenti per installare i pacchetti:

   cd IoTCIntegration
   npm install
   

   L'esecuzione di questi comandi potrebbe richiedere alcuni minuti. È possibile ignorare in modo sicuro tutti i messaggi di avviso.

2. Al termine dell'installazione del pacchetto, selezionare Riavvia nella pagina Panoramica dell'app per le funzioni:

   

3. 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, navigare fino a Funzioni > IoTCIntegration > Codice + Test > Ottenere l'URL della funzione.

   

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.

deviceId deve 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.

Annotazioni

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, esplorare Monitoraggio > log nell'app per le funzioni nel portale di Azure. Selezionare Attiva Application Insights.

Risorse provisionate

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

• App per le funzioni
• Piano di servizio app
• Account di archiviazione
• Insieme di credenziali delle chiavi

La cassaforte delle chiavi archivia la chiave del gruppo SAS 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. Con 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 Opzioni di hosting di Funzioni di Azure.

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

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

Successivamente, modifica il modello per includere "alwaysOn": true nella configurazione per la risorsa functionapp sotto "properties": {"SiteConfig": {...}} La 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 di dispositivi Particle tramite il bridge del dispositivo

Per connettere un dispositivo Particle tramite il bridge per dispositivi a IoT Central, accedere alla console di Particle e creare una nuova integrazione di webhook. Impostare Formato richiesta su JSON. In Impostazioni avanzate usare il formato del corpo personalizzato seguente:

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

Incolla l'URL della funzione dall'app delle funzioni e i dispositivi Particle appaiono 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 dei 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 del dispositivo include una funzione di conversione per questo formato, che accetta un sottoinsieme dei tipi di campo possibili in un payload di un 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 di 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 di dispositivi dalla rete things tramite il bridge del dispositivo

Per connettere i dispositivi Di rete Things a IoT Central:

• Aggiungi una nuova integrazione HTTP alla tua applicazione su The Things Network: Integrazioni Applicazione > aggiungi integrazione > Integrazione HTTP >.
• Assicurarsi che l'applicazione includa una funzione decoder che converte automaticamente il payload dei messaggi del dispositivo in JSON prima di inviarli alla funzione: Applicazione > Funzioni di payload > decoder.

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

Annotazioni

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.

Limitazioni

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.