Esercitazione: Usare Eclipse ThreadX per connettere un devkit MXCHIP AZ3166 a hub IoT

  • Articolo

Esplora il codice

In questa esercitazione si usa Eclipse ThreadX per connettere un MXCHIP AZ3166 IoT DevKit (da ora in poi MXCHIP DevKit) ad Azure IoT.

Completare le attività seguenti:

  • Installare un set di strumenti di sviluppo incorporati per la programmazione di MXChip DevKit in C
  • Creare un'immagine e lampeggiarla nel DevKit MXCHIP
  • Usare l'interfaccia della riga di comando di Azure per creare e gestire un hub IoT di Azure a cui si connette in modo sicuro MXCHIP DevKit
  • Usare Azure IoT Explorer per registrare un dispositivo con l'hub IoT, visualizzare le proprietà del dispositivo, visualizzare i dati di telemetria del dispositivo e chiamare comandi diretti nel dispositivo

Prerequisiti

  • Un PC che esegue Windows 10 o Windows 11

  • Una sottoscrizione di Azure attiva. Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.

  • Git per la clonazione del repository

  • Interfaccia della riga di comando di Azure. In questa esercitazione sono disponibili due opzioni per l'esecuzione dei comandi dell'interfaccia della riga di comando di Azure:

    • Usare Azure Cloud Shell, una shell interattiva che esegue i comandi dell'interfaccia della riga di comando nel browser. Questa opzione è consigliata perché non è necessario installare nulla. Se si usa Cloud Shell per la prima volta, accedere al portale di Azure. Seguire la procedura descritta in Avvio rapido di Cloud Shell per Avviare Cloud Shell e selezionare l'ambiente Bash.
    • Facoltativamente, eseguire l'interfaccia della riga di comando di Azure nel computer locale. Se l'interfaccia della riga di comando di Azure è già installata, eseguire az upgrade per aggiornare l'interfaccia della riga di comando e le estensioni alla versione corrente. Per installare l'interfaccia della riga di comando di Azure, vedere Installare l'interfaccia della riga di comando di Azure.

  • Hardware

Preparare l'ambiente di sviluppo

Per configurare l'ambiente di sviluppo, clonare prima di tutto un repository GitHub che contiene tutti gli asset necessari per l'esercitazione. Installare quindi un set di strumenti di programmazione.

Clonare il repository

Clonare il repository seguente per scaricare tutto il codice del dispositivo di esempio, gli script di installazione e le versioni offline della documentazione. Se questo repository è stato clonato in precedenza in un'altra esercitazione, non è necessario eseguire di nuovo questa operazione.

Per clonare il repository, eseguire il comando seguente:

git clone --recursive https://github.com/eclipse-threadx/getting-started.git

Installa gli strumenti

Il repository clonato contiene uno script di installazione che installa e configura gli strumenti necessari. Se questi strumenti sono stati installati in un'altra esercitazione sul dispositivo incorporato, non è necessario eseguire di nuovo questa operazione.

Nota

Lo script di installazione installa gli strumenti seguenti:

Per installare gli strumenti:

  1. Da Esplora file passare al percorso seguente nel repository ed eseguire lo script di installazione denominato get-toolchain.bat:

    getting-started\tools\get-toolchain.bat

  2. Dopo l'installazione, aprire una nuova finestra della console per riconoscere le modifiche di configurazione apportate dallo script di installazione. Usare questa console per completare le attività di programmazione rimanenti nell'esercitazione. È possibile usare CMD di Windows, PowerShell o Git Bash per Windows.

  3. Eseguire il codice seguente per verificare che sia installato CMake versione 3.14 o successiva.

    cmake --version

Creare i componenti cloud

Creare un hub IoT

È possibile usare l'interfaccia della riga di comando di Azure per creare un hub IoT che gestisce gli eventi e la messaggistica per il dispositivo.

