Definições de hardware

Artigo
09/27/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).

Esta seção descreve os arquivos de definição de hardware e como criá-los para placas e módulos do Azure Sphere.

Arquivos de definição de hardware

As definições de hardware servem a dois propósitos separados, mas relacionados:

As definições específicas da placa definem os periféricos específicos de um módulo ou outra placa e permitem que um aplicativo faça referência a eles usando identificadores relevantes e significativos. Por exemplo, um aplicativo pode usar "Red_LED_1" em vez de um número opaco, como GPIO "13". O diretório HardwareDefinitions no SDK do Azure Sphere contém essas definições para placas comuns do Azure Sphere e os chips que elas usam. Este diretório está %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions no Windows e /opt/azurespheresdk/HardwareDefinitions no Linux.

As definições específicas do aplicativo mapeiam periféricos que são referenciados no código do aplicativo para definições específicas da placa. As definições específicas do aplicativo são criadas em definições específicas da placa e definem um único conjunto de identificadores que podem ser usados para fazer referência a periféricos em qualquer placa. Assim, um aplicativo executado em várias placas pode ter uma definição específica do aplicativo para cada tipo de placa, mas o próprio aplicativo usa apenas um conjunto de identificadores periféricos. O código em si pode ser executado totalmente inalterado em hardware diferente; Um desenvolvedor só precisa alterar a referência para usar a definição apropriada. Por exemplo, o código do aplicativo para uma cafeteira faz referência a um LED indicador BrewingStatus. O painel de controle da cafeteira é fornecido por dois fornecedores, Contoso e Fabrikam. Por meio do uso de definições específicas do aplicativo para cada placa, o indicador BrewingStatus pode ser mapeado para o LED 2 na placa de controle fornecida pela Contoso e para o LED 4 na placa de controle fornecida pela Fabrikam.

Se o aplicativo usa definições de hardware do SDK ou do fornecedor de hardware — e você não está criando sua própria definição específica do aplicativo — você pode ignorar o restante deste tópico por enquanto e ir direto para o uso de dependências de hardware.

Você cria seus arquivos de definição de hardware no formato JSON. Em seguida, você gera arquivos de cabeçalho C a partir dos arquivos JSON.

Formato de um arquivo de definição de hardware

Um arquivo de definição de hardware é um arquivo JSON com o seguinte formato:

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "<name of board or module>",
        "MainCoreHeaderFileTopContent": [
            "/* Copyright (c) <vendor name> All rights reserved.",
            "   <vendor licensing information, if any> */",
            "",
            "// This header contains the peripheral pinout definitions for the",
            "// <name of board or module>"
        ]
    },
    "Imports" : [ {"Path": "<path to underlying hardware definition file>"} ],
    "Peripherals": [
       {"Name": "", "Type": " ", "Mapping": " ", "Comment": " "},
   ]
}

A seção Metadados contém informações sobre o arquivo (tipo de arquivo, versão e assim por diante).

A seção Descrição contém informações sobre o painel ou módulo. O campo "MainCoreHeaderFileTopContent" contém informações que serão colocadas no início do arquivo de cabeçalho gerado.

A seção Importações especifica o nome do caminho do arquivo de definição de hardware para a plataforma de hardware subjacente (placa ou módulo).

A seção Periféricos lista os periféricos expostos por esse painel para uso em aplicativos. Uma descrição periférica tem o seguinte formato:

{"   Name": "<name-in-code>", "Type": "<type>", "Mapping": "<name-in-imported-definition>", "Comment": "<helpful info>"}

A seguir estão os elementos da seção Periféricos :

Nome – O identificador usado para referenciar o periférico no código do seu aplicativo.

Tipo – O tipo de periférico (por exemplo, Gpio, Uart, Adc). Consulte o arquivo de definição de hardware listado na seção Importações para obter as informações sobre o tipo.

Mapeamento – Mapeia o identificador no campo Nome para o identificador usado para o periférico no arquivo de definição de hardware importado.

Comentários – Fornece informações úteis a serem exibidas no arquivo de cabeçalho gerado. Por exemplo, fixe atribuições para periféricos ISU* ou para mapear LEDs integrados para pinos GPIO do MCU ou Módulo subjacente.

Exemplo: definição específica do conselho

O exemplo a seguir mostra uma parte do arquivo de definição de hardware que contém uma definição específica da placa para uma placa de desenvolvimento MT3620 fictícia chamada MyBoard. Ele especifica as definições de pinagem periférica para MyBoard. Ele importa definições de recursos do arquivo de definição de hardware específico do chip (mt3620.json) para o MCU MT3620. As informações na seção Periféricos resultam em um mapeamento pino a pino dos recursos expostos pelo MyBoard para os recursos fornecidos pelo MCU MT3620 subjacente.

{
    "Metadata":
    {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "MyBoard",
        "MainCoreHeaderFileTopContent": [
            "// This header contains the peripheral pinout definitions for ",
            "// MyBoard"
        ]
    },
    "Imports" : [ {"Path": "... /mt3620/mt3620.json"} ],
    "Peripherals": [
        {"Name": "MY_BOARD_LED_RED", "Type": "Gpio", "Mapping": "MT3620_GPIO8", "Comment": "LED 1 Red channel uses GPIO8."},
        {"Name": "MY_BOARD_LED_GREEN", "Type": "Gpio", "Mapping": "MT3620_GPIO16", "Comment": "LED 2 Green channel uses GPIO16"},
        {"Name": "MY_BOARD_BUTTON_A", "Type": "Gpio", "Mapping": "MT3620_GPIO12", "Comment": "Button A uses GPIO12"},
                              .
                              .
                              .
    ]
}

