Definiciones del hardware
Importante
Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).
En esta sección se describen los archivos de definición de hardware y cómo crearlos para paneles y módulos de Azure Sphere.
Archivos de definición de hardware
Las definiciones de hardware sirven para dos propósitos independientes, pero relacionados:
Las definiciones específicas de la placa definen los periféricos específicos de un módulo u otra placa y permiten que una aplicación haga 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 la aplicación asignan periféricos a los que se hace referencia en el código de aplicación a definiciones específicas de la placa. Las definiciones específicas de la aplicación se basan en definiciones específicas de la placa y definen un único conjunto de identificadores que se pueden usar para hacer referencia a periféricos en cualquier panel. 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 propio código puede ejecutarse completamente sin cambios en hardware diferente; 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 cafetera es fuente de dos proveedores, Contoso y Fabrikam. Mediante el uso de definiciones específicas de la aplicación para cada placa, el indicador BrewingStatus se puede asignar al LED 2 en la placa de control proporcionada por Contoso y LED 4 en la placa de control proporcionada por Fabrikam.
Si la aplicación usa definiciones de hardware desde el SDK o desde el proveedor de hardware ,y no va a crear su propia definición específica de la aplicación, puede omitir el resto de este tema por ahora y ir directamente al uso de dependencias de hardware.
Cree los archivos de definición de hardware en formato JSON. A continuación, generará archivos de encabezado de 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 formato siguiente:
{
"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 Description 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 Imports especifica el nombre de ruta de acceso del archivo de definición de hardware para la plataforma de hardware subyacente (placa o módulo).
La sección Peripherals enumera los periféricos que esta placa expone para su uso en las 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>"}
A continuación se muestran los elementos de la sección Periféricos :
Name: identificador usado para hacer referencia al periférico en el código de la aplicación.
Type: tipo de periférico (por ejemplo, GPIO, UART, ADC). Consulte el archivo de definición de hardware que se muestra en la sección Imports para obtener información sobre los tipos.
Mapping: asigna el identificador del campo Name al identificador usado para el periférico en el archivo de definición de hardware importado.
Comments: proporciona información útil que aparecerá en el archivo de encabezado generado. Por ejemplo, anclar asignaciones para periféricos de ISU * o asignar los LED integrados en la placa a pins de GPIO del MCU o módulo subyacente.
Ejemplo: definición específica de la placa
En el ejemplo siguiente se muestra una parte del archivo de definición de hardware que contiene una definición específica de la placa para una placa de desarrollo FIcticia MT3620 denominada MyBoard. Especifica las definiciones de pinout periférico para MyBoard. Importa las definiciones de recursos del archivo de definición de hardware específico del chip (mt3620.json) para la MCU MT3620. La información de la sección Periféricos da como resultado una asignación de patillas de los recursos expuestos por MyBoard a los recursos proporcionados por la 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 de la placa 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 dispositivo ficticio de cafetera.
Entre los periféricos incluidos en la aplicación se encuentran dos LED de indicador y un botón de pulsación. Se hace referencia a ellos en el código de aplicación por 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 de la placa importada para la placa ficticia 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"},
.
.
.
]
}
La sección Imports contiene la ruta de acceso al archivo de definición de hardware para la placa física o el módulo.
"Imports" : [ {"Path": "... /MyHwDefs/my_board.json"} ],La sección Periféricos asigna los periféricos de la placa de control 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 usado 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 de un panel o módulo.
La siguiente versión de la cafetera podría basarse en MyBoardV2. Tendría una nueva definición específica de 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 real de la aplicación cafetera permanecerá sin cambios.
Del mismo modo, una nueva implementación de la definición de "sample_appliance.json", usada por las aplicaciones de ejemplo de Azure Sphere, podría permitir que estas aplicaciones de ejemplo se ejecuten 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 de la placa y específicas de la aplicación.
Para generar un archivo de encabezado, use el comando azsphere hardware-definition generate-header.
Para crear el archivo de encabezado, escriba la siguiente línea en el símbolo del sistema de Azure Sphere. Reemplace <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 siguiente línea 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 su archivo de encabezado complementario, consulte Administración de dependencias de hardware de destino para conocer los pasos para usarlos en la aplicación.