Definições de hardware

Artigo
08/09/2023

Esta secção descreve os ficheiros de definição de hardware e como criá-los para quadros e módulos do Azure Sphere.

Ficheiros de definição de hardware

As definições de hardware servem duas finalidades separadas, mas relacionadas:

As definições específicas do quadro definem os periféricos específicos de um módulo ou de outro quadro e permitem que uma aplicação os referencie através de identificadores relevantes e significativos. Por exemplo, uma aplicação pode utilizar "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 quadros comuns do Azure Sphere e os chips que utilizam. Este diretório está %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions no Windows e /opt/azurespheresdk/HardwareDefinitions no Linux.

As definições específicas da aplicação mapeiam periféricos que são referenciados no código da aplicação para definições específicas do quadro. As definições específicas da aplicação são criadas em definições específicas do quadro e definem um único conjunto de identificadores que podem ser utilizados para referenciar periféricos em qualquer quadro. Assim, uma aplicação que é executada em vários quadros pode ter uma definição específica da aplicação para cada tipo de quadro, mas a própria aplicação utiliza apenas um conjunto de identificadores periféricos. O código em si pode ser executado totalmente inalterado em hardware diferente; um programador só precisa de alterar a referência para utilizar a definição adequada. Por exemplo, o código da aplicação para uma máquina de café faz referência a um LED indicador BrewingStatus. O painel de controlo da máquina de café é fornecido por dois fornecedores, Contoso e Fabrikam. Através da utilização de definições específicas da aplicação para cada quadro, o indicador BrewingStatus pode ser mapeado para LED 2 no quadro de controlo fornecido pela Contoso e pelo LED 4 no quadro de controlo fornecido pela Fabrikam.

Se a sua aplicação utilizar definições de hardware do SDK ou do seu fornecedor de hardware e não estiver a criar a sua própria definição específica da aplicação, pode ignorar o resto deste tópico por enquanto e ir diretamente para a utilização de dependências de hardware.

Crie os seus ficheiros de definição de hardware no formato JSON. Em seguida, irá gerar ficheiros de cabeçalho C a partir dos ficheiros JSON.

Formato de um ficheiro de definição de hardware

Um ficheiro de definição de hardware é um ficheiro 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 secção Metadados contém informações sobre o ficheiro (tipo de ficheiro, versão, etc.).

A secçã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 ficheiro de cabeçalho gerado.

A secção Importações especifica o pathname do ficheiro de definição de hardware para a plataforma de hardware subjacente (quadro ou módulo).

A secção Periféricos lista os periféricos que este quadro expõe para utilização em aplicações. Uma descrição de periférico tem o seguinte formato:

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

Seguem-se os elementos da secção Periféricos :

Nome – o identificador utilizado para referenciar o periférico no código da aplicação.

Tipo – o tipo de periférico (por exemplo, Gpio, Uart, Adc). Veja o ficheiro de definição de hardware listado na secção Importações para obter informações sobre o tipo.

Mapeamento – mapeia o identificador no campo Nome para o identificador utilizado para o periférico no ficheiro de definição de hardware importado.

Comentários – fornece informações úteis para aparecer no ficheiro de cabeçalho gerado. Por exemplo, afixar atribuições para periféricos ISU* ou mapear LEDs a bordo para pinos GPIO do MCU ou Módulo subjacente.

Exemplo: definição específica do quadro

O exemplo seguinte mostra uma parte do ficheiro de definição de hardware que contém uma definição específica do quadro para um quadro de desenvolvimento fictício mt3620 chamado MyBoard. Especifica as definições de pinout periférico para MyBoard. Importa definições de recursos do ficheiro de definição de hardware específico do chip (mt3620.json) para o MCU mt3620. As informações na secção Periféricos resultam num mapeamento afixado 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"},
                              .
                              .
                              .
    ]
}

Pode ver exemplos adicionais de ficheiros 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 da aplicação

O exemplo seguinte mostra uma parte de um ficheiro de definição de hardware que contém uma definição específica da aplicação para uma aplicação de máquina de café fictícia.

Entre os periféricos incluídos na aplicação estão dois LEDs indicadores e um botão push. São referenciados no código da aplicação pelos identificadores COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY e COFFEEMAKER_BUTTON_START respetivamente. Estes identificadores são mapeados para periféricos definidos na definição específica do quadro importado para a placa fictícia 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 secção Importações contém o caminho para o ficheiro de definição de hardware para o quadro físico ou módulo.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
A secção Periféricos mapeia os periféricos da placa de controlo Do Café para os periféricos correspondentes num quadro ou módulo.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Name - contém o identificador utilizado para o periférico no código da aplicação.

Mapeamento - contém o identificador utilizado para o periférico no ficheiro de definição de hardware de um quadro ou módulo.

A próxima versão da máquina de café poderá ser criada no MyBoardV2. Teria uma nova definição específica do quadro com periféricos, como MY_BOARD_V2_LED_ORANGE. Isto seria importado por uma nova implementação da definição específica da aplicação da máquina de café que mapeia COFFEEMAKER_STATUS_BREWING para este novo LED laranja. O código da aplicação da máquina de café real permaneceria inalterado.

Da mesma forma, uma nova implementação da definição "sample_appliance.json", utilizada pelas aplicações de exemplo do Azure Sphere, poderia permitir que estas aplicações de exemplo funcionassem inalteradas no MyBoard.

Ficheiros de cabeçalho

Os ficheiros de cabeçalho são gerados a partir dos ficheiros JSON que contêm as definições de hardware. Tem de criar ficheiros de cabeçalho para definições específicas do quadro e específicas da aplicação.

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

Para criar o ficheiro de cabeçalho, introduza a seguinte linha na Linha de Comandos do Azure Sphere. Substitua <filename> pelo nome do ficheiro JSON.

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

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

Por exemplo, introduza a seguinte linha para gerar um ficheiro de cabeçalho a partir do ficheiro JSON.

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

O seguinte mostra uma parte do ficheiro 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 predefinição, o ficheiro de cabeçalho gerado será colocado em inc/hw, que tem de ser um subdiretório do diretório que contém o ficheiro JSON de entrada. Se este subdiretório não existir, será criado.

Agora que criou o ficheiro JSON de definição de hardware e o respetivo ficheiro de cabeçalho associado, veja Gerir dependências de hardware de destino para obter os passos para utilizá-lo na sua aplicação.

Partilhar via