Per creare un hub IoT:

  1. Avviare l'app dell'interfaccia della riga di comando. Per eseguire i comandi dell'interfaccia della riga di comando nel resto di questa guida introduttiva, copiare la sintassi del comando, incollarla nell'app dell'interfaccia della riga di comando, modificare i valori delle variabili e premere INVIO.

    • Se si usa Cloud Shell, fare clic con il pulsante destro del mouse sul collegamento per Cloud Shell e selezionare l'opzione da aprire in una nuova scheda.
    • Se si usa l'interfaccia della riga di comando di Azure in locale, avviare l'app console dell'interfaccia della riga di comando e accedere all'interfaccia della riga di comando di Azure.

  2. Eseguire az extension add per installare o aggiornare l'estensione azure-iot alla versione corrente.

    az extension add --upgrade --name azure-iot

  3. Eseguire il comando az group create per creare un gruppo di risorse. Il comando seguente crea un gruppo di risorse denominato MyResourceGroup nell'area centralus .

    Nota

    Facoltativamente, è possibile impostare un oggetto alternativo location. Per visualizzare le posizioni disponibili, eseguire az account list-locations.

    az group create --name MyResourceGroup --location centralus

  4. Eseguire il comando az iot hub create per creare un hub IoT. La creazione di un hub IoT potrebbe richiedere alcuni minuti.

    YourIotHubName. Sostituire questo segnaposto nel codice con il nome scelto per l'hub IoT. Un nome dell'hub IoT deve essere univoco a livello globale in Azure. Questo segnaposto viene usato nella parte restante di questa guida introduttiva per rappresentare il nome univoco dell'hub IoT.

    Il --sku F1 parametro crea l'hub IoT nel livello Gratuito. Gli hub di livello gratuito hanno un set di funzionalità limitato e vengono usati per le applicazioni di verifica. Per altre informazioni su hub IoT livelli, funzionalità e prezzi, vedere prezzi hub IoT di Azure.

    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2

  5. Dopo aver creato l'hub IoT, visualizzare l'output JSON nella console e copiare il hostName valore da usare in un passaggio successivo. Il hostName valore è simile all'esempio seguente:

    {Your IoT hub name}.azure-devices.net

Configurare IoT Explorer

Nella parte restante di questa guida introduttiva si usa IoT Explorer per registrare un dispositivo nell'hub IoT, visualizzare le proprietà e i dati di telemetria del dispositivo e inviare comandi al dispositivo. In questa sezione viene configurato IoT Explorer per connettersi all'hub IoT creato e per leggere i modelli plug and play dal repository del modello pubblico.

Per aggiungere una connessione all'hub IoT:

  1. Installare Azure IoT Explorer. Questo strumento è un'utilità multipiattaforma per monitorare e gestire le risorse di Azure IoT.

  2. Nell'app dell'interfaccia della riga di comando eseguire il comando az iot hub connection-string show per ottenere il stringa di connessione per l'hub IoT.

    az iot hub connection-string  show --hub-name {YourIoTHubName}

  3. Copiare il stringa di connessione senza le virgolette circostanti.

  4. In Azure IoT Explorer selezionare Hub IoT nel menu a sinistra.

  5. Selezionare + Aggiungi connessione.

  6. Incollare il stringa di connessione nella casella stringa di Connessione ion.

  7. Seleziona Salva.

    Screenshot dell'aggiunta di una connessione in IoT Explorer.

Se la connessione ha esito positivo, IoT Explorer passa alla visualizzazione Dispositivi .

Per aggiungere il repository del modello pubblico:

  1. In IoT Explorer selezionare Home per tornare alla visualizzazione home.

  2. Nel menu a sinistra selezionare Plug and Play IoT Impostazioni, quindi selezionare +Aggiungi e selezionare Repository pubblico dal menu a discesa.

  3. Viene visualizzata una voce per il repository di modelli pubblici in https://devicemodels.azure.com.

    Screenshot dell'aggiunta del repository del modello pubblico in IoT Explorer.

  4. Seleziona Salva.

Registrazione di un dispositivo

In questa sezione viene creata una nuova istanza del dispositivo e registrata con l'hub IoT creato. Usare le informazioni di connessione per il dispositivo appena registrato per connettere in modo sicuro il dispositivo fisico in una sezione successiva.

Per registrare un dispositivo:

  1. Nella home view in IoT Explorer selezionare Hub IoT.

  2. Verrà visualizzata la connessione aggiunta in precedenza. Selezionare Visualizza dispositivi in questo hub sotto le proprietà di connessione.

  3. Selezionare + Nuovo e immettere un ID dispositivo per il dispositivo, mydevicead esempio . Lasciare invariate tutte le altre proprietà.

  4. Seleziona Crea.

    Screenshot dell'identità del dispositivo azure IoT Explorer.

  5. Usare i pulsanti copia per copiare i campi ID dispositivo e Chiave primaria .

