Configurar o Azure IoT Edge para o Azure Sphere

Artigo
11/05/2024

Importante

Esta é a documentação do Azure Sphere (herdado). O Azure Sphere (herdado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).

O Azure IoT Edge fornece uma camada de filtragem e processamento de dados entre um dispositivo downstream, como o Azure Sphere e o Hub IoT do Azure. Considere usar o Azure IoT Edge se o dispositivo do Azure Sphere produzir uma quantidade considerável de dados ou dados que exijam pós-processamento.

Este tópico documenta as etapas para configurar um dispositivo Azure IoT Edge com o Azure Sphere. O Azure Sphere dá suporte às versões 1.1 e 1.2 do Azure IoT Edge; diferenças significativas são observadas nas instruções. As diferenças principais são:

O nome do pacote mudou de iotedge para aziot-edge.
O arquivo de configuração padrão tem um novo nome e local. No Azure IoT Edge 1.1, o arquivo de configuração era /etc/iotedge/config.yaml. No Azure IoT Edge 1.2, o arquivo de configuração é /etc/aziot/config.toml.
O Azure IoT Edge 1.2 requer um FQDN (nome de domínio totalmente qualificado) acessível por meio de um servidor DNS na rede.

Depois de concluir as tarefas neste tópico, seu dispositivo do Azure Sphere será configurado para enviar dados para um Hub IoT do Azure por meio de um dispositivo do Azure IoT Edge que atua como um gateway transparente. Você pode adicionar filtragem e processamento de dados adicionais com um módulo no dispositivo Azure IoT Edge seguindo o guia do Módulo do Azure IoT Edge.

Antes de começar

As etapas neste tópico pressupõem que:

Seu dispositivo do Azure Sphere está conectado ao seu computador por USB.
Você tem uma assinatura do Azure.
Você criou uma instância do Hub IoT do Azure e provisionou manualmente um dispositivo. Observe que você precisará usar o certificado de autoridade de certificação do locatário para o Hub IoT posteriormente no procedimento (Etapa 6).
Você criou um grupo de recursos e todos os recursos relacionados aos serviços do Hub IoT do Azure e do IoT Edge devem pertencer a esse grupo de recursos.

Importante

Embora você possa criar uma assinatura do Azure sem custos, o processo de inscrição exige que você insira um número de cartão de crédito. O Azure fornece vários níveis de serviço de assinatura. Por padrão, a camada Standard, que requer um encargo de serviço mensal, é selecionada quando você cria uma instância do Hub IoT do Azure. Para evitar uma cobrança mensal, selecione a Camada gratuita. A camada Gratuita inclui os serviços necessários para usar seu dispositivo com uma instância do Hub IoT do Azure, incluindo o Dispositivo Gêmeo. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Visão geral

Configurar um dispositivo Azure IoT Edge e configurá-lo para funcionar com um dispositivo Azure Sphere requer um processo de várias etapas e você deve planejar cerca de 8 horas para trabalhar nas etapas, especialmente se não estiver familiarizado com o Azure IoT Edge. Se esta for a primeira vez que você trabalha com o Azure IoT Edge, siga as instruções de início rápido em cada seção para instalar e configurar um dispositivo IoT Edge executado em uma máquina virtual Linux.

Essas etapas devem ser concluídas apenas uma vez por locatário do Azure Sphere e dispositivo Azure IoT Edge; no entanto, cada dispositivo do Azure Sphere deve ser configurado manualmente no Hub IoT do Azure e o dispositivo do Azure IoT Edge deve ser definido como o pai do dispositivo do Azure Sphere.

As etapas de configuração podem ser divididas em três agrupamentos lógicos:

