Compartilhar via

Personalizar uma solução pré-configurada

  • Artigo

As soluções pré-configuradas fornecidas com o Pacote IoT do Azure demonstram os serviços no pacote trabalhando juntos para fornecer uma solução de ponta a ponta. Do ponto de partida, há diversos lugares nos quais você pode estender e personalizar a solução para cenários específicos. As seções a seguir descrevem esses pontos comuns de personalização.

Localizar o código-fonte

O código-fonte para a solução pré-configurada está disponível no GitHub nos seguintes repositórios:

O código-fonte para as soluções pré-configuradas é fornecido para demonstrar os padrões e as práticas usadas para implementar a funcionalidade de ponta a ponta de uma solução IoT usando o Azure IoT Suite. Você pode encontrar mais informações sobre como compilar e implantar as soluções em repositórios GitHub.

Alterar as regras pré-configuradas

A solução de monitoramento remoto inclui três trabalhos do Stream Analytics do Azure para lidar com informações do dispositivo, telemetria e lógica de regras na solução.

Os três trabalhos de Stream Analytics e sua sintaxe são descritos em detalhes na Passo a passo da solução pré-configurada de monitoramento remoto.

Você pode editar esses trabalhos diretamente para alterar a lógica ou adicionar lógica específica para seu cenário. Você pode encontrar os trabalhos do Stream Analytics da seguinte maneira:

  1. Vá para o portal do Azure.

  2. Navegue até o grupo de recursos com o mesmo nome da sua solução IoT.

  3. Selecione o trabalho de Stream Analytics do Azure que você deseja modificar.

  4. Interrompa o trabalho selecionando Pararno conjunto de comandos.

  5. Edite as entradas, consulta e saídas.

    Uma modificação simples é alterar a consulta do trabalho Regras para usar um "<" em vez de um ">". O portal da solução ainda mostra ">" quando você edita uma regra, mas percebe como o comportamento é invertido devido à alteração no trabalho subjacente.

  6. Iniciar o trabalho

Observação

O painel de monitoramento remoto depende de dados específicos, por isso, alterar os trabalhos pode fazer com que o painel falhe.

Adicionar suas próprias regras

Além de alterar os trabalhos de Stream Analytics do Azure, você pode usar o portal do Azure para adicionar novos trabalhos ou adicionar novas consultas para trabalhos existentes.

Personalizar dispositivos

Uma das atividades mais comuns de extensão é o trabalho com dispositivos específicos ao seu cenário. Há vários métodos para trabalhar com dispositivos. Esses métodos incluem alterar um dispositivo simulado de acordo com seu cenário ou usar o SDK de Dispositivo IoT para conectar seu dispositivo físico à solução.

Para obter um guia passo a passo para adicionar dispositivos, consulte o artigo Dispositivos de Conexão do Iot Suite e o Exemplo de SDK para o monitoramento remoto em C. Este exemplo é projetado para trabalhar com a solução pré-configurada de monitoramento remoto.

Criar seu próprio dispositivo simulado

Incluído no código-fonte da solução de monitoramento remota, é um simulador de .NET. Esse simulador é provisionado como parte da solução e pode ser alterado para enviar metadados diferentes, telemetria, e responder a comandos e métodos diferentes.

O simulador pré-configurado na solução pré-configurada de monitoramento remoto simula um dispositivo mais frio que emite a temperatura e a telemetria da umidade. Você pode modificar o simulador no projeto Simulator.WebJob quando tiver dividido o repositório GitHub.

Locais disponíveis para dispositivos simulados

O conjunto padrão de locais fica em Seattle/Redmond, Washington, Estados Unidos. É possível alterar esses locais em SampleDeviceFactory.cs.

Adicionar um manipulador de atualização da propriedade desejada ao simulador

Você pode definir um valor para uma propriedade desejada para um dispositivo no portal de solução. É responsabilidade do dispositivo lidar com a solicitação de alteração da propriedade quando o dispositivo recupera o valor da propriedade desejada. Para adicionar suporte para uma alteração de valor da propriedade por meio de uma propriedade desejada, você precisa adicionar um manipulador ao simulador.

O simulador contém manipuladores para as propriedades SetPointTemp e TelemetryInterval que você pode atualizar definindo os valores desejados no portal da solução.

O exemplo a seguir mostra o manipulador para a propriedade desejada SetPointTemp na classe CoolerDevice:

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

    await SetReportedPropertyAsync(SetPointTempPropertyName, telemetry.SetPointTemperature);
}

Esse método atualiza a temperatura do ponto de telemetria, em seguida, informa a alteração ao Hub IoT definindo uma propriedade relatada.

Você pode adicionar seus próprios manipuladores para suas próprias propriedades seguindo o padrão no exemplo anterior.