Prima di continuare con la sezione successiva, salvare ognuno dei valori seguenti recuperati dai passaggi precedenti in un percorso sicuro. Questi valori vengono usati nella sezione successiva per configurare il dispositivo.

  • hostName
  • deviceId
  • primaryKey

Preparare il dispositivo

Per connettere MXCHIP DevKit ad Azure, modificare un file di configurazione per le impostazioni Wi-Fi e Azure IoT, ricompilare l'immagine e lampeggiare l'immagine nel dispositivo.

Aggiungere la configurazione

  1. Aprire il file seguente in un editor di testo:

    getting-started\MXChip\AZ3166\app\azure_config.h

  2. Impostare come commento la riga seguente nella parte superiore del file, come illustrato:

    // #define ENABLE_DPS

  3. Impostare le costanti Wi-Fi sui valori seguenti dell'ambiente locale.

    Nome costante Valore
    WIFI_SSID {SSID wi-fi}
    WIFI_PASSWORD {Password Wi-Fi}
    WIFI_MODE {Uno dei valori della modalità Wi-Fi enumerati nel file}

  4. Impostare le costanti relative alle informazioni sul dispositivo Azure IoT sui valori salvati dopo aver creato le risorse di Azure.

    Nome costante Valore
    IOT_HUB_HOSTNAME {Il valore del nome host}
    IOT_HUB_DEVICE_ID {Valore ID dispositivo}
    IOT_DEVICE_SAS_KEY {Il valore della chiave primaria}

  5. Salva e chiudi il file.

Compilare l'immagine

  1. Nella console o in Esplora file eseguire lo script rebuild.bat nel percorso seguente per compilare l'immagine:

    getting-started\MXChip\AZ3166\tools\rebuild.bat

  2. Al termine della compilazione, verificare che il file binario sia stato creato nel percorso seguente:

    getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

Eseguire il flashing dell'immagine

  1. In MXCHIP DevKit individuare il pulsante Reimposta e la porta Micro USB. Questi componenti vengono usati nei passaggi seguenti. Entrambi sono evidenziati nell'immagine seguente:

    Individuare i componenti chiave nella scheda devkit MXChip

  2. Connessione il cavo Micro USB alla porta Micro USB sul DevKit MXCHIP e quindi connetterlo al computer.

  3. In Esplora file trovare il file binario creato nella sezione precedente.

  4. Copiare il file binario mxchip_azure_iot.bin.

  5. In Esplora file trovare il dispositivo MXCHIP DevKit connesso al computer. Il dispositivo viene visualizzato come unità nel sistema con l'etichetta di unità AZ3166.

  6. Incollare il file binario nella cartella radice del devkit MXCHIP. Il flashing viene avviato automaticamente e viene completato in pochi secondi.

    Nota

    Durante il processo di flashing, un LED verde attiva o disattiva MXCHIP DevKit.

Confermare i dettagli della connessione del dispositivo

È possibile usare l'app Termite per monitorare la comunicazione e verificare che il dispositivo sia configurato correttamente.

  1. Avviare Termite.

    Suggerimento

    Se non è possibile connettere Termite al devkit, installare il driver ST-LINK e riprovare. Per altri passaggi, vedere Risoluzione dei problemi .

  2. Seleziona Impostazioni.

  3. Nella finestra di dialogo Impostazioni porta seriale controllare le impostazioni seguenti e aggiornare, se necessario:

    • Velocità baud: 115.200
    • Porta: la porta a cui è connesso il DevKit MXCHIP. Se sono presenti più opzioni di porta nell'elenco a discesa, è possibile trovare la porta corretta da usare. Aprire Windows Gestione dispositivi e visualizzare Porte per identificare la porta da usare.

    Screenshot delle impostazioni della porta seriale nell'app Termite

  4. Seleziona OK.

  5. Premere il pulsante Ripristina sul dispositivo. Il pulsante è etichettato sul dispositivo e si trova vicino al connettore Micro USB.

  6. Nell'app Termite controllare i valori del checkpoint seguenti per verificare che il dispositivo sia inizializzato e connesso ad Azure IoT.

     Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

Tenere aperto Termite per monitorare l'output del dispositivo nei passaggi seguenti.

Visualizzare le proprietà del dispositivo