Criar e configurar o dispositivo IoT Edge como um gateway transparente
- Etapa 1. Criar um dispositivo do Azure IoT Edge.
- Etapa 2. Configure o dispositivo de gateway do Azure IoT Edge como um servidor.
- Etapa 3. Abra as portas do dispositivo do gateway do Azure IoT Edge para comunicação.
- Etapa 4. Atualize o nome do host do gateway em config.toml (Azure IoT Edge versão 1.2) ou config.yaml (Azure IoT Edge versão 1.1).
Configurar o dispositivo do Azure Sphere no Hub IoT do Azure
- Etapa 5. Defina o dispositivo Azure IoT Edge como pai do dispositivo Azure Sphere.
Estabelecer uma conexão confiável entre o dispositivo do Azure Sphere e o dispositivo IoT Edge
- Etapa 6. Forneça o certificado de autoridade de certificação do locatário do dispositivo do Azure Sphere para o dispositivo do Azure IoT Edge.
- Etapa 7. Forneça o certificado de autoridade de certificação raiz do dispositivo Azure IoT Edge para o dispositivo do Azure Sphere.

Etapa 1. Criar um dispositivo Azure IoT Edge

Você deve configurar um dispositivo Azure IoT Edge e registrá-lo no Hub IoT do Azure, caso ainda não tenha feito isso.

Você pode usar o DPS (Serviço de Provisionamento de Dispositivos) para provisionar o dispositivo Azure IoT Edge. No entanto, você não pode usar o DPS para provisionar o dispositivo do Azure Sphere. Não há suporte para o provisionamento automático de dispositivos downstream do dispositivo Azure IoT Edge com o DPS do Hub IoT do Azure.

Você pode seguir as etapas no Início Rápido do IoT Edge para configurar um dispositivo Azure IoT Edge executado em uma VM Linux ou dispositivo Windows e registrá-lo no Hub IoT do Azure.

Use as etapas no Início Rápido para:

Registre um dispositivo do Azure IoT Edge em sua instância do Hub IoT do Azure. Não crie um novo hub IoT nesta etapa, apenas registre seu dispositivo Azure IoT Edge no hub IoT que você já criou.
Instale e inicie o runtime do Azure IoT Edge em seu dispositivo Azure IoT Edge.

Observação

No Início Rápido do IoT Edge, pare antes de implantar um módulo.

Etapa 2. Configurar o dispositivo de gateway do IoT Edge como um servidor

Siga as instruções para Configurar um dispositivo Azure IoT Edge para atuar como um gateway transparente (Azure IoT Edge 1.2) ou Azure IoT Edge 1.1, mas pare quando chegar à seção "Abrir portas no dispositivo de gateway". Embora essas instruções solicitem que você copie os arquivos de certificado para o dispositivo IoT Edge, não copie os arquivos para a VM até a Etapa 8 deste procedimento.

Como parte das etapas concluídas para configurar o gateway de dispositivo como um servidor, você já terá:

Configurados os certificados de dispositivo do Azure IoT Edge.
Implantado o módulo de hub do Azure IoT Edge.
Roteamento de mensagens configurado por meio do Azure IoT Edge.

Também como parte dessas etapas, você terá criado estes certificados:

Certificado de CA raiz: certs/azure-iot-test-only.root.ca.cert.pem
Certificado de AC do dispositivo e chave privada (usados para registrar o dispositivo IoT Edge no Hub IoT):
- certs/iot-edge-device-identity-<cert-name>-full-chain.cert.pem
- private/iot-edge-device-identity-<cert-name>.key.pem
Certificado de autoridade de certificação e chave privada do IoT Edge (a serem copiados para um dispositivo IoT Edge e referenciados em seu arquivo de configuração):
- certs/iot-edge-device-ca-<cert-name>-full-chain.cert.pem
- private/iot-edge-device-ca-<cert-name>.key.pem

Se você estiver seguindo o Início Rápido, use as instruções do Linux para configurar os certificados de demonstração se o computador no qual você está gerando os certificados for um computador baseado em Linux. Use as instruções do Windows para gerar os certificados de demonstração se o computador no qual você está gerando os certificados for um computador baseado no Windows. Consulte a seção para copiar certificados raiz para uma VM Linux ou para um computador Windows local.

O certificado de AC raiz do Azure IoT Edge será modificado na Etapa 7, mas você precisará do certificado original na Etapa 8. Guarde uma cópia do certificado original para que você possa reutilizá-lo.

Observação

Ao atualizar a seção de certificados do arquivo config.toml (Azure IoT Edge 1.2) ou config.yaml (Azure IoT Edge 1.1), verifique se a certificates: linha no config.toml (Azure IoT Edge 1.2) ou config.yaml (Azure IoT Edge 1.1) não tem espaço em branco anterior e se cada um dos certificados aninhados é recuado por dois espaços.

Depois de atualizar o arquivo, verifique se o módulo edgehub está em execução no dispositivo Azure IoT Edge:

sudo iotedge list

Para obter mais informações, consulte Como um dispositivo IoT Edge pode ser usado como um gateway (Azure IoT Edge 1.2) ou Azure IoT Edge 1.1.

Se você estiver usando certificados de teste, pare antes de gerar o certificado de dispositivo downstream, conforme documentado em Criar certificados de dispositivo downstream (Azure IoT Edge 1.2) ou Azure IoT Edge 1.1.

Etapa 3. Abrir portas de dispositivo do gateway do Azure IoT Edge para comunicação

Os dispositivos de gateway devem ser capazes de receber mensagens de seus dispositivos downstream. Para que um cenário de gateway funcione, pelo menos um dos protocolos com suporte do hub IoT deve estar aberto para tráfego de entrada de dispositivos downstream.

O Azure Sphere usa o protocolo MQTT. Este protocolo usa a porta 8883.

Para obter mais informações, consulte Abrir portas no dispositivo de gateway (Azure IoT Edge 1.2) ou Azure IoT Edge 1.1.

Siga estas etapas para abrir a porta 8883 em uma VM do Windows depois de configurar um dispositivo Edge no Início Rápido:

Se necessário, faça logon no portal do Azure usando sua conta do Azure.
Navegue até a máquina virtual que você criou na seção Etapa 1: Criar um dispositivo Azure IoT Edge.
Na seção Configurações à esquerda, selecione Rede e, em seguida, Adicionar regra de porta de entrada.
Na folha Adicionar regra de porta de entrada, em Intervalos de portas de destino, altere o valor para 8883.
Em Protocolo, selecione TCP.
Em Nome, altere o valor para MQTT.
Deixe todas as outras configurações como padrão e selecione Adicionar.

Siga estas etapas para abrir a porta 8883 em uma VM Linux depois de configurar um dispositivo Azure IoT Edge no Início Rápido:

Execute o seguinte comando para verificar se a porta para MQTT está aberta:

sudo netstat -lptu
Se necessário, use o seguinte comando para abrir a porta:

sudo ufw allow 8883

Isso definirá uma regra de segurança de entrada para permitir a comunicação do protocolo MQTT com o Gateway do Azure IoT Edge.

Etapa 4. Atualizar o nome do host do gateway

Esta etapa usa procedimentos diferentes, dependendo da versão do Azure IoT Edge que você está usando: Azure IoT Edge 1.2 ou Azure IoT Edge 1.1.

Azure IoT Edge 1.2: atualizar o nome do host do gateway em config.toml

O runtime do Azure IoT Edge dá suporte a nomes de host com menos de 64 caracteres. Os computadores físicos geralmente não têm nomes de host longos, mas se você estiver usando uma máquina virtual como o dispositivo Azure IoT Edge, como o exemplo no Início Rápido, deverá configurar manualmente o nome do host.

Para solucionar problemas de um nome de host inválido, consulte resoluções de erros comuns.

Siga estas etapas para configurar o nome do host do dispositivo Azure IoT Edge depois de configurar a porta MQTT no Início Rápido:

Encontre o FQDN (nome de domínio totalmente qualificado) para o gateway do IoT Edge navegando até o dispositivo do IoT Edge (VM do Linux) no Portal do Azure e copiando o valor do nome DNS da página de visão geral.
Se necessário, faça logon no dispositivo Azure IoT Edge.
Abra o arquivo config.toml em um editor de texto.

/etc/aziot/config.toml
Cole o FQDN na seção de nome do host de config.toml. Verifique se o nome é escrito inteiramente em letras minúsculas.
```
hostname: "<iotedge_machinename>.<mydomain>"
```
Observação

Por design com o Azure IoT Edge v1.2 e superior, o nome do host DEVE ser um nome FQDN (um endereço IP não é mais permitido, como na v1.1); portanto, um servidor DNS com o registro A apropriado na mesma rede é obrigatório.
Reinicie o daemon iotedge .

sudo systemctl restart iotedge
Se vir erros (texto colorido prefixado com "[ERRO]") no status, examine os logs do daemon para ver informações de erro detalhadas.

sudo journalctl -u iotedge --no-pager --no-full
Para evitar avisos, defina a configuração DNS para módulos no dispositivo Azure IoT Edge para incluir um arquivo de configuração em /etc/docker/daemon.json, por exemplo:
```
{
     "dns": ["<IP address of your DNS server>"]
}
```

Azure IoT Edge 1.1: Atualizar o nome do host do gateway em config.yaml

Para solucionar problemas de um nome de host inválido, consulte resoluções de erros comuns.

Siga estas etapas para configurar o nome do host do dispositivo Azure IoT Edge depois de configurar a porta MQTT no Início Rápido:

No portal do Azure, navegue até sua máquina virtual. Copie o valor do nome DNS (FQDN do computador) da seção Visão geral .
Se necessário, faça logon no dispositivo Azure IoT Edge.
Abra o arquivo config.yaml em um editor de texto.

/etc/iotedge/config.yaml
Cole o FQDN na seção hostname de config.yaml. Verifique se o nome é escrito inteiramente em letras minúsculas.
```
`hostname: "<machinename>.<region>.cloudapp.azure.com"`
```
Observação

Talvez seja necessário usar o nome do computador simples para o nome do host (o endereço IP ou o nome do host real) se um resolvedor de DNS estiver na rede, já que o Azure Sphere não dá suporte a netbios.
Reinicie o daemon iotedge .

sudo systemctl restart iotedge
Se vir erros (texto colorido prefixado com "[ERRO]") no status, examine os logs do daemon para ver informações de erro detalhadas.

sudo journalctl -u iotedge --no-pager --no-full
Para evitar avisos, defina a configuração DNS para módulos no dispositivo Azure IoT Edge para incluir um arquivo de configuração em /etc/docker/daemon.json, por exemplo:
```
{
    "dns": ["<IP address of your DNS server>"]
}
```

Etapa 5. Definir o dispositivo Azure IoT Edge como pai do dispositivo Azure Sphere

Siga estas etapas para definir o dispositivo Azure IoT Edge como o pai do dispositivo Azure Sphere:

Navegue até o dispositivo do Azure Sphere que foi provisionado manualmente acima.
Selecione ID do Dispositivo.
Selecione o ícone de engrenagem em Nenhum dispositivo pai.
Selecione o dispositivo Azure IoT Edge que você deseja definir como pai.
Selecione OK e, em seguida, Salvar.

O dispositivo Azure IoT Edge agora se torna o pai do dispositivo Azure Sphere.

Etapa 6. Fornecer o certificado de AC do locatário do dispositivo do Azure Sphere para o dispositivo IoT Edge

Para verificar os certificados de dispositivo do Azure Sphere, o dispositivo do Azure IoT Edge deve ter sua própria cópia da AC do locatário.

Baixe o certificado de autoridade de certificação do locatário, se ainda não tiver feito isso. Observação: você já deve ter concluído isso como parte da configuração do Hub IoT do Azure.
- No prompt de comando, entre com seu logon do Azure Sphere:
```
azsphere login
```
- Baixe o certificado de AC para seu locatário do Azure Sphere. Esse comando baixa o certificado para um arquivo chamado CAcertificate.cer no diretório de trabalho atual. Certifique-se de baixar o arquivo para um diretório no qual você tenha permissão de gravação, ou a operação de download falhará. O arquivo de saída deve ter uma extensão .cer.
```
azsphere ca-certificate download --destination CAcertificate.cer
```
Converta o certificado de autoridade de certificação do locatário para o formato PEM. Exemplos de instruções para converter o formato em uma máquina Windows são as seguintes:
- Localize o caminho do certificado em seu computador e clique duas vezes no certificado para abri-lo.
- Abra a guia Detalhes e selecione Copiar para arquivo.
- No assistente de Exportação de Certificado , selecione Avançar.
- Selecione o formato X.509 (CER) codificado em Base-64 e, em seguida, selecione Avançar.
- Insira o nome do arquivo para o certificado a ser exportado e selecione Avançar.
- Selecione Concluir para concluir o assistente.
- Renomeie o arquivo de certificado baixado para ter a extensão de arquivo .pem.
Acrescente o certificado de locatário ao certificado raiz do Azure IoT Edge. Lembre-se de que você criou os certificados do Azure IoT Edge na Etapa 2.
- Se necessário, faça logon no dispositivo Azure IoT Edge.
- Localize o caminho do certificado de autoridade de certificação raiz do dispositivo IoT Edge e abra-o em um editor de texto. Se você seguiu o Início Rápido e usou os scripts fornecidos no repositório Git do Azure IoT Edge para criar certificados de demonstração, o certificado de AC raiz será denominado azure-iot-test-only.root.ca.cert.pem.
- Abra o certificado de AC do Locatário do Azure Sphere (no formato PEM) em um editor de texto. Copie o conteúdo e cole-o no final do certificado de autoridade de certificação raiz do IoT Edge.
- Salve as alterações feitas no certificado de autoridade de certificação raiz do Azure IoT Edge e feche o arquivo.
- Reinicie o dispositivo Azure IoT Edge. Para um dispositivo Linux Azure IoT Edge, execute: sudo systemctl restart iotedge.
- Verifique se os módulos estão em execução no dispositivo Azure IoT Edge. Para um dispositivo Linux Azure IoT Edge, execute: sudo iotedge list.

Etapa 7. Forneça o certificado de autoridade de certificação raiz do dispositivo Azure IoT Edge para o dispositivo do Azure Sphere

Para verificar os certificados de dispositivo do Azure IoT Edge, o dispositivo do Azure Sphere (o dispositivo downstream) deve ter sua própria cópia do certificado de autoridade de certificação raiz do dispositivo do Azure IoT Edge, que você configurou na Etapa 2.

Para obter mais informações, consulte Conectar um dispositivo downstream a um gateway do Azure IoT Edge.

Localize o certificado raiz do dispositivo Azure IoT Edge original.
- Lembre-se de que o certificado raiz do dispositivo Azure IoT Edge original é aquele que você criou na Etapa 2.
- Se você seguiu o Início Rápido e usou os scripts fornecidos no repositório Git do IoT Edge para criar certificados de demonstração, o certificado de autoridade de certificação raiz será chamado azure-iot-test-only.root.ca.cert.pem.
Copie o certificado raiz do Azure IoT Edge para o dispositivo do Azure Sphere adicionando-o ao pacote de aplicativos.
- Para obter etapas detalhadas, consulte Criação de pacote de imagem.
- Consulte a seção para copiar certificados raiz para uma VM Linux ou para um computador Windows local.

Etapa 8. Copiar o certificado raiz da IoT para um computador remoto

Siga estas etapas para copiar o certificado raiz do Azure IoT Edge para uma VM Linux remota ou para um computador Windows local:

Você pode instalar a ferramenta WinSCP para transferir os arquivos. A ferramenta fornece uma GUI para que seja mais fácil de usar do que uma abordagem de linha de comando.
Para usar a linha de comando, use a ferramenta de linha de comando SCP (Secure Copy).
Para transferir um arquivo de um computador Windows local para uma VM Linux remota, execute o seguinte comando no Windows PowerShell:
```
powershell -Command scp -r <path-to-file-name> <userName@remote-ip>:<path-to-destination-directory>
```
Sintaxe de exemplo:

scp C:\Documents\cert.pem AzureUser@edgevmname-west.westus22.cloudapp.azure.com:/home/azureUser/test/
Para transferir um arquivo de uma VM remota do Linux para uma máquina Windows local, execute o seguinte comando no Windows PowerShell:
```
powershell -Command scp -r <userName@remote-ip>:<path-to-file-name> <path-to-destination-dir>
```
Sintaxe de exemplo:

scp azureUser@edgevmname-west.westus22.cloudapp.azure.com:/home/azureUser/test/cert.pem C:\Documents\

Solução de problemas

Se você tiver problemas ao executar o Azure IoT Edge em seu ambiente, use estes artigos para solução de problemas e diagnóstico:

Próximas etapas

Depois de concluir as etapas neste tópico, você pode executar o exemplo de IoT do Azure, seguindo as instruções para se conectar usando o Azure IoT Edge.

Compartilhar via