Манифест приложения

  • Статья

Манифест приложения описывает ресурсы, также называемые возможностями приложения, которые требуются приложению. Каждое приложение имеет манифест приложения.

Приложения должны согласиться на использование возможностей, перечислив каждый необходимый ресурс в разделе Возможности манифеста приложения; По умолчанию возможности не включены. Если приложение запрашивает возможность, не указанную в списке, запрос завершается ошибкой. Если файл манифеста приложения содержит ошибки, попытка загрузить неопубликованное приложение завершается ошибкой. Манифест каждого приложения должен храниться как app_manifest.json в корневом каталоге папки приложения на компьютере.

Шаблон Azure Sphere автоматически создает манифест приложения по умолчанию при создании приложения. Необходимо изменить манифест по умолчанию, чтобы получить список возможностей, необходимых приложению. Каждый пример Azure Sphere также включает манифест приложения. Если вы используете пример приложения, вероятно, также потребуется изменить манифест.

Различные устройства Azure Sphere могут предоставлять функции микросхемы по-разному. В результате значение, используемое в манифесте для идентификации конкретной функции, например пин-кода GPIO, может отличаться в зависимости от оборудования, для чего вы разрабатываете. Управление зависимостями целевого оборудования предоставляет дополнительные сведения о целевых объектах оборудования для высокоуровневого приложения. В манифесте приложения высокого уровня используйте константы, определенные в JSON-файле в папке HardwareDefinitions каталога установки пакета SDK Microsoft Azure Sphere. Точное расположение каталога установки в Windows и Linux будет отличаться. В приложении с поддержкой реального времени (RTApp) используйте необработанные значения, перечисленные в разделе Содержимое манифеста приложения.

Когда какое-либо приложение загружается или развертывается на устройстве, среда выполнения Azure Sphere считывает манифест приложения, чтобы определить, какие возможности приложение может использовать. Попытки получить доступ к ресурсам, которые не перечислены в манифесте, приводят к ошибкам API, таким как EPERM (отказано в разрешении). Только одно приложение на устройстве может использовать ресурс. Если установить приложение, запрашивающее уже используемый ресурс, попытка завершится ошибкой.

Содержимое манифеста приложения

Манифест приложения включает следующие элементы:

Имя Описание
SchemaVersion Используемая версия схемы манифеста приложения. В настоящее время значение должно иметь значение 1. Обязательно.
Имя Имя приложения. При создании проекта для этого значения задается имя проекта. Имя может быть любой длины, но в пакете изображения хранятся только первые 31 символ; таким образом, имя будет усечено в запросах по пакету изображений. Обязательно.
ComponentId Идентификатор компонента. Visual Studio создает этот идентификатор при сборке приложения. Если вы не используете Visual Studio, сведения о создании идентификатора см. в разделе Создание идентификатора компонента . Обязательно.
Entrypoint Имя исполняемого файла вместе с относительным путем в образе файловой системы приложения, который создается при сборке приложения. В настоящее время Visual Studio использует /bin/app для этого значения. Обязательно.
CmdArgs Аргументы для передачи приложению при запуске. Заключите каждый аргумент в двойные кавычки и разделите аргументы запятой. Дополнительные.
TargetBetaApis Указывает, что приложению требуются API бета-версии, и определяет набор используемых бета-интерфейсов API. Это поле автоматически добавляется в процессе сборки, если приложение создается с помощью бета-интерфейсов API. Дополнительные. Дополнительные сведения см. в статье Использование бета-версии функций .
ApplicationType Тип приложения. Дополнительные. Установите значение Отладчик, только если вы создаете замену для gdbserver.
Возможности Список пар "ключ-значение", определяющих требования к ресурсам приложения. Обязательно.
MallocVersion Целое число, указывающее версию malloc, где 1=standard и 2=mallocng— расширенный malloc, доступный в версиях MUSL больше 1.2.1. Версия 2 рекомендуется использовать для разработки всех новых приложений.

Раздел "Возможности " поддерживает следующее:

Примечание

Высокоуровневые приложения могут использовать значения возможностей из файлов определения оборудования или необработанные значения. Однако вы не можете смешивать оба типа значений в одной возможности. ПРИЛОЖЕНИЯ RTApp могут использовать только необработанные значения для возможностей.

Имя Описание
Adc Контроллер аналогово-цифрового преобразования (ADC), используемый приложением. Эта возможность позволяет зарезервировать весь контроллер ADC (который состоит из 8-контактного блока), а не только закрепить 0 в блоке.
В высокоуровневом приложении укажите имя периферийного устройства, объявленное в файле заголовка определения оборудования.
В RTApp укажите Значение AppManifestValue, объявленное в JSON-файле определения оборудования.
Пример определения оборудования:"Adc": [ "$MT3620_RDB_ADC_CONTROLLER0" ]
Пример необработанного значения:"Adc": [ "ADC-CONTROLLER-0" ]
Справочник по API:Applibs adc.h
Основные понятия:использование ADC в Azure Sphere
AllowedApplicationConnections Список идентификаторов компонентов приложения, к которым приложение может подключаться.
Примере:"AllowedApplicationConnections": [ "005180BC-402F-4CB3-A662-72937DBCDE47" ]
Справочник по API:Applibs application.h
Концепция:взаимодействие с приложением высокого уровня
AllowedConnections Список имен узлов DNS или IP-адресов (IPv4), к которым приложение может подключаться. Если приложение использует Центр Интернета вещей Azure, список должен содержать IP-адрес или DNS-имя узла концентратора, обычно hub-name.azure-devices.net. Номера портов и подстановочные знаки в именах и IP-адресах не принимаются.
Примере:"AllowedConnections" : [ "my-hub.example.net", "global.azure-devices-provisioning.net" ]
AllowedTcpServerPorts Список портов, разрешающих входящий трафик TCP. Можно включить до 10 портов, каждый из которых должен быть указан отдельно. Поддерживаемые порты— от 1024 до 65535. Вы можете указать одни и те же порты для TCP и UDP. Однако если указать один и тот же порт для нескольких приложений на устройстве, второе запущенное приложение не загрузится.
Примере:"AllowedTcpServerPorts": [ 1024, 65535 ]
AllowedUdpServerPorts Список портов, разрешающих входящий трафик UDP. Можно включить до 10 портов, каждый из которых должен быть указан отдельно. Поддерживаемые порты— от 1024 до 65535. Вы можете указать одни и те же порты для TCP и UDP. Однако если указать один и тот же порт для нескольких приложений на устройстве, второе запущенное приложение не загрузится.
Примере:"AllowedUdpServerPorts": [ 1024, 50000 ]
CertStore Логическое значение, указывающее, имеет ли высокоуровневое приложение разрешение на управление сертификатами с помощью API CertStore: true, чтобы включить API; в противном случае — значение false.
Примере:"CertStore" : true
DeviceAuthentication Строка, указывающая UUID клиента Azure Sphere, который будет использоваться для проверки подлинности устройства.
Примере:"DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0"
DhcpService Логическое значение, указывающее, имеет ли приложение разрешение на настройку службы DHCP: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"DhcpService" : true
Справочник по API:Applibs networking.h
Основные понятия:использование сетевых служб
EnterpriseWifiConfig Логическое значение, указывающее, имеет ли приложение высокого уровня разрешение на создание сети EAP-TLS и связывание с ней сертификатов: true, если приложение имеет такую возможность; в противном случае — значение false.
Примере:"EnterpriseWifiConfig" : true
ExternalInterrupt Список внешних прерываний, которые использует RTApp. Эта возможность недоступна для высокоуровневых приложений.
Примере:"ExternalInterrupt": [ "EINT4", "EINT12" ]
Gpio Список объектов GPIOs, которые использует приложение.
В высокоуровневом приложении укажите имя GPIO, объявленное в файле заголовка определения оборудования, например $MT 3620_RDB_LED1_RED.
В RTApp укажите целые числа, соответствующие номерам GPIO в JSON-файле определения оборудования. Например, 8 указывает GPIO 8.
Пример определения оборудования:"Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ]
Пример необработанного значения:"Gpio": [ 8, 12 ]
Справочник по API:Applibs gpio.h
Основные понятия:использование GPIOS в Azure Sphere
HardwareAddressConfig Логическое значение, указывающее, имеет ли приложение разрешение на настройку аппаратного адреса сетевого интерфейса: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"HardwareAddressConfig" : true
Справочник по API:Applibs networking.h
Основные понятия:использование сетевых служб
HeapMemStats Логическое значение, указывающее, включено ли отслеживание выделения памяти кучи: true, если приложение имеет такую возможность; в противном случае — значение false.
Примере:"HeapMemStats": true
Концепция:использование памяти в высокоуровневых приложениях
I2cMaster Список интерфейсов I2C master, используемых приложением.
В высокоуровневом приложении укажите имя периферийного устройства, объявленное в файле заголовка определения оборудования.
В RTApp укажите Значение AppManifestValue , объявленное в JSON-файле определения оборудования.
Пример определения оборудования:"I2cMaster": [ "$MT3620_RDB_HEADER2_ISU0_I2C", "$MT3620_RDB_HEADER4_ISU1_I2C" ]
Пример необработанного значения:"I2cMaster": [ "ISU0", "ISU1" ]
Справочник по API:Applibs i2c.h
Основные понятия:использование I2C с Azure Sphere
I2sSubordinate Подчиненный интерфейс inter-IC Sound (I2S), используемый RTApp. Эта возможность недоступна для высокоуровневых приложений. Пример необработанного значения: "I2sSubordinate": [ "I2S0", "I2S1" ]
MutableStorage Параметры изменяемого хранилища, позволяющие приложению использовать постоянное хранилище.
Примере:"MutableStorage" : { "SizeKB": 64, }
Справочник по API:Applibs storage.h
Основные понятия:использование хранилища в Azure Sphere
NetworkConfig Логическое значение, указывающее, имеет ли приложение разрешение на настройку сетевого интерфейса: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"NetworkConfig" : true
Справочник по API:Applibs networking.h
Основные понятия:использование сетевых служб
PowerControls Массив строк, представляющих детализированные возможности для управления состоянием питания устройства. Только поддерживаемые значения — ForcePowerDown и ForceReboot.
Предупреждение: Так как ForcePowerDown и ForceReboot позволяют приложению немедленно завершить работу всех приложений, необходимо убедиться, что устройство по-прежнему может получать обновления операционной системы и приложений. Дополнительные сведения и рекомендации см. в разделе Принудительное выключение питания и обновления.
Примере:"PowerControls": ["ForcePowerDown", "ForceReboot"]
Справочник по API:Applibs powermanagement.h
Основные понятия:управление состоянием выключения питания для устройств Azure Sphere
Шим Импульсно-ширинный модулятор (PWM), используемый приложением.
В высокоуровневом приложении укажите имя периферийного устройства, объявленное в файле заголовка определения оборудования.
В RTApp укажите Значение AppManifestValue , объявленное в JSON-файле определения оборудования.
Пример определения оборудования:"Pwm": [ "$MT3620_RDB_LED_PWM_CONTROLLER2" ]
Пример необработанного значения:"Pwm": [ "PWM-CONTROLLER-0" ]
Справочник по API:Applibs pwm.h
Концепция: использование ШИМ в высокоуровневых приложениях
ReadNetworkProxyConfig Логическое значение, указывающее, имеет ли приложение разрешение на получение конфигурации прокси-сервера: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"ReadNetworkProxyConfig": true
Справочник по API:Applibs networking.h
Концепция:подключение к веб-службам
SntpService Логическое значение, указывающее, имеет ли приложение разрешение на настройку службы SNTP: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"SntpService" : true
Справочник по API:Applibs networking.h
Концептуальный:сервер SNTP
SoftwareUpdateDeferral Логическое значение, указывающее, имеет ли приложение разрешение на отсрочку обновлений программного обеспечения на ограниченный период: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"SoftwareUpdateDeferral" : true
Справочник по API:Applibs eventloop.H
Концептуальный:отложить обновления устройств
SpiMaster Список интерфейсов SPI master, используемых приложением.
В высокоуровневом приложении укажите имя периферийного устройства, объявленное в файле заголовка определения оборудования.
В RTApp укажите Значение AppManifestValue , объявленное в JSON-файле определения оборудования.
Пример определения оборудования:"SpiMaster": [ "$MT3620_RDB_HEADER2_ISU0_SPI", "$MT3620_RDB_HEADER4_ISU1_SPI" ]
Пример необработанного значения:"SpiMaster": [ "ISU0", "ISU1" ]
Справочник по API:Applibs spi.h
Основные понятия:использование SPI с Azure Sphere
SystemEventNotifications Логическое значение, указывающее, имеет ли приложение разрешение на получение уведомлений о системных событиях: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"SystemEventNotifications" : true
Справочник по API:Applibs sysevent.h
Концептуальный:отложить обновления устройств
Systemtime Логическое значение, указывающее, имеет ли приложение разрешение на настройку системного времени: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"SystemTime" : true
Справочник по API:Applibs rtc.h
Основные понятия:управление системным временем и RTC в Azure Sphere
TimeSyncConfig Логическое значение, указывающее, имеет ли приложение разрешение на настройку службы синхронизации времени: true, если у приложения есть возможность; в противном случае — значение false.
Примере:"TimeSyncConfig" : true
Uart Список периферийных устройств UART, которые использует приложение. Эта возможность не включает выделенный UART на плате разработки MT3620. Сведения о выделенном UART см. в статье Создание приложения с поддержкой реального времени.
В высокоуровневом приложении укажите имя периферийного устройства, объявленное в файле заголовка определения оборудования.
В RTApp укажите Значение AppManifestValue , объявленное в JSON-файле определения оборудования.
Пример определения оборудования:"Uart": [ "$MT3620_RDB_HEADER2_ISU0_UART", "$MT3620_RDB_HEADER4_ISU1_UART" ]
Пример необработанного значения:"Uart": [ "ISU0", "ISU1" ]
Справочник по API:Applibs uart.h
Основные понятия:использование UART в Azure Sphere
WifiConfig Логическое значение, указывающее, имеет ли приложение разрешение на использование API WifiConfig для изменения конфигурации Wi-Fi: true, если приложение имеет такую возможность; в противном случае — значение false.
Примере:"WifiConfig" : true
Справочник по API:Applibs wificonfig.h
Основные понятия:настройка сети

Раздел MutableStorage поддерживает следующее:

Имя Описание
SizeKB Целое число, указывающее размер изменяемого хранилища в кибибайтах. Максимальное значение — 64. Значение 0 эквивалентно тому, что у него нет возможности изменяемого хранилища.

Примере

Ниже показан пример файла app_manifest.json для высокоуровневого приложения, предназначенного для оборудования MT3620 RDB:

{
    "SchemaVersion": 1,
    "Name": "MyTestApp",
    "ComponentId": "072c9364-61d4-4303-86e0-b0f883c7ada2",
    "EntryPoint": "/bin/app",
    "CmdArgs": ["-m", "262144", "-t", "1"],
    "Capabilities": {
        "AllowedConnections" : [
            "my-hub.example.net",
            "contoso.azure-devices.net",
            "global.azure-devices-provisioning.net" ],
        "AllowedTcpServerPorts": [ 1024, 65535 ],
        "AllowedUdpServerPorts": [ 1024, 50000 ],
        "DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0",
        "Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ],
        "HardwareAddressConfig": true,
        "I2cMaster": [ "ISU2" ],
        "MutableStorage" : {
            "SizeKB": 64,
        },
        "SpiMaster": [ "ISU1" ],
        "SystemTime" : true,
        "Uart": [ "ISU0" ],
        "WifiConfig" : true
    },
    "ApplicationType": "Default",
    "MallocVersion": 2
}

Пример файла app_manifest.json для MyTestApp выполняет следующие действия:

  • Передает в приложение четыре аргумента командной строки.
  • Разрешает подключения только к узлам DNS my-hub.example.net, contoso.azure-devices.net и global.azure-devices-provisioning.net.
  • Разрешает входящий трафик TCP на портах 1024 и 65535.
  • Разрешает входящий трафик UDP на портах 1024 и 50000.
  • Указывает клиент Azure Sphere для проверки подлинности устройства и разрешения подключений к службе подготовки устройств.
  • Указывает использование трех объектов GPIOS.
  • Позволяет приложению настроить аппаратный адрес сетевого интерфейса.
  • Указывает использование одного периферийного устройства UART.
  • Включает изменяемое хранилище с 64 кибибайтами дискового пространства.
  • Позволяет приложению использовать API WifiConfig для изменения конфигурации Wi-Fi.
  • Указывает использование одного интерфейса SPI master.
  • Указывает использование одного интерфейса I2C master.
  • Позволяет приложению настраивать системное время с помощью API RTC.
  • Включает mallocng для разработки приложений.