È possibile usare Azure IoT Explorer per visualizzare e gestire le proprietà dei dispositivi. In questa sezione e nelle sezioni seguenti si usano le funzionalità Plug and Play visualizzate in IoT Explorer per gestire e interagire con MXCHIP DevKit. Queste funzionalità si basano sul modello di dispositivo pubblicato per MXCHIP DevKit nel repository di modelli pubblici. IoT Explorer è stato configurato per cercare in questo repository i modelli di dispositivo in precedenza in questa esercitazione. È possibile eseguire molte azioni senza usare plug and play selezionando l'azione dal menu a sinistra del riquadro del dispositivo in IoT Explorer. Tuttavia, l'uso di plug and play offre spesso un'esperienza avanzata. IoT Explorer può leggere il modello di dispositivo specificato da un dispositivo plug and play e presentare informazioni specifiche del dispositivo.

Per accedere ai componenti Plug and Play IoT per il dispositivo in IoT Explorer:

  1. Nella home view in IoT Explorer selezionare Hub IoT, quindi selezionare Visualizza dispositivi in questo hub.

  2. Selezionare il dispositivo.

  3. Selezionare Plug and Play IoT componenti.

  4. Selezionare Componente predefinito. IoT Explorer visualizza i componenti Plug and Play IoT implementati nel dispositivo.

    Screenshot del componente predefinito MXCHIP DevKit in IoT Explorer

  5. Nella scheda Interfaccia visualizzare il contenuto JSON nella descrizione del modello di dispositivo. Il codice JSON contiene i dettagli di configurazione per ognuno dei componenti Plug and Play IoT nel modello di dispositivo.

    Ogni scheda in IoT Explorer corrisponde a uno dei componenti Plug and Play IoT nel modello di dispositivo.

    Tab Type Name Descrizione
    Interfaccia Interfaccia MXCHIP Getting Started Guide Modello di esempio per MXCHIP DevKit
    Proprietà (sola lettura) Proprietà ledState Stato corrente del LED
    Proprietà (scrivibile) Proprietà telemetryInterval Intervallo di invio dei dati di telemetria da parte del dispositivo
    Comandi Comando setLedState Accendere o disattivare il LED

Per visualizzare le proprietà del dispositivo tramite Azure IoT Explorer:

  1. Selezionare la scheda Proprietà (scrivibile). Visualizza l'intervallo di invio dei dati di telemetria.

  2. Impostare su telemetryInterval5 e quindi selezionare Aggiorna valore desiderato. Il dispositivo usa ora questo intervallo per inviare i dati di telemetria.

    Screenshot dell'impostazione dell'intervallo di telemetria in MXCHIP DevKit in IoT Explorer

  3. IoT Explorer risponde con una notifica. È anche possibile osservare l'aggiornamento in Termite.

  4. Impostare di nuovo l'intervallo di telemetria su 10.

Per usare l'interfaccia della riga di comando di Azure per visualizzare le proprietà del dispositivo:

  1. Eseguire il comando az iot hub device-twin show .

    az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

  2. Esaminare le proprietà del dispositivo nell'output della console.

Visualizzare i dati di telemetria

Con Azure IoT Explorer è possibile visualizzare il flusso di dati di telemetria dal dispositivo al cloud. Facoltativamente, è possibile eseguire la stessa attività usando l'interfaccia della riga di comando di Azure.

Per visualizzare i dati di telemetria in Azure IoT Explorer:

  1. Nel riquadro componenti di Plug and Play IoT (componente predefinito) per il dispositivo in IoT Explorer selezionare la scheda Telemetria. Verificare che l'opzione Usa hub eventi predefinito sia impostata su Sì.

  2. Selezionare Inizio.

  3. Visualizzare i dati di telemetria mentre il dispositivo invia messaggi al cloud.

    Screenshot dei dati di telemetria dei dispositivi in IoT Explorer

    Nota

    È anche possibile monitorare i dati di telemetria dal dispositivo usando l'app Termite.

  4. Selezionare la casella di controllo Mostra eventi modellati per visualizzare gli eventi nel formato dati specificato dal modello di dispositivo.

    Screenshot degli eventi di telemetria modellati in IoT Explorer

  5. Selezionare Arresta per terminare la ricezione di eventi.

