Application manifest

आलेख
09/23/2024

Important

This is the Azure Sphere (Legacy) documentation. Azure Sphere (Legacy) is retiring on 27 September 2027, and users must migrate to Azure Sphere (Integrated) by this time. Use the Version selector located above the TOC to view the Azure Sphere (Integrated) documentation.

The application manifest describes the resources, also called application capabilities, that an application requires. Every application has an application manifest.

Applications must opt in to use capabilities by listing each required resource in the Capabilities section of the application manifest; no capabilities are enabled by default. If an application requests a capability that is not listed, the request fails. If the application manifest file contains errors, attempts to sideload the application fail. Each application's manifest must be stored as app_manifest.json in the root directory of the application folder on your PC.

The Azure Sphere template automatically creates a default application manifest when you create an application. You must edit the default manifest to list the capabilities that your application requires. Each Azure Sphere sample also includes an application manifest. If you base your application on a sample, you will probably also need to edit the manifest.

Different Azure Sphere devices may expose features of the chip in different ways. As a result, the value you use in the manifest to identify a particular feature, such as a GPIO pin, may vary depending on the hardware you're developing for. Manage target hardware dependencies provides more information about hardware targets for a high-level application. In the application manifest for a high-level application, use the constants that are defined in the JSON file in the HardwareDefinitions folder of the Microsoft Azure Sphere SDK installation directory. The exact location of the installation directory will differ on Windows and Linux. In a real-time capable application (RTApp), use the raw values that are listed in Contents of the application manifest.

When any application is sideloaded or deployed to the device, the Azure Sphere runtime reads the application manifest to ascertain which capabilities the application is allowed to use. Attempts to access resources that are not listed in the manifest will result in API errors such as EPERM (permission denied). Only one application on the device can use a resource. If you install an application that requests a resource that is already in use, the attempt will fail.

Contents of the application manifest

The application manifest includes the following items:

Name	Description
SchemaVersion	Version of the application manifest schema in use. Currently must be 1. Required.
Name	Name of the application. At project creation, this value is set to the name of the project. The name can be any length, but only the first 31 characters are stored in the image package; thus the name appears truncated in inquiries about the image package. Required.
ComponentId	ID of the component. Visual Studio creates this ID when you build the application. If you do not use Visual Studio, see Generate a component ID for information on creating the ID. Required.
EntryPoint	Name of the executable together with the relative path in the application's file system image, which is created when the application is built. Visual Studio currently uses /bin/app for this value. Required.
CmdArgs	Arguments to pass to the application at startup. Enclose each argument in double quotation marks and separate arguments with a comma. Optional.
TargetBetaApis	Specifies that the application requires Beta APIs and identifies the set of Beta APIs used. This field is automatically added during the build process if the application is built using Beta APIs. Optional. See Use beta features for details.
ApplicationType	Type of application. Optional. Set to Debugger only if you are building a replacement for gdbserver.
Capabilities	List of key/value pairs that specify application resource requirements. Required.
MallocVersion	An integer that specifies the version of malloc, where 1=standard and 2=mallocng, an enhanced malloc available in MUSL versions greater than 1.2.1. Version 2 is recommended for all new app development.

The Capabilities section supports the following:

Note

High-level applications can use capability values from hardware definition files or they can use raw values. However, you can't mix both value types in the same capability. RTApps can use only raw values for capabilities.

Name	Description
Adc	The analog-to-digital conversion (ADC) controller that is used by the application. This capability reserves the entire ADC controller (which comprises an 8-pin block), not just pin 0 in the block. In a high-level application, specify the peripheral name that is declared in the hardware definition header file. In an RTApp, specify the AppManifestValue that is declared in the hardware definition JSON file. Hardware definition example: `"Adc": [ "$MT3620_RDB_ADC_CONTROLLER0" ]` Raw value example: `"Adc": [ "ADC-CONTROLLER-0" ]` API reference: Applibs adc.h Conceptual: Using ADCs on Azure Sphere
AllowedApplicationConnections	A list of application component IDs to which the application is allowed to connect. Example: `"AllowedApplicationConnections": [ "005180BC-402F-4CB3-A662-72937DBCDE47" ]` API reference: Applibs application.h Conceptual: Communicate with a high-level application
AllowedConnections	A list of DNS host names or IP addresses (IPv4) to which the application is allowed to connect. If the application uses an Azure IoT Hub, the list must include the IP address or DNS host name for the hub, typically hub-name.azure-devices.net. Port numbers and wildcard characters in names and IP addresses are not accepted. Example: `"AllowedConnections" : [ "my-hub.example.net", "global.azure-devices-provisioning.net" ]`
AllowedTcpServerPorts	A list of ports that allow incoming TCP traffic. You can include up to 10 ports, and each port must be listed individually. The supported ports are 1024 to 65535. You can specify the same ports for both TCP and UDP. However, if you specify the same port for more than one app on the device, the second app to run will fail to load. Example: `"AllowedTcpServerPorts": [ 1024, 65535 ]`
AllowedUdpServerPorts	A list of ports that allow incoming UDP traffic. You can include up to 10 ports, and each port must be listed individually. The supported ports are 1024 to 65535. You can specify the same ports for both TCP and UDP. However, if you specify the same port for more than one app on the device, the second app to run will fail to load. Example: `"AllowedUdpServerPorts": [ 1024, 50000 ]`
CertStore	A Boolean that indicates whether a high-level app has permission to manage certificates with the CertStore API: true to enable the API; otherwise, false. Example: `"CertStore" : true`
DeviceAuthentication	A string that specifies the UUID of the Azure Sphere tenant to use for device authentication. Example: `"DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0"`
DhcpService	A Boolean that indicates whether the application has permission to configure the DHCP service: true if the application has the capability; otherwise, false. Example: `"DhcpService" : true` API reference: Applibs networking.h Conceptual: Use network services
EnterpriseWifiConfig	A Boolean that indicates whether a high-level application has permission to create an EAP-TLS network and associate certificates with it: true if the application has the capability; otherwise, false. Example: `"EnterpriseWifiConfig" : true`
ExternalInterrupt	A list of external interrupts that an RTApp uses. This capability isn't available to high-level applications. Example: `"ExternalInterrupt": [ "EINT4", "EINT12" ]`
Gpio	A list of GPIOs the application uses. In a high-level application, specify the GPIO name that is declared in the hardware definition header file, such as $MT3620_RDB_LED1_RED. In an RTApp, specify the integers that correspond to the GPIO numbers in the hardware definition JSON file. For example, 8 specifies GPIO 8. Hardware definition example: `"Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ]` Raw value example: `"Gpio": [ 8, 12 ]` API reference: Applibs gpio.h Conceptual: Using GPIOs on Azure Sphere
HardwareAddressConfig	A Boolean that indicates whether the application has permission to configure the hardware address of the network interface: true if the application has the capability; otherwise, false. Example:`"HardwareAddressConfig" : true` API reference: Applibs networking.h Conceptual: Use network services
HeapMemStats	A Boolean that indicates whether heap memory allocation tracking is enabled: true if the application has the capability; otherwise, false. Example: `"HeapMemStats": true` Conceptual:Memory use in high-level applications
I2cMaster	A list of I2C master interfaces that are used by the application. In a high-level application, specify the peripheral name that is declared in the hardware definition header file. In an RTApp, specify the AppManifestValue that is declared in the hardware definition JSON file. Hardware definition example: `"I2cMaster": [ "$MT3620_RDB_HEADER2_ISU0_I2C", "$MT3620_RDB_HEADER4_ISU1_I2C" ]` Raw value example: `"I2cMaster": [ "ISU0", "ISU1" ]` API reference: Applibs i2c.h Conceptual: Using I2C with Azure Sphere
I2sSubordinate	The Inter-IC Sound (I2S) subordinate interface used by an RTApp. This capability isn't available to high-level applications. Raw value example: "I2sSubordinate": [ "I2S0", "I2S1" ]
MutableStorage	Mutable storage settings that allow the application to use persistent storage. Example: `"MutableStorage" : { "SizeKB": 64, }` API reference: Applibs storage.h Conceptual: Using storage on Azure Sphere
NetworkConfig	A Boolean that indicates whether the application has permission to configure a network interface: true if the application has the capability; otherwise, false. Example: `"NetworkConfig" : true` API reference: Applibs networking.h Conceptual: Use network services
PowerControls	An array of strings that represent granular capabilities to control the device power state. ForcePowerDown and ForceReboot are the only supported values. Warning: Because ForcePowerDown and ForceReboot allow an application to immediately terminate all applications, you must make sure your device is still able to receive operating system and application updates. For more information and guidance, see Force Power Down and updates. Example: `"PowerControls": ["ForcePowerDown", "ForceReboot"]` API reference: Applibs powermanagement.h Conceptual: Manage power-down state for Azure Sphere devices
Pwm	The pulse-width modulator (PWM) that is used by the application. In a high-level application, specify the peripheral name that is declared in the hardware definition header file. In an RTApp, specify the AppManifestValue that is declared in the hardware definition JSON file. Hardware definition example: `"Pwm": [ "$MT3620_RDB_LED_PWM_CONTROLLER2" ]` Raw value example: `"Pwm": [ "PWM-CONTROLLER-0" ]` API reference: Applibs pwm.h Conceptual: Use PWMs in high-level applications
ReadNetworkProxyConfig	A Boolean that indicates whether the application has permission to retrieve the proxy configuration: true if the application has the capability; otherwise, false. Example: `"ReadNetworkProxyConfig": true` API reference: Applibs networking.h Conceptual: Connect to web services
SntpService	A Boolean that indicates whether the application has permission to configure the SNTP service: true if the application has the capability; otherwise, false. Example: `"SntpService" : true` API reference: Applibs networking.h Conceptual: SNTP server
SoftwareUpdateDeferral	A Boolean that indicates whether the application has permission to defer software updates for a limited period: true if the application has the capability; otherwise, false. Example: `"SoftwareUpdateDeferral" : true` API reference: Applibs eventloop.h Conceptual: Defer device updates
SpiMaster	A list of SPI master interfaces that are used by the application. In a high-level application, specify the peripheral name that is declared in the hardware definition header file. In an RTApp, specify the AppManifestValue that is declared in the hardware definition JSON file. Hardware definition example: `"SpiMaster": [ "$MT3620_RDB_HEADER2_ISU0_SPI", "$MT3620_RDB_HEADER4_ISU1_SPI" ]` Raw value example: `"SpiMaster": [ "ISU0", "ISU1" ]` API reference: Applibs spi.h Conceptual: Using SPI with Azure Sphere
SystemEventNotifications	A Boolean that indicates whether the application has permission to receive system event notifications: true if the application has the capability; otherwise, false. Example: `"SystemEventNotifications" : true` API reference: Applibs sysevent.h Conceptual: Defer device updates
SystemTime	A Boolean that indicates whether the application has permission to configure the system time: true if the application has the capability; otherwise, false. Example: `"SystemTime" : true` API reference: Applibs rtc.h Conceptual: Manage system time and the RTC on Azure Sphere
TimeSyncConfig	A Boolean that indicates whether the application has permission to configure the time-sync service: true if the application has the capability; otherwise, false. Example: `"TimeSyncConfig" : true`
Uart	A list of UART peripherals that the application uses. This capability doesn't enable the dedicated UART on an MT3620 development board. For information about the dedicated UART, see Build a real-time capable application. In a high-level application, specify the peripheral name that is declared in the hardware definition header file. In an RTApp, specify the AppManifestValue that is declared in the hardware definition JSON file. Hardware definition example: `"Uart": [ "$MT3620_RDB_HEADER2_ISU0_UART", "$MT3620_RDB_HEADER4_ISU1_UART" ]` Raw value example: `"Uart": [ "ISU0", "ISU1" ]` API reference: Applibs uart.h Conceptual: Use UART on Azure Sphere
WifiConfig	A Boolean that indicates whether the application has permission to use the WifiConfig API to change the Wi-Fi configuration: true if the application has the capability; otherwise, false. Example: `"WifiConfig" : true` API reference: Applibs wificonfig.h Conceptual: Configure networking

The MutableStorage section supports the following:

Name	Description
SizeKB	An integer that specifies the size of mutable storage in kibibytes. The maximum value is 64. A value of 0 is equivalent to not having the mutable storage capability.

Example

The following shows a sample app_manifest.json file for a high-level application that targets the MT3620 RDB hardware:

{
    "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
}

The sample app_manifest.json file for MyTestApp does the following:

Passes four command-line arguments to the app.
Only allows connections to the DNS hosts my-hub.example.net, contoso.azure-devices.net, and global.azure-devices-provisioning.net.
Allows incoming TCP traffic on ports 1024 and 65535.
Allows incoming UDP traffic on ports 1024 and 50000.
Specifies an Azure Sphere tenant to use for device authentication and allow connections to the Device Provisioning Service.
Specifies the use of three GPIOs.
Allows the application to configure the hardware address of the network interface.
Specifies the use of one UART peripheral.
Enables mutable storage with 64 kibibytes of storage space.
Enables the app to use the WifiConfig API to change the Wi-Fi configuration.
Specifies the use of one SPI master interface.
Specifies the use of one I2C master interface.
Enables the app to configure system time using the RTC API.
Enables mallocng for app development.

इसके माध्यम से साझा किया गया

Application manifest

Contents of the application manifest

Example

प्रतिक्रिया

अतिरिक्त संसाधन