Personalizzare una soluzione preconfigurata

Articolo
11/02/2017

Le soluzioni preconfigurate disponibili in Azure IoT Suite dimostrano come i servizi nella suite si integrano per fornire una soluzione end-to-end. Esistono poi diverse posizioni in cui è possibile personalizzare ed estendere la soluzione per adattarla a scenari specifici. Le sezioni seguenti descrivono questi punti di personalizzazione comuni.

Trovare il codice sorgente

Il codice sorgente per le soluzioni preconfigurate è disponibile in GitHub nei repository seguenti:

Monitoraggio remoto: https://www.github.com/Azure/azure-iot-remote-monitoring
Manutenzione predittiva: https://github.com/Azure/azure-iot-predictive-maintenance
Fabbrica connessa: https://github.com/Azure/azure-iot-connected-factory

Il codice sorgente per le soluzioni preconfigurate viene fornito per illustrare i modelli e le procedure usate per implementare la funzionalità end-to-end di una soluzione IoT tramite Azure IoT Suite. È possibile trovare altre informazioni su come compilare e distribuire le soluzioni in repository GitHub.

Modificare le regole preconfigurate

La soluzione di monitoraggio remoto include tre processi di Analisi di flusso di Azure per gestire le informazioni sul dispositivo, la telemetria e la logica delle regole nella soluzione.

I tre processi di analisi di flusso e la relativa sintassi sono descritti in dettaglio in Procedura dettagliata della soluzione preconfigurata per il monitoraggio remoto.

È possibile modificare questi processi direttamente per alterare la logica o aggiungere una logica specifica allo scenario. È possibile trovare i processi di analisi di flusso come segue:

Passare al portale di Azure.
Passare a un nuovo gruppo di risorse con lo stesso nome della soluzione IoT.
Selezionare il processo di Analisi di flusso di Azure che si vuole modificare.
Arrestare il processo selezionando Arresta nel set di comandi.
Modificare i valori di input, query e output.

Una semplice modifica consiste nel modificare la query per il processo Rules in modo da usare un "<" anziché un ">". Il portale della soluzione visualizza ancora ">" quando si modifica una regola, ma si noti che il comportamento viene capovolto a causa della modifica nel processo sottostante.
Avviare il processo

Nota

Il dashboard per il monitoraggio remoto dipende da dati specifici, quindi la modifica dei processi può causare un errore del dashboard.

Aggiungere le regole personalizzate

Oltre a modificare i processi preconfigurati di analisi di flusso di Azure, è possibile usare il portale di Azure per aggiungere nuovi processi o nuove query ai processi esistenti.

Personalizzare i dispositivi

Una delle attività di estensione più comuni è l'uso di dispositivi specifici per lo scenario. Esistono diversi metodi per usare i dispositivi, tra cui modificare un dispositivo simulato in modo che corrisponda allo scenario o usare l'IoT Device SDK per connettere il dispositivo fisico alla soluzione.

Per indicazioni dettagliate sull'aggiunta di dispositivi, vedere l'articolo Dispositivi di connessione a Iot Suite e Remote monitoring C SDK Sample (Esempio C SDK per il monitoraggio remoto). Questo esempio è stato progettato in modo specifico per la soluzione preconfigurata per il monitoraggio remoto.

Creare il dispositivo simulato

Nel codice sorgente della soluzione di monitoraggio remoto è incluso un simulatore .NET. Il provisioning di questo simulatore viene eseguito nell'ambito della soluzione ed è possibile modificarlo per inviare metadati diversi, la telemetria o per rispondere a comandi e metodi diversi.

Il simulatore preconfigurato nella soluzione preconfigurata per il monitoraggio remoto simula un dispositivo ad accesso sporadico che emette dati di telemetria su temperatura e umidità. È possibile modificare il simulatore nel progetto Simulator.WebJob una volta duplicato il repository di GitHub.

Posizioni disponibili per i dispositivi simulati

Il set predefinito di posizioni si trova a Seattle/Redmond, Washington, Stati Uniti d'America. È possibile modificare queste località nel file SampleDeviceFactory.cs.