Per usare l'interfaccia della riga di comando di Azure per visualizzare i dati di telemetria dei dispositivi:

  1. Eseguire il comando az iot hub monitor-events . Usare i nomi creati in precedenza in Azure IoT per il dispositivo e l'hub IoT.

     az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}

  2. Visualizzare l'output JSON nella console.

     {
     "event": {
         "origin": "mydevice",
         "module": "",
         "interface": "dtmi:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

  3. Selezionare CTRL+C per terminare il monitoraggio.

Chiamare un metodo diretto nel dispositivo

È anche possibile usare Azure IoT Explorer per chiamare un metodo diretto implementato nel dispositivo. I metodi diretti hanno un nome e possono facoltativamente avere un payload JSON, una connessione configurabile e un timeout del metodo. In questa sezione viene chiamato un metodo che attiva o disattiva un LED. Facoltativamente, è possibile eseguire la stessa attività usando l'interfaccia della riga di comando di Azure.

Per chiamare un metodo in Azure IoT Explorer:

  1. Nel riquadro componenti di Plug and Play IoT (componente predefinito) per il dispositivo in IoT Explorer selezionare la scheda Comandi.

  2. Per il comando setLedState impostare lo statosu true.

  3. Selezionare Invia comando. Verrà visualizzata una notifica in IoT Explorer e la luce LED utente gialla sul dispositivo dovrebbe essere attivata.

    Screenshot della chiamata al metodo setLedState in IoT Explorer

  4. Impostare lo statosu false e quindi selezionare Invia comando. Il LED utente giallo deve essere spento.

  5. Facoltativamente, è possibile visualizzare l'output in Termite per monitorare lo stato dei metodi.

Per usare l'interfaccia della riga di comando di Azure per chiamare un metodo:

  1. Eseguire il comando az iot hub invoke-device-method e specificare il nome e il payload del metodo. Per questo metodo, impostare method-payload per true attivare il LED e impostarlo su false disattivarlo.

    az iot hub invoke-device-method --device-id mydevice --method-name setLedState --method-payload true --hub-name {YourIoTHubName}

    La console dell'interfaccia della riga di comando mostra lo stato della chiamata al metodo nel dispositivo, dove 204 indica l'esito positivo.

    {
  "payload": {},
  "status": 200
}

  2. Controllare il dispositivo per confermare lo stato del LED.

  3. Visualizzare il terminale Termite per confermare i messaggi di output:

     Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

Risolvere i problemi ed eseguire il debug

Se si verificano problemi durante la compilazione del codice del dispositivo, il flashing del dispositivo o la connessione, vedere Risoluzione dei problemi.

Per il debug dell'applicazione, vedere Debug con Visual Studio Code.

Pulire le risorse

Se le risorse di Azure create in questa guida introduttiva non sono più necessarie, è possibile usare l'interfaccia della riga di comando di Azure per eliminare il gruppo di risorse e tutte le relative risorse.

Importante

L'eliminazione di un gruppo di risorse è irreversibile. Il gruppo di risorse e tutte le risorse in esso contenute vengono eliminati in modo permanente. Assicurarsi di non eliminare accidentalmente il gruppo di risorse sbagliato o le risorse errate.

Per eliminare un gruppo di risorse per nome:

  1. Eseguire il comando az group delete. Questo comando rimuove il gruppo di risorse, il hub IoT e la registrazione del dispositivo creata.

    az group delete --name MyResourceGroup

  2. Eseguire il comando az group list per verificare che il gruppo di risorse sia stato eliminato.

    az group list

Passaggi successivi

In questa esercitazione è stata creata un'immagine personalizzata che contiene il codice di esempio Eclipse ThreadX e quindi è stata visualizzata l'immagine nel dispositivo MXCHIP DevKit. È stata usata anche l'interfaccia della riga di comando di Azure e/o IoT Explorer per creare risorse di Azure, connettere MXCHIP DevKit in modo sicuro ad Azure, visualizzare i dati di telemetria e inviare messaggi.

Come passaggio successivo, vedere l'articolo seguente per altre informazioni sulle opzioni di sviluppo incorporate.

Altre informazioni sulla connessione di dispositivi incorporati con C SDK e Embedded C SDK

Eclipse ThreadX fornisce agli OEM componenti per proteggere la comunicazione e creare codice e isolamento dei dati usando meccanismi di protezione hardware MCU/MPU sottostanti. Tuttavia, ogni OEM è in ultima analisi responsabile di garantire che il dispositivo soddisfi i requisiti di sicurezza in continua evoluzione.