Você pode ver exemplos adicionais de arquivos de definição específicos da placa no diretório HardwareDefinitions que faz parte da instalação do SDK do Azure Sphere.

Exemplo: definição específica do aplicativo

O exemplo a seguir mostra uma parte de um arquivo de definição de hardware que contém uma definição específica do aplicativo para um aparelho de cafeteira fictício.

Entre os periféricos incluídos no aplicativo estão dois LEDs indicadores e um botão de pressão. Eles são referenciados no código do aplicativo pelos identificadores COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY e COFFEEMAKER_BUTTON_START respectivamente. Esses identificadores são mapeados para periféricos definidos na definição específica da placa importada para a placa MT3620 fictícia MyBoard.

{
    "Metadata": {
        "Type": "Azure Sphere Hardware Definition",
        "Version": 1
    },
    "Description":
    {
        "Name": "Coffee Maker Application",
        "MainCoreHeaderFileTopContent": [
            "// This file implements the Coffee Maker application-specific definition on MyBoard",
        ]
    },
    "Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
    "Peripherals": [
         {"Name": "COFFEEMAKER_STATUS_BREWING", "Type": "Gpio", "Mapping": "MY_BOARD_LED_RED", "Comment": "Brewing status indicator uses MyBoard RED LED"},
         {"Name": "COFFEEMAKER_STATUS_READY", "Type": "Gpio", "Mapping": "MY_BOARD_LED_GREEN", "Comment": "Ready status indicator uses MyBoard GREEN LED"},
         {"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": "Start button uses MyBoard Button A"},
                                             .
                                             .
                                             .
    ]
}

A seção Imports contém o caminho para o arquivo de definição de hardware para a placa física ou módulo.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
A seção Periféricos mapeia os periféricos da placa de controle do CoffeeMaker para os periféricos correspondentes em uma placa ou módulo.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Nome - contém o identificador usado para o periférico no código do aplicativo.

Mapeamento - contém o identificador usado para o periférico no arquivo de definição de hardware de uma placa ou módulo.

A próxima versão da cafeteira pode ser construída no MyBoardV2. Ele teria uma nova definição específica da placa com periféricos como MY_BOARD_V2_LED_ORANGE. Isso seria importado por uma nova implementação da definição específica do aplicativo da cafeteira que mapeia COFFEEMAKER_STATUS_BREWING para esse novo LED laranja. O código real do aplicativo da cafeteira permaneceria inalterado.

Da mesma forma, uma nova implementação da definição "sample_appliance.json", usada pelos aplicativos de exemplo do Azure Sphere, pode permitir que esses aplicativos de exemplo sejam executados inalterados no MyBoard.

Arquivos de cabeçalho

Os arquivos de cabeçalho são gerados a partir dos arquivos JSON que contêm as definições de hardware. Você deve criar arquivos de cabeçalho para definições específicas da placa e específicas do aplicativo.

Use o comando azsphere hardware-definition generate-header para gerar um arquivo de cabeçalho.

Para criar o arquivo de cabeçalho, insira a seguinte linha no Prompt de Comando do Azure Sphere. Substitua <filename> pelo nome do arquivo JSON.

Azure Sphere CLI
CLI clássica do Azure Sphere

azsphere hardware-definition generate-header --hardware-definition-file <filename>

azsphere hardware-definition generate-header --input <filename>

Observação

A CLI clássica do Azure Sphere está sendo desativada. Recomendamos usar o Azure Sphere (Integrado).

O arquivo de cabeçalho filename.h será criado e colocado na pasta inc/hw.

Por exemplo, insira a linha a seguir para gerar um arquivo de cabeçalho a partir do arquivo JSON.

Azure Sphere CLI
CLI clássica do Azure Sphere

azsphere hardware-definition generate-header --hardware-definition-file my_board.json

azsphere hardware-definition generate-header --input my_board.json

Observação

A CLI clássica do Azure Sphere está sendo desativada. Recomendamos usar o Azure Sphere (Integrado).

O seguinte mostra uma parte do arquivo de cabeçalho my_board.h:

#pragma once
#include "... /mt3620/inc/hw/mt3620.h"

// LED Red channel uses GPIO8.
#define MY_BOARD_LED_RED MT3620_GPIO8

// LED Green channel uses GPIO16
#define MY_BOARD_LED_GREEN MT3620_GPIO16

// Button A uses GPIO12
#define MY_BOARD_BUTTON_A MT3620_GPIO12
                   .
                   .
                   .

Observação Por padrão, o arquivo de cabeçalho gerado será colocado em inc/hw, que deve ser um subdiretório do diretório que contém o arquivo JSON de entrada. Se este subdiretório não existir, ele será criado.

Agora que você criou o arquivo JSON de definição de hardware e o arquivo de cabeçalho que o acompanha, consulte Gerenciar dependências de hardware de destino para obter as etapas para usá-lo em seu aplicativo.

Compartilhar via