Definiciones de hardware

Artículo
08/09/2023

En esta sección se describen los archivos de definición de hardware y cómo crearlos para los módulos y paneles Azure Sphere.

Archivos de definición de hardware

Las definiciones de hardware sirven para dos fines independientes pero relacionados:

Las definiciones específicas del panel definen los periféricos específicos de un módulo u otro panel y permiten a una aplicación hacer referencia a ellos mediante identificadores relevantes y significativos. Por ejemplo, una aplicación puede usar "Red_LED_1" en lugar de un número opaco como GPIO "13". El directorio HardwareDefinitions del SDK de Azure Sphere contiene estas definiciones para los paneles comunes de Azure Sphere y los chips que usan. Este directorio está %ProgramFiles(x86)%\Microsoft Azure Sphere SDK\HardwareDefinitions en Windows y /opt/azurespheresdk/HardwareDefinitions en Linux.

Las definiciones específicas de aplicaciones asignan periféricos a los que se hace referencia en el código de aplicación a definiciones específicas del panel. Las definiciones específicas de la aplicación se crean en definiciones específicas de las placas y definen un único conjunto de identificadores que se pueden usar para hacer referencia a periféricos en cualquier placa. Por lo tanto, una aplicación que se ejecuta en varios paneles podría tener una definición específica de la aplicación para cada tipo de placa, pero la propia aplicación usa solo un conjunto de identificadores periféricos. El código en sí puede ejecutarse sin cambios en otro hardware; un desarrollador solo necesita cambiar la referencia para usar la definición adecuada. Por ejemplo, el código de aplicación de una cafetera hace referencia a un LED indicador BrewingStatus. La placa de control de la cafetera la suministran dos proveedores: Contoso y Fabrikam. Mediante el uso de definiciones específicas de la aplicación para cada panel, el indicador BrewingStatus se puede asignar a LED 2 en el panel de control suministrado por Contoso y LED 4 en el panel de control proporcionado por Fabrikam.

Si la aplicación usa definiciones de hardware del SDK o del proveedor de hardware y no está creando su propia definición específica de la aplicación, puede omitir el resto de este tema por ahora e ir directamente al uso de dependencias de hardware.

Los archivos de definición de hardware se crean en formato JSON. A continuación, genera archivos de encabezado C a partir de los archivos JSON.

Formato de un archivo de definición de hardware

Un archivo de definición de hardware es un archivo JSON con el siguiente 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": " "},
   ]
}

La sección Metadatos contiene información sobre el archivo (tipo de archivo, versión, etc.).

La sección Descripción contiene información sobre la placa o el módulo. El campo "MainCoreHeaderFileTopContent" contiene información que se colocará al principio del archivo de encabezado generado.

La sección Importaciones especifica el nombre de ruta del archivo de definición de hardware para la plataforma de hardware subyacente (placa o módulo).

La sección Periféricos enumera los periféricos que esta placa expone para su uso en aplicaciones. Una descripción de periférico tiene el siguiente formato:

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

Estos son los elementos de la sección Periféricos :

Name: identificador que se usa para hacer referencia al periférico en el código de aplicación.

Tipo: el tipo de periférico (por ejemplo, Gpio, Uart, Adc). Consulte el archivo de definición de hardware que se muestra en la sección Importaciones para obtener información de tipo.

Asignación: asigna el identificador en el campo Nombre al identificador usado para el periférico en el archivo de definición de hardware importado.

Comentarios: proporciona información útil para que aparezca en el archivo de encabezado generado. Por ejemplo, ancla asignaciones para periféricos ISU* o asigna ledes integrados a pin de GPIO del MCU o módulo subyacente.

Ejemplo: definición específica del panel

En el ejemplo siguiente se muestra una parte del archivo de definición de hardware que contiene una definición específica del panel para un panel de desarrollo ficticio mt3620 llamado Miboard. Especifica las definiciones de pinout periférico para MyBoard. Importa definiciones de recursos desde el archivo de definición de hardware específico de chip (mt3620.json) para el MCU MT3620. La información de la sección Periféricos da como resultado una asignación anclada de los recursos expuestos por MyBoard a los recursos proporcionados por el MCU MT3620 subyacente.

{
    "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"},
                              .
                              .
                              .
    ]
}

Puede ver ejemplos adicionales de archivos de definición específicos del panel en el directorio HardwareDefinitions que forma parte de la instalación del SDK de Azure Sphere.

Ejemplo: definición específica de la aplicación

En el ejemplo siguiente se muestra una parte de un archivo de definición de hardware que contiene una definición específica de la aplicación para un aparato ficticio de cafetera.

Entre los periféricos incluidos en la aplicación hay dos LED indicadores y un pulsador. Se hace referencia a ellos en el código de aplicación mediante los identificadores COFFEEMAKER_STATUS_BREWING, COFFEEMAKER_STATUS_READY y COFFEEMAKER_BUTTON_START, respectivamente. Estos identificadores se asignan a periféricos definidos en la definición específica del panel importado para la placa ficticia MT3620 board 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"},
                                             .
                                             .
                                             .
    ]
}

La sección Importaciones contiene la ruta de acceso al archivo de definición de hardware para la placa física o módulo.
```
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],
```
La sección Periféricos asigna los periféricos de la placa de control de CoffeeMaker a los periféricos correspondientes de una placa o módulo.
```
{"Name": "COFFEEMAKER_BUTTON_START", "Type": "Gpio", "Mapping": "MY_BOARD_BUTTON_A", "Comment": " Start button uses MyBoard Button A"},
```
Name: contiene el identificador que se usa para el periférico en el código de la aplicación.

Asignación: contiene el identificador usado para el periférico en el archivo de definición de hardware para una placa o módulo.

La siguiente versión de la cafetera podría estar integrada en MyBoardV2. Tendría una nueva definición específica de la placa con periféricos como MY_BOARD_V2_LED_ORANGE. Esto se importaría mediante una nueva implementación de la definición específica de la aplicación de la cafetera que asigna COFFEEMAKER_STATUS_BREWING a este nuevo LED naranja. El código de aplicación de cafetera real no se modificaría.

De forma similar, una nueva implementación de la definición "sample_appliance.json", usada por las aplicaciones de ejemplo de Azure Sphere, podría permitir que estas aplicaciones de muestra se ejecutara sin cambios en MyBoard.

Archivos de encabezado

Los archivos de encabezado se generan a partir de los archivos JSON que contienen las definiciones de hardware. Debe crear archivos de encabezado para definiciones específicas del panel y específicas de aplicaciones.

Utilice el comando azsphere hardware-definition generate-header para generar un archivo de encabezado.

Para crear el archivo de encabezado, escriba la línea siguiente en el símbolo del sistema de Azure Sphere. Reemplazar <filename> por el nombre del archivo JSON.

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

Se creará el archivo de encabezado filename.h y se colocará en la carpeta inc/hw.

Por ejemplo, escriba la línea siguiente para generar un archivo de encabezado a partir del archivo JSON.

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

A continuación se muestra una parte del archivo de encabezado 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 De forma predeterminada, el archivo de encabezado generado se colocará en inc/hw, que debe ser un subdirectorio del directorio que contiene el archivo JSON de entrada. Si este subdirectorio no existe, se creará.

Ahora que ha creado el archivo JSON de definición de hardware y el archivo de encabezado correspondiente, consulte Administrar dependencias de hardware de destino para conocer los pasos para usarlo en la aplicación.