Schéma pour les définitions des capacités

Une capacité est documentée à l'aide d'un document JSON déclaratif qui fournit un contrat clair sur la manière dont la capacité doit fonctionner au sein du système.

Pour une capacité, les éléments obligatoires sont$id, nameextrinsicId, extrinsicVersion et au moins un élément dans au moins l'une des sections suivantes :

• properties

• actions

• events

Les éléments facultatifs d'une fonctionnalité sont $ref titledescription,version, $defs etextrinsicProperties. Pour une fonctionnalité, vous $ref devez vous référer àaws.capability.

Les sections suivantes détaillent le schéma utilisé pour les définitions des capacités.

$id (obligatoire)

L'élément $id identifie la définition du schéma. Il doit suivre cette structure :

• Commencez par le préfixe /schema-versions/ URI

• Inclure le type de capability schéma

• Utiliser une barre oblique (/) comme séparateur de chemin d'URI

• Incluez l'identité du schéma, avec des fragments séparés par des points (.)

• Utilisez le @ caractère pour séparer l'ID et la version du schéma

• Terminez par la version semver, en utilisant des points (.) pour séparer les fragments de version

L'identité du schéma doit commencer par un espace de noms racine de 3 à 12 caractères, suivi d'un sous-espace et d'un nom facultatifs.

