Definições de hardware

Artigo
08/09/2023

Esta seção descreve 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 duas finalidades separadas, mas relacionadas:

Definições específicas do quadro definem os periféricos específicos de um módulo ou outra placa e permitem que um aplicativo as referencie 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 tais definições para placas comuns do Azure Sphere e os chips que eles usam. Esse diretório está %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions no Windows e /opt/azurespheresdk/HardwareDefinitions no Linux.

Definições específicas do aplicativo mapeiam periféricos referenciados no código do aplicativo para definições específicas do quadro. As definições específicas do aplicativo são criadas em definições específicas do quadro e definem um único conjunto de identificadores que podem ser usados para referenciar periféricos em qualquer quadro. Assim, um aplicativo executado em vários quadros 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 do indicador BrewingStatus. O conselho de controle da cafeteira é criado 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 LED 2 no quadro de controle fornecido pela Contoso e led 4 no quadro de controle fornecido pela Fabrikam.

Se o aplicativo usar definições de hardware do SDK ou do fornecedor de hardware e você não estiver criando sua própria definição específica do aplicativo, você poderá ignorar o restante deste tópico por enquanto e ir direto para usar 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 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 quadro 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 de 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 que esse quadro expõe 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>"}

Veja a seguir os elementos da seção Periféricos :

Nome – o identificador usado para fazer referência ao periférico no código do 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 informações de 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 para aparecer no arquivo de cabeçalho gerado. Por exemplo, fixar atribuições para periféricos ISU* ou mapear LEDs a bordo para pinos GPIO da MCU ou módulo subjacentes.

Exemplo: definição específica do quadro

O exemplo a seguir mostra uma parte do arquivo de definição de hardware que contém uma definição específica do quadro para um quadro de desenvolvimento mt3620 fictício chamado MyBoard. Ele especifica as definições de pinout periférico para MyBoard. Ele importa definições de recurso 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 pin-to-pin dos recursos expostos pelo MyBoard aos 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 do quadro 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 uma cafeteira fictícia dispositivo.

Entre os periféricos incluídos no aplicativo estão dois LEDs de indicador e um botão push. 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 do quadro importado para o quadro fictício MT3620 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 Importações contém o caminho para o arquivo de definição de hardware para o quadro físico ou módulo.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
A seção Periféricos mapeia os periféricos do quadro de controle 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 para uma placa ou módulo.

A próxima versão da cafeteira pode ser criada no MyBoardV2. Ele teria uma nova definição específica do quadro 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 este novo LED laranja. O código do aplicativo de cafeteira real permaneceria inalterado.

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

Arquivos de cabeçalho

Os arquivos de cabeçalho são gerados dos arquivos JSON que contêm as definições de hardware. Você deve criar arquivos de cabeçalho para definições específicas do quadro 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 linha a seguir no Prompt de Comando do Azure Sphere. Substitua <filename> pelo nome do arquivo JSON.

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

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 do arquivo JSON.

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

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
                   .
                   .
                   .

Nota 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 esse subdiretório não existir, ele será criado.

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