Usare Azure IoT Edge per inviare messaggi da dispositivo a cloud con un dispositivo simulato (Windows)

La procedura dettagliata dell'esempio di caricamento nel cloud del dispositivo simulato illustra come usare Azure IoT Edge per inviare dati di telemetria da dispositivo a cloud all'hub IoT da dispositivi simulati.

In questa procedura dettagliata verranno trattati i seguenti argomenti:

Architettura

L'esempio di caricamento nel cloud del dispositivo simulato mostra come creare un gateway che invia i dati di telemetria da dispositivi simulati a un hub IoT. Un dispositivo potrebbe non essere in grado di connettersi direttamente all'hub IoT perché il dispositivo:

  • Non usa un protocollo di comunicazione riconosciuto dall'hub IoT.
  • Non riesce a memorizzare l'identità assegnata dall'hub IoT.

Un gateway IoT Edge può risolvere questi problemi nei modi seguenti:

  • Il gateway riconosce il protocollo usato dal dispositivo, riceve i dati di telemetria da dispositivo a cloud dal dispositivo e inoltra i messaggi all'hub IoT usando un protocollo riconosciuto dall'hub IoT.

  • Il gateway esegue il mapping delle identità dell'hub IoT ai dispositivi e funge da proxy quando un dispositivo invia messaggi all'hub IoT.

Il diagramma seguente illustra i componenti principali dell'esempio, inclusi i moduli di IoT Edge:

Diagramma - Il messaggio del dispositivo simulato arriva all'hub IoT attraverso il gateway

Questo esempio include tre moduli che costituiscono il gateway:

  1. Modulo di inserimento del protocollo
  2. Modulo ID MAC <-> IoT Hub
  3. Modulo di comunicazione dell'hub IoT

I moduli non si scambiano direttamente i messaggi, ma li pubblicano in un broker interno che li invia ad altri moduli usando un meccanismo di sottoscrizione. Per altre informazioni, vedere Get started with Azure IoT Edge (Introduzione ad Azure IoT Edge).

Diagramma - I moduli del gateway comunicano con il broker

Modulo di inserimento del protocollo

Questo modulo è il punto di partenza per il processo di ricezione dei dati dai dispositivi e trasferimento degli stessi al cloud attraverso il gateway.

Nell'esempio il modulo esegue le attività seguenti:

  1. Crea dati di temperatura simulati. Se vengono usati dispositivi fisici, il modulo legge i dati da tali dispositivi fisici.
  2. Crea un messaggio.
  3. Inserisce i dati di temperatura simulati nel contenuto del messaggio.
  4. Aggiunge una proprietà con un indirizzo MAC fittizio al messaggio.
  5. Rende disponibile il messaggio al modulo successivo nella catena.

Il modulo di inserimento del protocollo è simulated_device.c nel codice sorgente.

Modulo ID MAC <-> IoT Hub

Il modulo ID MAC < - > IoT Hub funge da convertitore. Questo esempio usa un indirizzo MAC come identificatore univoco del dispositivo e lo associa a un'identità dei dispositivi di un hub IoT. Tuttavia, è possibile scrivere un modulo personalizzato che usa un identificatore univoco diverso. Ad esempio, i dispositivi possono avere numeri di serie univoci o i dati di telemetria possono includere un nome univoco del dispositivo incorporato.

Nell'esempio il modulo esegue le attività seguenti:

  1. Analizza i messaggi che includono una proprietà di indirizzo MAC.
  2. Se è presente un indirizzo MAC, aggiunge un'altra proprietà con una chiave del dispositivo dell'hub IoT al messaggio.
  3. Rende disponibile il messaggio al modulo successivo nella catena.

Lo sviluppatore imposta il mapping tra gli indirizzi MAC e le identità dell'hub IoT per associare i dispositivi simulati alle identità del dispositivo dell'hub IoT. Lo sviluppatore aggiunge manualmente il mapping durante la configurazione del modulo.

Il modulo ID MAC < - > IoT Hub è identitymap.c nel codice sorgente.

Modulo di comunicazione dell'hub IoT

Questo modulo apre una singola connessione HTTP dal gateway all'hub IoT. HTTP è uno dei tre protocolli riconosciuti dall'hub IoT. Invece di aprire una connessione per ogni dispositivo, questo modulo apre una singola connessione sulla quale esegue il multiplexing delle connessioni da tutti i dispositivi. Questo approccio consente a un singolo gateway di connettersi a molti dispositivi.

Nell'esempio il modulo esegue le attività seguenti:

  1. Accetta i messaggi con una proprietà chiave dei dispositivi di un hub IoT assegnata dal modulo precedente.
  2. Invia il contenuto del messaggio all'hub IoT usando il protocollo HTTP.