Aggiungere un gestore di aggiornamento della proprietà desiderata al simulatore

È possibile configurare un valore per la proprietà desiderata per un dispositivo nel portale della soluzione. La gestione della richiesta di modifica della proprietà quando il dispositivo recupera il valore della proprietà desiderata è a carico del dispositivo. Per aggiungere il supporto per una modifica del valore della proprietà tramite una proprietà desiderata, è necessario aggiungere un gestore al simulatore.

Il simulatore contiene gestori per le proprietà SetPointTemp e TelemetryInterval che possono essere aggiornate impostando i valori desiderati nel portale della soluzione.

L'esempio seguente mostra il gestore per la proprietà desiderata SetPointTemp nella classe CoolerDevice:

protected async Task OnSetPointTempUpdate(object value)
{
    var telemetry = _telemetryController as ITelemetryWithSetPointTemperature;
    telemetry.SetPointTemperature = Convert.ToDouble(value);

    await SetReportedPropertyAsync(SetPointTempPropertyName, telemetry.SetPointTemperature);
}

Questo metodo aggiorna la temperatura del punto dati di telemetria e quindi segnala la modifica all'hub IoT impostando una proprietà segnalata.

È possibile aggiungere gestori personalizzati per le proprietà specifiche seguendo il modello dell'esempio precedente.

È anche necessario associare la proprietà desiderata al gestore, come illustrato nell'esempio seguente dal costruttore CoolerDevice:

_desiredPropertyUpdateHandlers.Add(SetPointTempPropertyName, OnSetPointTempUpdate);

Si noti che SetPointTempPropertyName è una costante definita come "Config.SetPointTemp".

Aggiungere il supporto per un nuovo metodo al simulatore

È possibile personalizzare il simulatore per aggiungere il supporto per un nuovo metodo (metodo diretto). La procedura prevede due passaggi principali:

Il simulatore deve inviare una notifica all'hub IoT nella soluzione preconfigurata con i dettagli del metodo.
Il simulatore deve includere il codice per gestire la chiamata al metodo quando viene richiamato dal pannello Dettagli dispositivo in Esplora soluzioni o tramite un processo.

La soluzione preconfigurata per il monitoraggio remoto usa le proprietà segnalate per inviare i dettagli dei metodi supportati all'hub IoT. Il back-end della soluzione gestisce un elenco di tutti i metodi supportati da ogni dispositivo, insieme a una cronologia delle chiamate al metodo. È possibile visualizzare queste informazioni sui dispositivi e richiamare i metodi nel portale della soluzione.

Per segnalare all'hub IoT che un dispositivo supporta un metodo, il dispositivo deve aggiungere i dettagli del metodo al nodo SupportedMethods nelle proprietà segnalate:

"SupportedMethods": {
  "<method signature>": "<method description>",
  "<method signature>": "<method description>"
}

La firma del metodo ha il formato seguente: <method name>--<parameter #0 name>-<parameter #1 type>-...-<parameter #n name>-<parameter #n type>. Per specificare, ad esempio, che il metodo InitiateFirmwareUpdate prevede un parametro di stringa denominato FwPackageURI, usare la firma del metodo seguente:

InitiateFirmwareUpate--FwPackageURI-string: "description of method"

Per un elenco di tipi di parametri supportati, vedere la classe CommandTypes nel progetto Infrastructure.

Per eliminare un metodo, impostare la firma del metodo su null nelle proprietà segnalate.

Nota

Il back-end della soluzione aggiorna solo le informazioni sui metodi supportati quando riceve un messaggio sulle informazioni del dispositivo dal dispositivo.

L'esempio di codice seguente dalla classe SampleDeviceFactory nel progetto Common mostra come aggiungere un metodo all'elenco SupportedMethods nelle proprietà segnalate inviate dal dispositivo:

device.Commands.Add(new Command(
    "InitiateFirmwareUpdate",
    DeliveryType.Method,
    "Updates device Firmware. Use parameter 'FwPackageUri' to specifiy the URI of the firmware file, e.g. https://iotrmassets.blob.core.windows.net/firmwares/FW20.bin",
    new[] { new Parameter("FwPackageUri", "string") }
));