Você também deve associar a propriedade desejada ao manipulador como mostrado no exemplo a seguir do construtor CoolerDevice:

_desiredPropertyUpdateHandlers.Add(SetPointTempPropertyName, OnSetPointTempUpdate);

Observe que SetPointTempPropertyName é uma constante definida como "Config.SetPointTemp".

Adicionar o suporte de um novo método ao simulador

Você pode personalizar o simulador para adicionar o suporte de um novo método (método direto). Há duas etapas principais necessárias:

  • O simulador deve notificar o Hub IoT na solução pré-configurada com os detalhes do método.
  • O simulador deve incluir o código para lidar com a chamada do método quando você o chama no painel Detalhes do dispositivo no Gerenciador de Soluções ou por meio de um trabalho.

A solução pré-configurada de monitoramento remoto usa as propriedades relatadas para enviar os detalhes dos métodos com suporte para o Hub IoT. O back-end de solução mantém uma lista de todos os métodos suportados por cada dispositivo junto com um histórico de chamadas do método. Você pode exibir essas informações sobre os dispositivos e chamar os métodos no portal de solução.

Para notificar o Hub IoT que um dispositivo oferece suporte a um método, o dispositivo deve adicionar os detalhes do método ao nó SupportedMethods nas propriedades relatadas:

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

A assinatura do método tem o seguinte formato: <method name>--<parameter #0 name>-<parameter #1 type>-...-<parameter #n name>-<parameter #n type>. Por exemplo, para especificar o método InitiateFirmwareUpdate que espera um parâmetro da cadeia de caracteres denominado FwPackageURI, use a assinatura do método a seguir:

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

Para obter uma lista dos tipos de parâmetro com suporte, consulte a classe CommandTypes no projeto de infraestrutura.

Para excluir um método, defina a assinatura do método para null nas propriedades relatadas.

Observação

O back-end de solução só atualiza as informações sobre os métodos com suporte quando ele recebe uma mensagem de informações do dispositivo a partir do dispositivo.

O exemplo de código a seguir da classe SampleDeviceFactory no projeto Common mostra como adicionar um método à lista de SupportedMethods nas propriedades relatadas enviadas pelo 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") }
));

Esse snippet de código adiciona os detalhes do método InitiateFirmwareUpdate, incluindo o texto a exibir no portal de solução e os detalhes dos parâmetros do método necessários.

O simulador envia as propriedades relatadas, incluindo a lista de métodos com suporte, ao Hub IoT quando o simulador inicia.

Adicione um manipulador ao código do simulador para cada método com suporte. Você pode ver os manipuladores existentes na classe CoolerDevice no projeto Simulator.WebJob. O exemplo a seguir mostra o manipulador do método 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));
    }
}

Os nomes do manipulador do método devem começar com On seguido do nome do método. O parâmetro methodRequest contém todos os parâmetros passados com a chamada do método a partir do back-end da solução. O valor de retorno deve ser do tipo Task<MethodResponse>. O método utilitário BuildMethodResponse ajuda a criar o valor de retorno.

No manipulador do método, você pode:

  • iniciar uma tarefa assíncrona.
  • recuperar as propriedades desejadas no dispositivo gêmeo no Hub IoT.
  • atualizar uma única propriedade relatada usando o método SetReportedPropertyAsync na classe CoolerDevice.
  • atualizar várias propriedades relatadas criando uma instância TwinCollection e chamar o método Transport.UpdateReportedPropertiesAsync.

O exemplo anterior de atualização do firmware executa as seguintes etapas:

  • verifica se o dispositivo é capaz de aceitar a solicitação de atualização do firmware.
  • inicia de forma assíncrona a operação de atualização do firmware e redefine a telemetria quando a operação é concluída.
  • retorna imediatamente a mensagem "FirmwareUpdate aceito" para indicar que a solicitação foi aceita pelo dispositivo.

Compilar e usar seu próprio dispositivo (físico)

Os SDKs do Azure IoT fornecem bibliotecas para conectar a vários tipos de dispositivo (linguagens e sistemas operacionais) em soluções de IoT.

Modificar os limites do painel

Número de dispositivos exibida na lista suspensa do painel

O padrão é 200. É possível alterar esse número em DashboardController.cs.

Número de marcações a serem exibidas no controle do Mapa do Bing

O padrão é 200. É possível alterar esse número em TelemetryApiController.cs.

Período do grafo de telemetria

O padrão é 10 minutos. É possível alterar esse valor em TelmetryApiController.cs.

Comentários

Há alguma personalização que você gostaria que fosse abordada neste documento? Adicione sugestões de recursos ao User Voiceou faça comentários sobre este artigo.

Próximas etapas

Para saber mais sobre as opções para personalizar as soluções pré-configuradas, confira: