Configurar o Azure IoT Edge para o Azure Sphere

2025-05-28

O Azure IoT Edge fornece uma camada de filtragem e processamento de dados entre um dispositivo downstream, como o Azure Sphere e o Azure IoT Hub. Considere usar o Azure IoT Edge se seu dispositivo 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 do Azure IoT Edge com o Azure Sphere. O Azure Sphere suporta as versões 1.1 e 1.2 do Azure IoT Edge; Diferenças significativas são notadas nas instruções. As principais diferenças são:

O nome do pacote foi alterado 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 através 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 de Borda do Azure IoT.

Antes de começar

As etapas neste tópico pressupõem que:

Seu dispositivo Azure Sphere está conectado ao seu PC 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 CA do catálogo para o Hub IoT posteriormente no procedimento (Etapa 6).
Você criou um grupo de recursos e todos os recursos relacionados ao Hub IoT do Azure e aos serviços IoT Edge devem pertencer a esse grupo de recursos.

Importante

Embora você possa criar uma assinatura do Azure gratuitamente, 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 Padrão, que exige uma taxa de serviço mensal, é selecionada quando você cria uma instância do Hub IoT do Azure. Para evitar uma cobrança mensal, selecione o nível Gratuito. A camada Gratuita inclui os serviços necessários para usar seu dispositivo com uma instância do Hub IoT do Azure, incluindo o Device Twin. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Visão geral

Configurar um dispositivo do Azure IoT Edge e configurá-lo para funcionar com um dispositivo do 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 catálogo do Azure Sphere e dispositivo do Azure IoT Edge; no entanto, cada dispositivo Azure Sphere deve ser configurado manualmente no Hub IoT do Azure e o dispositivo Azure IoT Edge deve ser definido como o pai do dispositivo 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
- Passo 1. Criar um dispositivo Azure IoT Edge.
- Passo 2. Configure o dispositivo de gateway do Azure IoT Edge como um servidor.
- Passo 3. Abra as portas de dispositivo do gateway do Azure IoT Edge para comunicação.
- Passo 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 Azure Sphere no Hub IoT do Azure
- Passo 5. Defina o dispositivo Azure IoT Edge como pai do dispositivo Azure Sphere.
Estabelecer uma conexão confiável entre o dispositivo Azure Sphere e o dispositivo IoT Edge
- Passo 6. Forneça o certificado de CA do catálogo do dispositivo Azure Sphere para o dispositivo Azure IoT Edge.
- Passo 7. Forneça o certificado de autoridade de certificação raiz do dispositivo Azure IoT Edge para o dispositivo Azure Sphere.

Passo 1. Criar um dispositivo do Azure IoT Edge

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

Você pode usar o Serviço de Provisionamento de Dispositivo (DPS) para provisionar o dispositivo Azure IoT Edge. No entanto, você não pode usar o DPS para provisionar o dispositivo 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 Guia de início rápido do IoT Edge para configurar um dispositivo do Azure IoT Edge executado em uma VM Linux ou dispositivo Windows e registrá-lo no Hub IoT do Azure.

Use as etapas no Guia de 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 tempo de execução do Azure IoT Edge em seu dispositivo Azure IoT Edge.

Observação

No Guia de início rápido do IoT Edge, pare antes de implantar um módulo.

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

Siga as instruções para Configurar um dispositivo do 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 "Portas abertas no dispositivo de gateway". Embora essas instruções digam para copiar os arquivos de certificado para seu dispositivo IoT Edge, não copie os arquivos para sua 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.
Implantou o módulo de hub do Azure IoT Edge.
Roteamento configurado de mensagens por meio do Azure IoT Edge.

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

Certificado de autoridade de certificação raiz: certs/azure-iot-test-only.root.ca.cert.pem
Certificado de autoridade de certificação 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 CA 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 Guia de início rápido, use as instruções do Linux para configurar os certificados de demonstração se a máquina na 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 a máquina na 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 autoridade de certificação 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 poder 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 em seu 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.

Passo 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 a jusante. Para que um cenário de gateway funcione, pelo menos um dos protocolos suportados pelo 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 Guia de início rápido:

Se necessário, inicie sessão no seu portal do Azure utilizando a sua conta do Azure.
Navegue até a máquina virtual que você criou na seção Etapa 1: Criar um dispositivo do 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 Guia de 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 de Borda do Azure IoT.

Passo 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 tempo de execução do Azure IoT Edge dá suporte a nomes de host com menos de 64 caracteres. As máquinas físicas 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 Guia de 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 erro comuns.

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

Encontre o nome de domínio totalmente qualificado (FQDN) para seu gateway IoT Edge navegando até seu dispositivo IoT Edge (VM Linux) no Portal do Azure e copiando o valor para 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 hostname de config.toml. Certifique-se de que o nome é todo minúsculo.
```
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 iotedge daemon.

sudo systemctl restart iotedge
Se você vir erros (texto colorido prefixado com "[ERROR]") no status, examine os logs de daemon para obter informações detalhadas sobre erros.

sudo journalctl -u iotedge --no-pager --no-full
Para evitar avisos, configure 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 erro comuns.

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

No portal do Azure, navegue até sua máquina virtual. Copie o valor para nome DNS (FQDN da máquina) 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. Certifique-se de que o nome é todo minúsculo.
```
`hostname: "<machinename>.<region>.cloudapp.azure.com"`
```
Observação

Talvez seja necessário usar o nome da máquina nua 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 oferece suporte a netbios.
Reinicie o iotedge daemon.

sudo systemctl restart iotedge
Se você vir erros (texto colorido prefixado com "[ERROR]") no status, examine os logs de daemon para obter informações detalhadas sobre erros.

sudo journalctl -u iotedge --no-pager --no-full
Para evitar avisos, configure 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>"]
}
```

Passo 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 Azure Sphere que foi provisionado manualmente acima.
Selecione ID do dispositivo.
Selecione o ícone de engrenagem em Sem dispositivo pai.
Selecione o dispositivo Azure IoT Edge que você deseja definir como pai.
Selecione OK e, em seguida , Guardar.

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

Passo 6. Fornecer o certificado de CA do catálogo do dispositivo 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 CA do catálogo.

Faça o download do certificado de CA do catálogo, se ainda não o tiver feito. 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 suas credenciais de login do Azure:
```
az login
```
- Baixe o certificado da autoridade de certificação para seu catálogo do Azure Sphere. Este comando baixa um certificado válido 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.
```
az sphere ca-certificate download --resource-group MyResourceGroup --catalog MyCatalog --output-file CACertificate.cer
```
Converta o certificado CA do catálogo para o formato PEM. Exemplos de instruções para converter o formato em uma máquina Windows são os seguintes:
- Localize o caminho do certificado no 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 Certificados, selecione Avançar.
- Selecione o formato X.509 (CER) codificado em Base-64 e, em seguida, selecione Avançar.
- Introduza o nome do ficheiro para o certificado a exportar e, em seguida, selecione Seguinte.
- Selecione Concluir para terminar o assistente.
- Renomeie o arquivo de certificado baixado para ter a extensão de arquivo .pem.
Anexe o certificado de catálogo 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 Guia de 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 autoridade de certificação raiz será denominado azure-iot-test-only.root.ca.cert.pem.
- Abra o certificado de autoridade de certificação do catálogo 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 seu dispositivo Azure IoT Edge. Para um dispositivo Linux Azure IoT Edge, execute: sudo iotedge list.

Passo 7. Fornecer o certificado de autoridade de certificação raiz do dispositivo Azure IoT Edge para o dispositivo 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 CA 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 original do Azure IoT Edge.
- Lembre-se de que o certificado raiz do dispositivo original do Azure IoT Edge é o que você criou na Etapa 2.
- Se você seguiu o Guia de início rápido e, em seguida, 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 é chamado azure-iot-test-only.root.ca.cert.pem.
Copie o certificado raiz do Azure IoT Edge para o dispositivo Azure Sphere adicionando-o ao pacote do aplicativo.
- Para obter etapas detalhadas, consulte Criação de pacotes de imagens.
- Consulte a seção para copiar certificados raiz para uma VM Linux ou para um computador Windows local.

Passo 8. Copie o certificado raiz da IoT para uma máquina remota

Siga estas etapas para copiar o certificado raiz do Azure IoT Edge para uma VM Linux remota ou para uma máquina 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 uma máquina 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 Linux remota 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 para executar o Azure IoT Edge em seu ambiente, use estes artigos para solução de problemas e diagnóstico:

Próximos passos

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