La version semver inclut une version MAJEURE (jusqu'à 3 chiffres), une version MINEURE (jusqu'à 3 chiffres) et une version PATCH optionnelle (jusqu'à 4 chiffres).

Note

Vous ne pouvez pas utiliser les espaces de noms aws réservés ou matter

Exemple $id

/schema-version/capability/aws.Recording@1.0

$ref

L'$refélément fait référence à une capacité existante au sein du système. Il suit les mêmes contraintes que l'$idélément.

Note

Une définition de type ou une capacité doit exister avec la valeur fournie dans le $ref fichier.

Exemple $ref

/schema-version/definition/aws.capability@1.0

nom (obligatoire)

L'élément name est une chaîne représentant le nom de l'entité dans le document de schéma. Il contient souvent des abréviations et doit respecter les règles suivantes :

• Ne contiennent que des caractères alphanumériques, des points (.), des barres obliques (/), des tirets (-) et des espaces

• Commencez par une lettre

• 64 caractères maximum

L'élément name est utilisé dans l'interface utilisateur et la documentation de la console Amazon Web Services.

Exemples de noms

Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

title

L'élément de titre est une chaîne descriptive de l'entité représentée par le document de schéma. Il peut contenir n'importe quel caractère et est utilisé dans la documentation. La longueur maximale du titre d'une fonctionnalité est de 256 caractères.

Exemples de titres

Real-time Communication (RTC) Session Controller
Energy EVSE Capability

description

L'descriptionélément fournit une explication détaillée de l'entité représentée par le document de schéma. Il peut contenir n'importe quel caractère et est utilisé dans la documentation. La longueur maximale d'une description de capacité est de 2 048 caractères

Exemple Description de l'exemple

Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. 
            This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management.

version

L’élément version est facultatif. Il s'agit d'une chaîne qui représente la version du document de schéma. Il présente les contraintes suivantes :

• Utilise le format semver, avec les fragments de version suivants séparés par . (points).

  • MAJORversion, maximum de 3 chiffres

  • MINORversion, maximum de 3 chiffres

  • PATCHversion (facultatif), maximum de 4 chiffres

• La longueur peut être comprise entre 3 et 12 caractères.

Exemples de versions

1.0

1.12

1.4.1

Utilisation des versions de fonctionnalités

Une capacité est une entité versionnée immuable. Toute modification est censée créer une nouvelle version. Le système utilise le versionnement sémantique au format MAJOR.MINOR.PATCH, où :

• La version MAJEURE augmente en cas de modifications d'API incompatibles avec les versions antérieures

• La version MINOR augmente lors de l'ajout de fonctionnalités de manière rétrocompatible

• La version du PATCH augmente lorsque des ajouts mineurs non impactants sont apportés à la fonctionnalité.

Les fonctionnalités dérivées des clusters Matter sont basées sur la version 1.4 et chaque version de Matter devrait être importée dans le système. Comme la version Matter consomme à la fois les niveaux MAJOR et MINOR de semver, les intégrations gérées ne peuvent utiliser que les versions PATCH.

Lorsque vous ajoutez des versions PATCH pour Matter, assurez-vous de tenir compte du fait que ce Matter utilise des révisions séquentielles. Toutes les versions de PATCH doivent être conformes à la révision documentée dans la spécification Matter et elles doivent être rétrocompatibles.

Pour résoudre les problèmes d'incompatibilité descendante, vous devez travailler avec la Connectivity Standards Alliance (CSA) pour résoudre les problèmes mentionnés dans la spécification et publier une nouvelle révision.

AWS-les fonctionnalités gérées ont été publiées avec une version initiale de1.0. Avec ceux-ci, les trois niveaux de version peuvent être utilisés.

Version extrinsèque (obligatoire)

Il s'agit d'une chaîne représentant une version gérée en dehors du AWS IoT système. Pour les fonctionnalités de Matter, extrinsicVersion des mappages vers revision

Il est représenté sous la forme d'une valeur entière sous forme de chaîne et sa longueur peut être comprise entre 1 et 10 chiffres numériques.

Exemples de versions

7

1567

ExtrinsiciD (obligatoire)

L'extrinsicIdélément représente un identifiant géré en dehors du système IoT d'Amazon Web Services. Pour les fonctionnalités de MatterclusterId, elles attributeId correspondent àcommandId,eventId,fieldId, ou, selon le contexte.

Il extrinsicId peut s'agir d'un entier décimal à chaînes (1 à 10 chiffres) ou d'un entier hexadécimal à chaînes (préfixe 0x ou 0X, suivi de 1 à 8 chiffres hexadécimaux).

Note

Pour AWS, l'ID du fournisseur (VID) est 0x1577, et pour Matter, il est égal à 0. Le système garantit que les schémas personnalisés n'utilisent pas ces schémas réservés VIDs aux fonctionnalités.

Exemples d'identifiants extrinsiciques

0018
0x001A
0x15771002

$deffs

La $defs section est une carte des sous-schémas qui peuvent être référencés dans le document de schéma comme le permet le schéma JSON. Dans cette carte, la clé est utilisée dans les définitions de référence locales et la valeur fournit le schéma JSON.

Note

Le système impose uniquement qu'il $defs s'agit d'une carte valide et que chaque sous-schéma est un schéma JSON valide. Aucune règle supplémentaire n'est appliquée.

Respectez les contraintes suivantes lorsque vous travaillez avec des définitions :

• Utilisez uniquement des caractères adaptés aux URI dans les noms de définition

• Assurez-vous que chaque valeur est un sous-schéma valide

• Incluez un nombre quelconque de sous-schémas conformes aux limites de taille du document de schéma

Propriétés extrinsèques

L'extrinsicPropertiesélément contient un ensemble de propriétés définies dans un système externe mais conservées dans le modèle de données. En ce qui concerne les fonctionnalités de Matter, il correspond à différents éléments non modélisés ou partiellement modélisés au sein d'un cluster, d'un attribut, d'une commande ou d'un événement ZCL.

Les propriétés extrinsèques doivent respecter les contraintes suivantes :

• Les noms de propriété doivent être alphanumériques, sans espaces ni caractères spéciaux

• Les valeurs de propriété peuvent être n'importe quelle valeur de schéma JSON

• Maximum de 20 propriétés

Le système prend en charge divers extrinsicPropertiesaccess, notammentapiMaturity,cli,cliFunctionName, et autres. Ces propriétés facilitent l'ACL pour les transformations de modèles de données AWS (et vice versa).

Note

Les propriétés extrinsèques sont prises en charge pour les éléments action eventproperty,, et struct les champs d'une capacité, mais pas pour la capacité ou le cluster lui-même.

Propriétés

Les propriétés représentent les états de la fonctionnalité gérés par le périphérique. Chaque état est défini comme une paire clé-valeur, où la clé décrit le nom de l'état et la valeur décrit la définition de l'état.

Lorsque vous travaillez avec des propriétés, respectez les contraintes suivantes :

• Utilisez uniquement des caractères alphanumériques dans les noms de propriétés, sans espaces ni caractères spéciaux

• Incluez un nombre quelconque de propriétés conformes aux limites de taille du document de schéma

Utilisation des propriétés

Une propriété au sein d'une fonctionnalité est un élément fondamental qui représente un état spécifique d'un appareil alimenté par des intégrations gérées. Il représente l'état ou la configuration actuelle de l'appareil. En normalisant la façon dont ces propriétés sont définies et structurées, les systèmes domotiques garantissent que les appareils de différents fabricants peuvent communiquer efficacement, créant ainsi une expérience fluide et interopérable.

Pour une propriété de capacité, les éléments obligatoires sont extrinsicId etvalue. Les éléments facultatifs d'une propriété de capacité sont descriptionretrievable,mutable, reportable etextrinsicProperties.

Valeur

Une structure illimitée qui permet aux constructeurs de définir toutes les contraintes conformes au schéma JSON pour définir le type de données de cette propriété.

Lorsque vous définissez des valeurs, respectez les contraintes suivantes :

• Pour les types simples, utilisez type et toute autre contrainte de schéma JSON native telle que ou maxLength maximum

• Pour les types compositesoneOf, utilisezallOf, ouanyOf. Le système ne prend pas en charge le not mot clé

• Pour faire référence à un type global, utilisez-le $ref avec une référence détectable valide

• Pour la nullabilité, suivez la définition du schéma de type OpenAPI en fournissant à l'attribut nullable un indicateur booléen (truesi null est une valeur autorisée)

Exemple :

{
    "$ref": "/schema-versions/definition/matter.uint16@1.4",
    "nullable": true,
    "maximum": 4096
}

Récupérable

Un booléen décrivant si l'état est lisible ou non.

L'aspect lisibilité de l'état dépend de la mise en œuvre de la fonctionnalité par le périphérique. L'appareil décide si un état donné est lisible ou non. Cet aspect de l'état n'est pas encore pris en charge pour être signalé dans le rapport de capacité et n'est donc pas appliqué au sein du système.

Exemple : true ou false

Mutable

Un booléen décrivant si l'état est inscriptible ou non.

L'aspect inscriptible de l'état est reporté à la mise en œuvre de la capacité par le périphérique. L'appareil décide si un état donné est inscriptible ou non. Cet aspect de l'état n'est pas encore pris en charge pour être signalé dans le rapport de capacité et n'est donc pas appliqué au sein du système.

Exemple : true ou false

À signaler

Un booléen décrivant si l'état est signalé par le périphérique lorsqu'il y a un changement d'état.

L'aspect déclarable de l'état est reporté à la mise en œuvre de la fonctionnalité par l'appareil. L'appareil décide si un état donné est déclarable ou non. Cet aspect de l'état n'est pas encore pris en charge pour être signalé dans le rapport de capacité et n'est donc pas appliqué au sein du système.

Exemple : true ou false

Actions

Les actions sont des opérations gérées par un schéma qui suivent un modèle de demande-réponse. Chaque action représente une opération mise en œuvre par l'appareil.

Respectez les contraintes suivantes lors de la mise en œuvre des actions :

• N'incluez que des actions uniques dans le tableau d'actions

• Incluez autant d'actions que vous le souhaitez, conformément aux limites de taille du document de schéma

Utilisation des actions

Une action est un moyen standardisé d'interagir avec les fonctionnalités des appareils et de les contrôler dans un système d'intégration géré. Il représente une commande ou une opération spécifique qui peut être exécutée sur un appareil, avec un format structuré pour modéliser les paramètres de demande ou de réponse nécessaires. Ces actions servent de pont entre les intentions des utilisateurs et le fonctionnement des appareils, permettant ainsi un contrôle cohérent et fiable des différents types d'appareils intelligents.

Pour une action, les éléments obligatoires sont name etextrinsicId. Les éléments facultatifs sont descriptionextrinsicProperties, request etresponse.

Description

La limite de longueur maximale de la description est de 1 536 caractères.

Demande

La section de demande est facultative et peut être omise s'il n'y a aucun paramètre de demande. En cas d'omission, le système prend en charge l'envoi d'une demande sans aucune charge utile en utilisant simplement le nom de. Action Ceci est utilisé pour des actions simples, comme allumer ou éteindre une lumière.

Les actions complexes nécessitent des paramètres supplémentaires. Par exemple, une demande de diffusion de séquences vidéo peut inclure des paramètres concernant le protocole de diffusion à utiliser ou l'opportunité d'envoyer le flux à un périphérique d'affichage spécifique.

Pour une demande d'action, l'élément obligatoire estparameters. Les éléments facultatifs sont descriptionextrinsicId, etextrinsicProperties.

Description de la demande

La description suit le même format que celui de la section 3.5, avec une longueur maximale de 2 048 caractères.

Réponse

Dans les intégrations gérées, pour toute demande d'action envoyée via l'SendManagedThingCommandAPI, la demande atteint l'appareil et attend une réponse asynchrone. La réponse à l'action définit la structure de cette réponse.

Pour une demande d'action, l'élément obligatoire estparameters. Les éléments facultatifs sont namedescription,extrinsicId,extrinsicProperties, errors etresponseCode.

Description de la réponse

La description suit le même format quedescription, et sa longueur maximale est de 2 048 caractères.

Nom de la réponse

Le nom suit le même format quenom (obligatoire), avec les détails supplémentaires suivants :

• Le nom classique d'une réponse est dérivé en l'ajoutant Response au nom de l'action.

• Si vous souhaitez utiliser un autre nom, vous pouvez le fournir dans cet name élément. Si a name est fourni dans la réponse, cette valeur est plus prioritaire que le nom conventionnel.

Erreurs

Un tableau illimité de messages uniques fournis dans la réponse, en cas d'erreur lors du traitement de la demande.

Contraintes :

• Un élément de message est déclaré en tant qu'objet JSON avec les champs suivants :

  • code: chaîne contenant des caractères alphanumériques et _ (traits de soulignement), d'une longueur comprise entre 1 et 64 caractères

  • message: valeur de chaîne illimitée

Exemple de message d'erreur

"errors": [
   {  
      "code": "AD_001", 
      "message": "Unable to receive signal from the sensor. Please check connection with the sensor." 
   }
]

Code de réponse

Un code entier indiquant comment la demande a été traitée. Nous recommandons que le code de l'appareil renvoie un code utilisant la spécification du code d'état de réponse du serveur HTTP afin de garantir l'uniformité au sein du système.

Contrainte : valeur entière comprise entre 100 et 599.

Paramètres de demande ou de réponse

La section des paramètres est définie comme une carte des paires de noms et de sous-schémas. Un certain nombre de paramètres peuvent être définis dans les paramètres de demande, s'ils peuvent être intégrés au document de schéma.

Les noms de paramètres ne peuvent contenir que des caractères alphanumériques. Les espaces ou tout autre caractère ne sont pas autorisés.

champ de paramètres

Les éléments obligatoires d'un parameter sont extrinsicId etvalue. Les éléments facultatifs sont description etextrinsicProperties.

L'élément de description suit le même format quedescription, avec une longueur maximale de 1024 caractères.

extrinsicIdet extrinsicProperties dérogations

extrinsicIdet extrinsicProperties suivez le même format que ExtrinsiciD (obligatoire) etPropriétés extrinsèques, avec ces informations supplémentaires :

• Si un extrinsicId est fourni dans la demande ou la réponse, cette valeur est plus prioritaire que la valeur fournie au niveau de l'action. Le système doit d'extrinsicIdabord utiliser request/response le niveau ; en cas d'absence, utiliser le niveau d'action extrinsicId

• Si extrinsicProperties elles sont fournies dans la demande ou la réponse, ces propriétés ont une priorité supérieure à la valeur va fournie au niveau de l'action. Le système doit prendre le niveau d'action extrinsicProperties et remplacer les paires clé-valeur fournies au niveau request/response extrinsicProperties

Exemple de remplacement d'ExtrinsicID et d'ExtrinsicProperties

{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

Dans l'exemple ci-dessus, les valeurs effectives de la demande d'action seraient les suivantes :

# effective request
"name": "ToggleWithEffect",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "stable",
   "introducedIn": "1.2"
   "manufacturerCode": "XYZ"
},
"parameters": {
   ...
}

# effective response
"name": "ToggleWithEffectResponse",
"extrinsicId": "0x0001",
"extrinsicProperties": {
   "apiMaturity": "provisional",
   "introducedIn": "1.2"
   "noDefaultImplementation": true
},
"parameters": {
   ...
}

Actions intégrées

Pour toutes les fonctionnalités, vous pouvez effectuer des actions personnalisées à l'aide des mots clés ReadState etUpdateState. Ces deux mots clés d'action agiront sur les propriétés de la fonctionnalité définies dans le modèle de données.

ReadState

Envoie une commande au managedThing pour lire les valeurs de ses propriétés d'état. ReadStateÀ utiliser pour forcer la mise à jour de l'état de l'appareil.

UpdateState

Envoie une commande pour mettre à jour certaines propriétés.

Il peut être utile de forcer la synchronisation de l'état d'un appareil dans les scénarios suivants :

1. L'appareil est resté hors ligne pendant un certain temps et n'émettait aucun événement.

2. L'appareil vient d'être provisionné et aucun état n'est encore maintenu dans le cloud.

3. L'état de l'appareil n'est pas synchronisé avec l'état réel de l'appareil.

ReadState exemples

Vérifiez si le voyant est allumé ou éteint à l'aide de l'SendManagedThingCommandAPI :

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "OnOff" ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Lisez toutes les propriétés d'état de la matter.OnOff fonctionnalité :

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "*" ] 
                // Use the wildcard operator to read ALL state properties for a capability
              }
            }
          ]
        }
      ]
    }
  ]
}

UpdateState exemple

Changez le OnTime pour une lampe à l'aide de l'SendManagedThingCommandAPI :

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "UpdateState",
              "parameters": {
                "OnTime": 5
              }
            }
          ]
        }
      ]
    }
  ]
}

Événements

Les événements sont des signaux unidirectionnels gérés par un schéma mis en œuvre par le dispositif.

Implémentez les événements en fonction des contraintes suivantes :

• Inclure uniquement les événements uniques dans le tableau des événements

• Incluez un nombre quelconque d'événements correspondant aux limites de taille du document de schéma