Il modulo di comunicazione dell'hub IoT è iothub.c nel codice sorgente.

Prima di iniziare

Prima di iniziare:

  • Creare un hub IoT nella propria sottoscrizione di Azure. Per questa procedura dettagliata di esempio è necessario il nome dell'hub. Se non si ha un account, è possibile crearne uno gratuito in pochi minuti.
  • Aggiungere due dispositivi all'hub IoT e annotare i relativi ID e le chiavi di dispositivo. È possibile usare gli strumenti Esplora dispositivi o iothub-explorer per aggiungere i dispositivi all'hub IoT e recuperarne le chiavi.

Installare i prerequisiti

  1. Installare Visual Studio 2015 o 2017. Se si soddisfano i requisiti di licenza, è possibile usare la versione gratuita Community Edition. Assicurarsi di includere Visual C++ e Gestione pacchetti NuGet.

  2. Installare git e verificare di riuscire a eseguire git.exe dalla riga di comando.

  3. Installare CMake e verificare di riuscire a eseguire cmake.exe dalla riga di comando. È consigliabile usare CMake versione 3.7.2 o successive. Il programma di installazione .msi è l'opzione più semplice in Windows. Aggiungere CMake alla variabile di ambiente PATH almeno per l'utente corrente quando viene dal programma di installazione.

  4. Installare Python 2.7. Assicurarsi di aggiungere Python alla variabile di ambiente PATH in Pannello di controllo -> Sistema -> Impostazioni di sistema avanzate -> Variabili di ambiente.

  5. Al prompt dei comandi, eseguire il comando seguente per clonare il repository GitHub Azure IoT Edge nel computer locale:

    git clone https://github.com/Azure/iot-edge.git
    

Come compilare l'esempio

È ora possibile compilare il runtime e gli esempi di IoT Edge nel computer locale:

  1. Aprire un prompt dei comandi per gli sviluppatori per VS 2015 o un prompt dei comandi per gli sviluppatori per VS 2017.

  2. Accedere alla cartella radice nella copia locale del repository iot-edge.

  3. Eseguire lo script di compilazione come segue:

    tools\build.cmd --disable-native-remote-modules
    

Questo script crea un file di soluzione Visual Studio e compila la soluzione. È possibile trovare la soluzione di Visual Studio nella cartella build nella copia locale del repository iot-edge. Per compilare ed eseguire unit test, aggiungere il parametro --run-unittests. Per compilare ed eseguire test end-to-end, aggiungere il parametro --run-e2e-tests.

Nota

Ogni volta che si esegue lo script build.cmd, la cartella build viene eliminata e ricreata nella cartella radice della copia locale del repository iot-edge.

Per eseguire l'esempio

Lo script build.cmd genera l'output nella cartella build nella copia locale dell'archivio iot-edge. Questo output include i quattro moduli di IoT Edge usati in questo esempio.

Le posizioni dello script di compilazione sono le seguenti:

  • logger.dll nella cartella build\modules\logger\Debug.
  • iothub.dll nella cartella build\modules\iothub\Debug.
  • identity_map.dll nella cartella build\modules\identitymap\Debug.
  • simulated_device.dll nella cartella build\modules\simulated_device\Debug.

Usare questi percorsi per i valori module path, come illustrato nel file di impostazioni JSON seguente:

Il processo simulated_device_cloud_upload_sample accetta il percorso di un file di configurazione JSON come argomento della riga di comando. Il file JSON di esempio seguente è disponibile nell'archivio SDK in samples\simulated_device_cloud_upload_sample\src\simulated_device_cloud_upload_sample_win.json. Questo file di configurazione funziona così com'è, a meno che non si modifichi lo script di compilazione per inserire moduli di IoT Edge o file eseguibili di esempio in percorsi non predefiniti.

Nota

I percorsi dei moduli sono relativi alla directory in cui si trova il file simulated_device_cloud_upload_sample.exe. Per impostazione predefinita, il file di configurazione JSON di esempio prevede la scrittura del file "deviceCloudUploadGatewaylog.log" nella directory di lavoro corrente.