Questo frammento di codice aggiunge i dettagli del metodo InitiateFirmwareUpdate, incluso il testo da visualizzare nel portale della soluzione e i dettagli dei parametri del metodo necessario.

Il simulatore invia le proprietà segnalate, incluso l'elenco dei metodi supportati, all'hub IoT quando viene avviato.

Aggiungere un gestore al codice del simulatore per ogni metodo supportato. È possibile visualizzare i gestori esistenti nella classe CoolerDevice del progetto Simulator.WebJob. L'esempio seguente mostra il gestore per il metodo InitiateFirmwareUpdate:

public async Task<MethodResponse> OnInitiateFirmwareUpdate(MethodRequest methodRequest, object userContext)
{
    if (_deviceManagementTask != null && !_deviceManagementTask.IsCompleted)
    {
        return await Task.FromResult(BuildMethodRespose(new
        {
            Message = "Device is busy"
        }, 409));
    }

    try
    {
        var operation = new FirmwareUpdate(methodRequest);
        _deviceManagementTask = operation.Run(Transport).ContinueWith(async task =>
        {
            // after firmware completed, we reset telemetry
            var telemetry = _telemetryController as ITelemetryWithTemperatureMeanValue;
            if (telemetry != null)
            {
                telemetry.TemperatureMeanValue = 34.5;
            }

            await UpdateReportedTemperatureMeanValue();
        });

        return await Task.FromResult(BuildMethodRespose(new
        {
            Message = "FirmwareUpdate accepted",
            Uri = operation.Uri
        }));
    }
    catch (Exception ex)
    {
        return await Task.FromResult(BuildMethodRespose(new
        {
            Message = ex.Message
        }, 400));
    }
}

I nomi dei gestori dei metodi devono iniziare con On, seguito dal nome del metodo. Il parametro methodRequest contiene tutti i parametri passati con la chiamata al metodo dal back-end della soluzione. Il valore restituito deve essere di tipo Task<MethodResponse>. Il metodo BuildMethodResponse dell'utilità consente di creare il valore restituito.

All'interno del gestore del metodo è possibile eseguire queste operazioni:

Avviare un'attività asincrona.
Recuperare le proprietà desiderate dal dispositivo gemello nell'hub IoT.
Aggiornare una singola proprietà segnalata usando il metodo SetReportedPropertyAsync nella classe CoolerDevice.
Aggiornare più proprietà segnalate creando un'istanza di TwinCollection e chiamando il metodo Transport.UpdateReportedPropertiesAsync.

L'esempio precedente di aggiornamento del firmware segue questa procedura:

Controlla che il dispositivo sia in grado di accettare la richiesta di aggiornamento del firmware.
Avvia in modo asincrono l'operazione di aggiornamento del firmware e reimposta i dati di telemetria al termine dell'operazione.
Restituisce immediatamente il messaggio "FirmwareUpdate accepted" per indicare che la richiesta è stata accettata dal dispositivo.

Compilare e usare il proprio dispositivo (fisico)

Gli SDK Azure IoT forniscono librerie per la connessione di numerosi tipi di dispositivi (linguaggi e sistemi operativi) alle soluzioni IoT.

Modificare i limiti del dashboard

Il valore predefinito è 200. È possibile modificare questo numero nel file DashboardController.cs.

Numero di pin da visualizzare nel controllo di Bing Mappe

Il valore predefinito è 200. È possibile modificare questo numero nel file TelemetryApiController.cs.

Periodo di tempo del grafico di dati di telemetria

Il valore predefinito è 10 minuti. È possibile modificare questo valore nel file TelmetryApiController.cs.

Commenti e suggerimenti

Per altre informazioni relative a una personalizzazione, Inviare suggerimenti sulla funzionalità a User Voice oppure lasciare un commento nell'apposita sezione di questo articolo.

Passaggi successivi

Per altre informazioni sulle opzioni per personalizzare le soluzioni preconfigurate, vedere: