Manifeste d’application

Article
11/09/2023

Le manifeste d’application décrit les ressources, également appelées fonctionnalités d’application, dont une application a besoin. Chaque application a un manifeste d’application.

Les applications doivent choisir d’utiliser les fonctionnalités en répertoriant chaque ressource requise dans la section Fonctionnalités du manifeste de l’application . aucune fonctionnalité n’est activée par défaut. Si une application demande une fonctionnalité qui n’est pas répertoriée, la demande échoue. Si le fichier manifeste de l’application contient des erreurs, les tentatives de chargement indépendant de l’application échouent. Le manifeste de chaque application doit être stocké sous app_manifest.json dans le répertoire racine du dossier d’application sur votre PC.

Le modèle Azure Sphere crée automatiquement un manifeste d’application par défaut lorsque vous créez une application. Vous devez modifier le manifeste par défaut pour répertorier les fonctionnalités dont votre application a besoin. Chaque exemple Azure Sphere inclut également un manifeste d’application. Si vous basez votre application sur un exemple, vous devrez probablement également modifier le manifeste.

Différents appareils Azure Sphere peuvent exposer les fonctionnalités de la puce de différentes manières. Par conséquent, la valeur que vous utilisez dans le manifeste pour identifier une fonctionnalité particulière, telle qu’une broche GPIO, peut varier en fonction du matériel pour lequel vous développez. Gérer les dépendances matérielles cibles fournit plus d’informations sur les cibles matérielles pour une application de haut niveau. Dans le manifeste de l’application pour une application de haut niveau, utilisez les constantes définies dans le fichier JSON dans le dossier HardwareDefinitions du répertoire d’installation du Kit de développement logiciel (SDK) Microsoft Azure Sphere. L’emplacement exact du répertoire d’installation diffère sur Windows et Linux. Dans une application compatible en temps réel (RTApp), utilisez les valeurs brutes répertoriées dans Contenu du manifeste de l’application.

Lorsqu’une application est chargée de manière indépendante ou déployée sur l’appareil, le runtime Azure Sphere lit le manifeste de l’application pour déterminer les fonctionnalités que l’application est autorisée à utiliser. Les tentatives d’accès aux ressources qui ne sont pas répertoriées dans le manifeste entraînent des erreurs d’API telles que EPERM (autorisation refusée). Une seule application sur l’appareil peut utiliser une ressource. Si vous installez une application qui demande une ressource déjà utilisée, la tentative échoue.

Contenu du manifeste de l’application

Le manifeste de l’application comprend les éléments suivants :

Nom	Description
SchemaVersion	Version du schéma de manifeste d’application en cours d’utilisation. Actuellement, doit être 1. Obligatoire.
Nom	Nom de l’application. Lors de la création du projet, cette valeur est définie sur le nom du projet. Le nom peut être de n’importe quelle longueur, mais seuls les 31 premiers caractères sont stockés dans le package d’image ; par conséquent, le nom apparaît tronqué dans les requêtes sur le package d’image. Obligatoire.
ComponentId	ID du composant. Visual Studio crée cet ID lorsque vous générez l’application. Si vous n’utilisez pas Visual Studio, consultez Générer un ID de composant pour plus d’informations sur la création de l’ID. Obligatoire.
EntryPoint	Nom de l’exécutable, ainsi que le chemin d’accès relatif dans l’image du système de fichiers de l’application, qui est créé lors de la génération de l’application. Visual Studio utilise actuellement /bin/app pour cette valeur. Obligatoire.
CmdArgs	Arguments à passer à l’application au démarrage. Placez chaque argument entre guillemets doubles et séparez les arguments par une virgule. Optionnel.
TargetBetaApis	Spécifie que l’application requiert des API bêta et identifie l’ensemble des API bêta utilisées. Ce champ est automatiquement ajouté pendant le processus de génération si l’application est générée à l’aide d’API bêta. Optionnel. Pour plus d’informations, consultez Utiliser les fonctionnalités bêta .
ApplicationType	Type d’application. Optionnel. Définissez sur Débogueur uniquement si vous créez un remplacement pour gdbserver.
Capacités	Liste des paires clé/valeur qui spécifient les besoins en ressources de l’application. Obligatoire.
MallocVersion	Entier qui spécifie la version de malloc, où 1=standard et 2=mallocng, malloc amélioré disponible dans les versions MUSL supérieures à 1.2.1. La version 2 est recommandée pour tous les nouveaux développements d’applications.

La section Fonctionnalités prend en charge les éléments suivants :

Note

Les applications de haut niveau peuvent utiliser des valeurs de capacité à partir de fichiers de définition de matériel ou utiliser des valeurs brutes. Toutefois, vous ne pouvez pas combiner les deux types valeur dans la même fonctionnalité. Les applications en temps réel peuvent utiliser uniquement des valeurs brutes pour les fonctionnalités.

Nom	Description
Adc	Contrôleur de conversion analogique-numérique (ADC) utilisé par l’application. Cette fonctionnalité réserve l’intégralité du contrôleur ADC (qui comprend un bloc à 8 broches), pas seulement la broche 0 dans le bloc. Dans une application de haut niveau, spécifiez le nom du périphérique déclaré dans le fichier d’en-tête de définition matérielle. Dans une application en temps réel, spécifiez la valeur AppManifestValue déclarée dans le fichier JSON de définition matérielle. Exemple de définition de matériel :`"Adc": [ "$MT3620_RDB_ADC_CONTROLLER0" ]` Exemple de valeur brute :`"Adc": [ "ADC-CONTROLLER-0" ]` Référence d’API :Applibs adc.h Conceptuel :Utilisation d’ADC sur Azure Sphere
AllowedApplicationConnections	Liste des ID de composant d’application auxquels l’application est autorisée à se connecter. Exemple:`"AllowedApplicationConnections": [ "005180BC-402F-4CB3-A662-72937DBCDE47" ]` Référence d’API :Applibs application.h Conceptuel :Communiquer avec une application de haut niveau
AllowedConnections	Liste des noms d’hôtes DNS ou des adresses IP (IPv4) auxquels l’application est autorisée à se connecter. Si l’application utilise un Azure IoT Hub, la liste doit inclure l’adresse IP ou le nom d’hôte DNS du hub, généralement hub-name.azure-devices.net. Les numéros de port et les caractères génériques dans les noms et les adresses IP ne sont pas acceptés. Exemple:`"AllowedConnections" : [ "my-hub.example.net", "global.azure-devices-provisioning.net" ]`
AllowedTcpServerPorts	Liste des ports qui autorisent le trafic TCP entrant. Vous pouvez inclure jusqu’à 10 ports, et chaque port doit être répertorié individuellement. Les ports pris en charge sont 1024 à 65535. Vous pouvez spécifier les mêmes ports pour TCP et UDP. Toutefois, si vous spécifiez le même port pour plusieurs applications sur l’appareil, le chargement de la deuxième application à exécuter échoue. Exemple:`"AllowedTcpServerPorts": [ 1024, 65535 ]`
AllowedUdpServerPorts	Liste des ports qui autorisent le trafic UDP entrant. Vous pouvez inclure jusqu’à 10 ports, et chaque port doit être répertorié individuellement. Les ports pris en charge sont 1024 à 65535. Vous pouvez spécifier les mêmes ports pour TCP et UDP. Toutefois, si vous spécifiez le même port pour plusieurs applications sur l’appareil, le chargement de la deuxième application à exécuter échoue. Exemple:`"AllowedUdpServerPorts": [ 1024, 50000 ]`
CertStore	Valeur booléenne qui indique si une application de haut niveau est autorisée à gérer les certificats avec l’API CertStore : true pour activer l’API ; sinon, false. Exemple:`"CertStore" : true`
DeviceAuthentication	Chaîne qui spécifie l’UUID du locataire Azure Sphere (hérité) à utiliser pour l’authentification de l’appareil. Exemple:`"DeviceAuthentication": "77304f1f-9530-4157-8598-30bc1f3d66f0"`
DhcpService	Valeur booléenne qui indique si l’application est autorisée à configurer le service DHCP : true si l’application dispose de la fonctionnalité ; sinon, false. Exemple:`"DhcpService" : true` Référence d’API :Bibliothèques d’applications networking.h Concept :Utiliser des services réseau
EnterpriseWifiConfig	Valeur booléenne qui indique si une application de haut niveau est autorisée à créer un réseau EAP-TLS et à y associer des certificats : true si l’application dispose de la fonctionnalité ; sinon, false. Exemple:`"EnterpriseWifiConfig" : true`
ExternalInterrupt	Liste des interruptions externes qu’une application en temps réel utilise. Cette fonctionnalité n’est pas disponible pour les applications de haut niveau. Exemple:`"ExternalInterrupt": [ "EINT4", "EINT12" ]`
Gpio	Liste des GPIO que l’application utilise. Dans une application de haut niveau, spécifiez le nom GPIO qui est déclaré dans le fichier d’en-tête de définition matérielle, par exemple $MT 3620_RDB_LED1_RED. Dans une application en temps réel, spécifiez les entiers qui correspondent aux nombres GPIO dans le fichier JSON de définition matérielle. Par exemple, 8 spécifie GPIO 8. Exemple de définition de matériel :`"Gpio": [ "$MT3620_RDB_HEADER1_PIN6_GPIO", "$MT3620_RDB_LED1_RED", "$MT3620_RDB_BUTTON_A" ]` Exemple de valeur brute :`"Gpio": [ 8, 12 ]` Référence d’API :Applibs gpio.h Conceptuel :Utilisation de GPIOs sur Azure Sphere
HardwareAddressConfig	Valeur booléenne qui indique si l’application est autorisée à configurer l’adresse matérielle de l’interface réseau : true si l’application a la capacité ; sinon, false. Exemple:`"HardwareAddressConfig" : true` Référence d’API :Bibliothèques d’applications networking.h Concept :Utiliser des services réseau
HeapMemStats	Valeur booléenne qui indique si le suivi de l’allocation de mémoire du tas est activé : true si l’application dispose de la fonctionnalité ; sinon, false. Exemple:`"HeapMemStats": true` Conceptuel :Utilisation de la mémoire dans les applications de haut niveau
I2cMaster	Liste des interfaces I2C master utilisées par l’application. Dans une application de haut niveau, spécifiez le nom du périphérique déclaré dans le fichier d’en-tête de définition matérielle. Dans une application en temps réel, spécifiez la valeur AppManifestValue déclarée dans le fichier JSON de définition matérielle. Exemple de définition de matériel :`"I2cMaster": [ "$MT3620_RDB_HEADER2_ISU0_I2C", "$MT3620_RDB_HEADER4_ISU1_I2C" ]` Exemple de valeur brute :`"I2cMaster": [ "ISU0", "ISU1" ]` Référence d’API :Bibliothèques d’applications i2c.h Conceptuel :Utilisation d’I2C avec Azure Sphere
I2sSubordinate	Interface subordonnée I2S (Inter-IC Sound) utilisée par une application rtapp. Cette fonctionnalité n’est pas disponible pour les applications de haut niveau. Exemple de valeur brute : « I2sSubordinate » : [ « I2S0 », « I2S1 » ]
MutableStorage	Paramètres de stockage mutables qui permettent à l’application d’utiliser le stockage persistant. Exemple:`"MutableStorage" : { "SizeKB": 64, }` Référence d’API :Bibliothèques d’applications storage.h Conceptuel :Utilisation du stockage sur Azure Sphere
NetworkConfig	Boolean qui indique si l’application a l’autorisation de configurer une interface réseau : true si l’application a la capacité ; sinon, false. Exemple:`"NetworkConfig" : true` Référence d’API :Bibliothèques d’applications networking.h Concept :Utiliser des services réseau
PowerControls	Tableau de chaînes qui représentent des fonctionnalités granulaires pour contrôler l’état d’alimentation de l’appareil. ForcePowerDown et ForceReboot sont les seules valeurs prises en charge. Avertissement: Étant donné que ForcePowerDown et ForceReboot permettent à une application d’arrêter immédiatement toutes les applications, vous devez vous assurer que votre appareil peut toujours recevoir les mises à jour du système d’exploitation et de l’application. Pour plus d’informations et d’aide, consultez Forcer la mise hors tension et mises à jour. Exemple:`"PowerControls": ["ForcePowerDown", "ForceReboot"]` Référence d’API :Powermanagement des bibliothèques d’applications.h Conceptuel :Gérer l’état de mise hors tension pour les appareils Azure Sphere
Pwm	Module de largeur d’impulsion (PWM) utilisé par l’application. Dans une application de haut niveau, spécifiez le nom du périphérique déclaré dans le fichier d’en-tête de définition matérielle. Dans une application en temps réel, spécifiez la valeur AppManifestValue déclarée dans le fichier JSON de définition matérielle. Exemple de définition de matériel :`"Pwm": [ "$MT3620_RDB_LED_PWM_CONTROLLER2" ]` Exemple de valeur brute :`"Pwm": [ "PWM-CONTROLLER-0" ]` Référence d’API :Applibs pwm.h Conceptuel :Utiliser des pwms dans des applications de haut niveau
ReadNetworkProxyConfig	Valeur booléenne qui indique si l’application est autorisée à récupérer la configuration du proxy : true si l’application a la fonctionnalité ; sinon, false. Exemple:`"ReadNetworkProxyConfig": true` Référence d’API :Bibliothèques d’applications networking.h Conceptuel :Se connecter à des services web
SntpService	Valeur booléenne qui indique si l’application est autorisée à configurer le service SNTP : true si l’application dispose de la fonctionnalité ; sinon, false. Exemple:`"SntpService" : true` Référence d’API :Bibliothèques d’applications networking.h Conceptuel :Serveur SNTP
SoftwareUpdateDeferral	Valeur booléenne qui indique si l’application est autorisée à différer les mises à jour logicielles pendant une période limitée : true si l’application a la capacité ; sinon, false. Exemple:`"SoftwareUpdateDeferral" : true` Référence d’API :Eventloop Applibs.h Conceptuel :Différer les mises à jour de l’appareil
SpiMaster	Liste des interfaces spi master utilisées par l’application. Dans une application de haut niveau, spécifiez le nom du périphérique déclaré dans le fichier d’en-tête de définition matérielle. Dans une application en temps réel, spécifiez la valeur AppManifestValue déclarée dans le fichier JSON de définition matérielle. Exemple de définition de matériel :`"SpiMaster": [ "$MT3620_RDB_HEADER2_ISU0_SPI", "$MT3620_RDB_HEADER4_ISU1_SPI" ]` Exemple de valeur brute :`"SpiMaster": [ "ISU0", "ISU1" ]` Référence d’API :Applibs spi.h Conceptuel :Utilisation de SPI avec Azure Sphere
SystemEventNotifications	Valeur booléenne qui indique si l’application est autorisée à recevoir des notifications d’événements système : true si l’application a la capacité ; sinon, false. Exemple:`"SystemEventNotifications" : true` Référence d’API :Applibs sysevent.h Conceptuel :Différer les mises à jour de l’appareil
SystemTime	Valeur booléenne qui indique si l’application a l’autorisation de configurer l’heure système : true si l’application a la fonctionnalité ; sinon, false. Exemple:`"SystemTime" : true` Référence d’API :Bibliothèques d’applications rtc.h Conceptuel :Gérer l’heure système et le RTC sur Azure Sphere
TimeSyncConfig	Valeur booléenne qui indique si l’application est autorisée à configurer le service de synchronisation de l’heure : true si l’application dispose de la fonctionnalité ; sinon, false. Exemple:`"TimeSyncConfig" : true`
Uart	Liste des périphériques UART que l’application utilise. Cette fonctionnalité n’active pas l’UART dédié sur une carte de développement MT3620. Pour plus d’informations sur l’UART dédié, consultez Créer une application prenant en charge le temps réel. Dans une application de haut niveau, spécifiez le nom du périphérique déclaré dans le fichier d’en-tête de définition matérielle. Dans une application en temps réel, spécifiez la valeur AppManifestValue déclarée dans le fichier JSON de définition matérielle. Exemple de définition de matériel :`"Uart": [ "$MT3620_RDB_HEADER2_ISU0_UART", "$MT3620_RDB_HEADER4_ISU1_UART" ]` Exemple de valeur brute :`"Uart": [ "ISU0", "ISU1" ]` Référence d’API :Bibliothèques d’applications uart.h Conceptuel :Utiliser UART sur Azure Sphere
WifiConfig	Valeur booléenne qui indique si l’application a l’autorisation d’utiliser l’API WifiConfig pour modifier la configuration Wi-Fi : true si l’application a la fonctionnalité ; sinon, false. Exemple:`"WifiConfig" : true` Référence d’API :Applibs wificonfig.h Concept :Configurer la mise en réseau

La section MutableStorage prend en charge les éléments suivants :

Nom	Description
SizeKB	Entier qui spécifie la taille du stockage mutable en Kibioctets. La valeur maximale est 64. La valeur 0 équivaut à ne pas avoir la capacité de stockage mutable.

Exemple

Voici un exemple de fichier app_manifest.json pour une application de haut niveau qui cible le matériel RDB MT3620 :

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

L’exemple de fichier app_manifest.json pour MyTestApp effectue les opérations suivantes :

Passe quatre arguments de ligne de commande à l’application.
Autorise uniquement les connexions aux hôtes DNS my-hub.example.net, contoso.azure-devices.net et global.azure-devices-provisioning.net.
Autorise le trafic TCP entrant sur les ports 1024 et 65535.
Autorise le trafic UDP entrant sur les ports 1024 et 50000.
Spécifie un UUID de locataire Azure Sphere (hérité) à utiliser pour l’authentification de l’appareil et autoriser les connexions au service Device Provisioning.
Spécifie l’utilisation de trois GPIOs.
Permet à l’application de configurer l’adresse matérielle de l’interface réseau.
Spécifie l’utilisation d’un périphérique UART.
Active le stockage mutable avec 64 Kibioctets d’espace de stockage.
Permet à l’application d’utiliser l’API WifiConfig pour modifier la configuration Wi-Fi.
Spécifie l’utilisation d’une interface master SPI.
Spécifie l’utilisation d’une interface de master I2C.
Permet à l’application de configurer l’heure système à l’aide de l’API RTC.
Active mallocng pour le développement d’applications.

Manifeste d’application

Contenu du manifeste de l’application

Exemple

Ressources supplémentaires