In un editor di testo aprire il file samples\simulated_device_cloud_upload_sample\src\simulated_device_cloud_upload_win.json nella copia locale dell'archivio iot-edge. Questo file consente di configurare i moduli IoT Edge nel gateway di esempio:

  • Il modulo IoTHub si connette all'hub IoT. È necessario configurarlo per l'invio di dati all'hub IoT. In particolare, impostare il valore di IoTHubName sul nome dell'hub IoT e impostare il valore di IoTHubSuffix su azure-devices.net. Impostare il valore Transport su HTTP, AMQP o MQTT. Attualmente, solo HTTP condivide una connessione TCP per tutti i messaggi del dispositivo. Se si imposta il valore su AMQP o MQTT, il gateway mantiene una connessione TCP separata all'hub IoT per ogni dispositivo.
  • Il modulo mapping esegue il mapping degli indirizzi MAC dei dispositivi simulati sugli ID dispositivo dell'hub IoT. Assicurarsi che i valori di deviceId corrispondano agli ID dei due dispositivi aggiunti all'hub IoT e che i valori di deviceKey contengano le chiavi dei due dispositivi.
  • I moduli BLE1 e BLE2 sono i dispositivi simulati. Si noti come gli indirizzi del modulo MAC corrispondono a quelli nel modulo mapping.
  • Il modulo Logger registra l'attività del gateway in un file.
  • I valori module path illustrati nell'esempio seguente sono relativi alla directory in cui si trova il file simulated_device_cloud_upload_sample.exe.
  • La matrice links nella parte inferiore del file JSON connette i moduli BLE1 e BLE2 al modulo mapping e il modulo mapping al modulo IoTHub. Inoltre, la matrice garantisce la registrazione di tutti i messaggi da parte del modulo Logger .
{
    "modules" :
    [
      {
        "name": "IotHub",
        "loader": {
          "name": "native",
          "entrypoint": {
            "module.path": "..\\..\\..\\modules\\iothub\\Debug\\iothub.dll"
          }
          },
          "args": {
            "IoTHubName": "<<insert here IoTHubName>>",
            "IoTHubSuffix": "<<insert here IoTHubSuffix>>",
            "Transport": "HTTP"
          }
        },
      {
        "name": "mapping",
        "loader": {
          "name": "native",
          "entrypoint": {
            "module.path": "..\\..\\..\\modules\\identitymap\\Debug\\identity_map.dll"
          }
          },
          "args": [
            {
              "macAddress": "01:01:01:01:01:01",
              "deviceId": "<<insert here deviceId>>",
              "deviceKey": "<<insert here deviceKey>>"
            },
            {
              "macAddress": "02:02:02:02:02:02",
              "deviceId": "<<insert here deviceId>>",
              "deviceKey": "<<insert here deviceKey>>"
            }
          ]
        },
      {
        "name": "BLE1",
        "loader": {
          "name": "native",
          "entrypoint": {
            "module.path": "..\\..\\..\\modules\\simulated_device\\Debug\\simulated_device.dll"
          }
          },
          "args": {
            "macAddress": "01:01:01:01:01:01"
          }
        },
      {
        "name": "BLE2",
        "loader": {
          "name": "native",
          "entrypoint": {
            "module.path": "..\\..\\..\\modules\\simulated_device\\Debug\\simulated_device.dll"
          }
          },
          "args": {
            "macAddress": "02:02:02:02:02:02"
          }
        },
      {
        "name": "Logger",
        "loader": {
          "name": "native",
          "entrypoint": {
            "module.path": "..\\..\\..\\modules\\logger\\Debug\\logger.dll"
          }
        },
        "args": {
          "filename": "deviceCloudUploadGatewaylog.log"
        }
      }
    ],
    "links" : [
        { "source" : "*", "sink" : "Logger" },
        { "source" : "BLE1", "sink" : "mapping" },
        { "source" : "BLE2", "sink" : "mapping" },
        { "source" : "mapping", "sink" : "IotHub" }
    ]
}

Salvare le modifiche apportate al file di configurazione.

Per eseguire l'esempio:

  1. Al prompt dei comandi accedere alla cartella build della copia locale dell'archivio iot-edge.
  2. Eseguire il comando seguente:

    samples\simulated_device_cloud_upload\Debug\simulated_device_cloud_upload_sample.exe ..\samples\simulated_device_cloud_upload\src\simulated_device_cloud_upload_win.json
    
  3. È possibile usare lo strumento Esplora dispositivi o iothub-explorer per monitorare i messaggi che l'hub IoT riceve dal gateway. Ad esempio, tramite iothub-explorer è possibile monitorare i messaggi da dispositivo a cloud usando il comando seguente:

    iothub-explorer monitor-events --login "HostName={Your iot hub name}.azure-devices.net;SharedAccessKeyName=iothubowner;SharedAccessKey={Your IoT Hub key}"
    

Passaggi successivi

Per ottenere informazioni più avanzate su IoT Edge e provare alcuni esempi di codice, vedere le risorse e le esercitazioni per gli sviluppatori elencate di seguito:

Per altre informazioni sulle funzionalità dell'hub IoT, vedere: