Schema per le definizioni delle funzionalità

Una funzionalità è documentata utilizzando un documento JSON dichiarativo che fornisce un contratto chiaro su come la funzionalità dovrebbe funzionare all'interno del sistema.

Per una funzionalità, gli elementi obbligatori sono $idname,extrinsicId, extrinsicVersion e almeno un elemento in almeno una delle seguenti sezioni:

• properties

• actions

• events

Gli elementi opzionali di una funzionalità sono $reftitle,description,version, $defs eextrinsicProperties. Per una funzionalità, $ref deve fare riferimento aaws.capability.

Le sezioni seguenti descrivono in dettaglio lo schema utilizzato per le definizioni delle funzionalità.

$id (obbligatorio)

L'elemento $id identifica la definizione dello schema. Deve seguire questa struttura:

• Inizia con il prefisso /schema-versions/ URI

• Includi il tipo di capability schema

• Usa una barra (/) come separatore di percorso URI

• Includi l'identità dello schema, con frammenti separati da punti () .

• Usa il @ carattere per separare l'ID e la versione dello schema

• Termina con la versione semver, usando period (.) per separare i frammenti di versione

L'identità dello schema deve iniziare con uno spazio dei nomi radice lungo 3-12 caratteri, seguito da uno spazio dei nomi secondario e da un nome opzionali.

La versione semver include una versione MAJOR (fino a 3 cifre), una versione MINOR (fino a 3 cifre) e una versione PATCH opzionale (fino a 4 cifre).

Nota

Non è possibile utilizzare i namespace riservati o aws matter

Esempio $id

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

$ref

L'$refelemento fa riferimento a una funzionalità esistente all'interno del sistema. Segue gli stessi vincoli dell'$idelemento.

Nota

È necessario che esista una definizione o una funzionalità del tipo con il valore fornito nel $ref file.

Esempio $ref

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

nome (obbligatorio)

L'elemento name è una stringa che rappresenta il nome dell'entità nel documento dello schema. Spesso contiene abbreviazioni e deve seguire queste regole:

• Contiene solo caratteri alfanumerici, punti (.), barre (/), trattini (-) e spazi

• Inizia con una lettera

• Massimo 64 caratteri

L'elemento name viene utilizzato nell'interfaccia utente e nella documentazione della console di Amazon Web Services.

Esempio Nomi di esempio

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

titolo

L'elemento title è una stringa descrittiva per l'entità rappresentata dal documento dello schema. Può contenere qualsiasi carattere e viene utilizzato nella documentazione. La lunghezza massima per un titolo di funzionalità è di 256 caratteri.

Esempio Titoli di esempio

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

description

L'descriptionelemento fornisce una spiegazione dettagliata dell'entità rappresentata dal documento dello schema. Può contenere qualsiasi carattere e viene utilizzato nella documentazione. La lunghezza massima per una descrizione delle funzionalità è di 2048 caratteri

Esempio Descrizione di esempio

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'elemento version è facoltativo. È una stringa che rappresenta la versione del documento dello schema. Vengono applicati i seguenti vincoli:

• Utilizza il formato semver, con i seguenti frammenti di versione separati da . (punti).

  • MAJORversione, massimo 3 cifre

  • MINORversione, massimo 3 cifre

  • PATCHversione (opzionale), massimo 4 cifre

• La lunghezza può essere compresa tra 3 e 12 caratteri.

Esempio Versioni di esempio

1.0

1.12

1.4.1

Utilizzo delle versioni con funzionalità

Una funzionalità è un'entità con versioni immutabili. Qualsiasi modifica dovrebbe creare una nuova versione. Il sistema utilizza il controllo delle versioni semantiche con il formato MAJOR.MINOR.PATCH, dove:

• La versione MAJOR aumenta quando si apportano modifiche all'API incompatibili con le versioni precedenti

• La versione MINOR aumenta quando si aggiungono funzionalità in modo retrocompatibile

• La versione PATCH aumenta quando si apportano aggiunte minori e senza impatto sulla funzionalità.

Le funzionalità derivate dai cluster Matter sono basate sulla versione 1.4 e ogni versione di Matter dovrebbe essere importata nel sistema. Poiché la versione Matter utilizza i livelli MAJOR e MINOR di semver, le integrazioni gestite possono utilizzare solo le versioni PATCH.

Quando aggiungi versioni PATCH per Matter, assicurati di tenere conto del fatto che Matter utilizza revisioni sequenziali. Tutte le versioni PATCH devono essere conformi alla revisione documentata nella specifica Matter e devono essere retrocompatibili.

Per risolvere eventuali problemi di incompatibilità con le versioni precedenti, è necessario collaborare con la Connectivity Standards Alliance (CSA) per risolverli nelle specifiche e rilasciare una nuova revisione.

AWS-le funzionalità gestite sono state rilasciate con una versione iniziale di. 1.0 Con queste, è possibile utilizzare tutti e tre i livelli di versione.

Extrinsic Version (obbligatoria)

Questa è una stringa che rappresenta una versione gestita all'esterno del sistema. AWS IoT Per le funzionalità di Matter, esegue il extrinsicVersion mapping a revision

È rappresentato come un valore intero con stringhe e la lunghezza può essere compresa tra 1 e 10 cifre numeriche.

Esempio Versioni di esempio

7

1567

ExtrinsICID (obbligatorio)

L'extrinsicIdelemento rappresenta un identificatore gestito all'esterno del sistema IoT di Amazon Web Services. Per le funzionalità di Matter, viene mappato a clusterId attributeIdcommandId,eventId,, ofieldId, a seconda del contesto.

extrinsicIdPuò essere un numero intero decimale con stringhe (1-10 cifre) o un intero esadecimale con stringhe (prefisso 0x o 0X, seguito da 1-8 cifre esadecimali).

Nota

Per, l' AWS ID fornitore (VID) è 0x1577 e per Matter è 0. Il sistema garantisce che gli schemi personalizzati non utilizzino queste funzionalità riservate. VIDs

Esempio: ExtrinsICIDS

0018
0x001A
0x15771002

$defs

La $defs sezione è una mappa di sottoschemi a cui è possibile fare riferimento all'interno del documento dello schema, come consentito dallo schema JSON. In questa mappa, la chiave viene utilizzata nelle definizioni di riferimento locali e il valore fornisce lo schema JSON.

Nota

Il sistema impone solo che $defs sia una mappa valida e che ogni sottoschema sia uno schema JSON valido. Non viene applicata alcuna regola aggiuntiva.

Segui questi vincoli quando lavori con le definizioni:

• Usa solo caratteri compatibili con gli URI nei nomi delle definizioni

• Assicurati che ogni valore sia un sottoschema valido

• Includi un numero qualsiasi di sottoschemi che rientrano nei limiti di dimensione del documento dello schema

Proprietà estrinseche

L'extrinsicPropertieselemento contiene un insieme di proprietà definite in un sistema esterno ma mantenute all'interno del modello di dati. Per quanto riguarda le funzionalità di Matter, esegue il mapping a diversi elementi non modellati o parzialmente modellati all'interno del cluster, dell'attributo, del comando o dell'evento ZCL.

Le proprietà estrinseche devono rispettare questi vincoli:

• I nomi delle proprietà devono essere alfanumerici senza spazi o caratteri speciali

• I valori delle proprietà possono essere qualsiasi valore dello schema JSON

• Massimo 20 proprietà

Il sistema supporta diverse funzionalitàextrinsicProperties, tra cui accessapiMaturity,cli,cliFunctionName, e altre ancora. Queste proprietà facilitano le trasformazioni tra ACL e modelli di dati AWS (e viceversa).

Nota

Le proprietà estrinseche sono supportate per gli elementi actionevent,property, e struct fields di una funzionalità, ma non per la capacità o il cluster stesso.

Proprietà

Le proprietà rappresentano gli stati della funzionalità gestiti dal dispositivo. Ogni stato è definito come una coppia chiave-valore, in cui la chiave descrive il nome dello stato e il valore descrive la definizione dello stato.

Quando lavorate con le proprietà, seguite questi vincoli:

• Utilizzate solo caratteri alfanumerici nei nomi delle proprietà, senza spazi o caratteri speciali

• Includi un numero qualsiasi di proprietà che rientrano nei limiti di dimensione del documento dello schema

Utilizzo delle proprietà

Una proprietà all'interno di una funzionalità è un elemento fondamentale che rappresenta uno stato specifico di un dispositivo basato su integrazioni gestite. Rappresenta la condizione o la configurazione corrente del dispositivo. Standardizzando il modo in cui queste proprietà sono definite e strutturate, i sistemi di casa intelligente garantiscono che i dispositivi di diversi produttori possano comunicare in modo efficace, creando un'esperienza fluida e interoperabile.

Per una proprietà di capacità, gli elementi obbligatori sono e. extrinsicId value Gli elementi opzionali di una proprietà di capacità sono descriptionretrievable,mutable, reportable eextrinsicProperties.

Valore

Una struttura illimitata che consente ai costruttori di inserire qualsiasi vincolo conforme allo schema JSON per definire il tipo di dati di questa proprietà.

Quando definisci i valori, segui questi vincoli:

• Per i tipi semplici, usa type e qualsiasi altro vincolo nativo dello schema JSON come o maxLength maximum

• Per i tipi compositi, usa, o. oneOf allOf anyOf Il sistema non supporta la not parola chiave

• Per fare riferimento a qualsiasi tipo globale, usala $ref con un riferimento rilevabile valido

• Per l'annullabilità, segui la definizione dello schema del tipo OpenAPI fornendo all'attributo nullable un flag booleano (se null è un valore consentito) true

Esempio:

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

Recuperabile

Un booleano che descrive se lo stato è leggibile o meno.

L'aspetto della leggibilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è leggibile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema.

Esempio: true o false

Mutable

Un booleano che descrive se lo stato è scrivibile o meno.

L'aspetto della scrivibilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è scrivibile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema.

Esempio: true o false

Segnalabile

Un booleano che descrive se lo stato viene segnalato dal dispositivo quando c'è un cambiamento nello stato.

L'aspetto relativo alla rendicontabilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è segnalabile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema.

Esempio: true o false

Azioni

Le azioni sono operazioni gestite dallo schema che seguono un modello di richiesta-risposta. Ogni azione rappresenta un'operazione implementata dal dispositivo.

Segui questi vincoli durante l'implementazione delle azioni:

• Includi solo azioni univoche nell'array delle azioni

• Includi un numero qualsiasi di azioni che rientrano nei limiti di dimensione del documento dello schema

Utilizzo di operazioni

Un'azione è un modo standardizzato per interagire e controllare le funzionalità dei dispositivi in un sistema di integrazione gestito. Rappresenta un comando o un'operazione specifico che può essere eseguito su un dispositivo, completo di un formato strutturato per modellare qualsiasi parametro di richiesta o risposta necessario. Queste azioni fungono da ponte tra le intenzioni degli utenti e le operazioni del dispositivo, consentendo un controllo coerente e affidabile su diversi tipi di dispositivi intelligenti.

Per un'azione, gli elementi obbligatori sono name eextrinsicId. Gli elementi opzionali sono descriptionextrinsicProperties, request eresponse.

Descrizione

La descrizione ha un limite di lunghezza massimo di 1536 caratteri.

Richiesta

La sezione di richiesta è facoltativa e può essere omessa se non ci sono parametri di richiesta. Se omessa, il sistema supporta l'invio di una richiesta senza alcun payload utilizzando semplicemente il nome di. Action Viene utilizzato per azioni semplici, come accendere o spegnere una luce.

Le azioni complesse richiedono parametri aggiuntivi. Ad esempio, una richiesta di streaming delle riprese della telecamera potrebbe includere parametri relativi al protocollo di streaming da utilizzare o se inviare lo streaming a un dispositivo di visualizzazione specifico.

Per una richiesta di azione, l'elemento obbligatorio èparameters. Gli elementi opzionali sono descriptionextrinsicId, eextrinsicProperties.

Descrizione della richiesta

La descrizione segue lo stesso formato della sezione 3.5, con una lunghezza massima di 2048 caratteri.

Risposta

Nelle integrazioni gestite, per ogni richiesta di azione inviata tramite l'SendManagedThingCommandAPI, la richiesta raggiunge il dispositivo e prevede una risposta asincrona. La risposta all'azione definisce la struttura di questa risposta.

Per una richiesta di azione, l'elemento obbligatorio èparameters. Gli elementi opzionali sono namedescription,extrinsicId,extrinsicProperties, errors eresponseCode.

Descrizione della risposta

La descrizione segue lo stesso description formato e ha una lunghezza massima di 2048 caratteri.

Nome della risposta

Il nome segue lo stesso formatonome (obbligatorio), con questi dettagli aggiuntivi:

• Il nome convenzionale di una risposta è derivato dall'aggiunta Response al nome dell'azione.

• Se desideri utilizzare un nome diverso, puoi fornirlo in questo name elemento. Se nella risposta name viene fornito a, questo valore ha la precedenza maggiore rispetto al nome convenzionale.

Errori

Una matrice illimitata di messaggi univoci fornita nella risposta, in caso di errori durante l'elaborazione della richiesta.

Vincoli:

• Un elemento del messaggio viene dichiarato come oggetto JSON con i seguenti campi:

  • code: Una stringa contenente caratteri alfanumerici e _ (caratteri di sottolineatura), con una lunghezza compresa tra 1 e 64 caratteri

  • message: valore di stringa illimitato

Esempio di messaggio di errore

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

Codice di risposta

Un codice intero che mostra come è stata gestita la richiesta. È consigliabile che il codice del dispositivo restituisca un codice utilizzando la specifica del codice di stato della risposta del server HTTP per consentire l'uniformità all'interno del sistema.

Vincolo: un valore intero compreso tra 100 e 599.

Parametri di richiesta o risposta

La sezione dei parametri è definita come una mappa di coppie di nomi e sottoschemi. È possibile definire un numero qualsiasi di parametri all'interno dei parametri della richiesta, se rientrano nel documento dello schema.

I nomi dei parametri possono contenere solo caratteri alfanumerici. Gli spazi o altri caratteri non sono consentiti.

campo dei parametri

Gli elementi obbligatori in a parameter sono extrinsicId evalue. Gli elementi opzionali sono description eextrinsicProperties.

L'elemento di descrizione segue lo stesso formato didescription, con una lunghezza massima di 1024 caratteri.

extrinsicIde sostituisce extrinsicProperties

extrinsicIde extrinsicProperties seguono lo stesso formato ExtrinsICID (obbligatorio) eProprietà estrinseche, con questi dettagli aggiuntivi:

• Se nella richiesta o nella risposta extrinsicId viene fornito un, questo valore ha la precedenza maggiore rispetto al valore fornito a livello di azione. Il sistema deve extrinsicId prima utilizzare request/response il livello, se manca utilizzare il livello di azione extrinsicId

• extrinsicPropertiesSe fornite nella richiesta o nella risposta, queste proprietà hanno la precedenza maggiore rispetto al valore va fornito a livello di azione. Il sistema deve passare al livello di azione extrinsicProperties e sostituire le coppie chiave-valore fornite a livello request/response extrinsicProperties

Esempio di override di ExtrinsicId ed ExtrinsicProperties

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

Nell'esempio precedente, i valori effettivi per la richiesta di azione sarebbero:

# 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": {
   ...
}

Azioni integrate

Per tutte le funzionalità, puoi eseguire azioni personalizzate utilizzando le parole chiave ReadState eUpdateState. Queste due parole chiave di azione agiranno sulle proprietà della funzionalità definite nel modello di dati.

ReadState

Invia un comando a managedThing per leggere i valori delle sue proprietà di stato. Viene utilizzato ReadState come metodo per forzare l'aggiornamento dello stato del dispositivo.

UpdateState

Invia un comando per aggiornare alcune proprietà.

Forzare la sincronizzazione dello stato del dispositivo può essere utile nei seguenti scenari:

1. Il dispositivo è rimasto offline per un periodo di tempo e non emetteva eventi.

2. Il dispositivo è stato appena fornito e non dispone ancora di alcuno stato mantenuto nel cloud.

3. Lo stato del dispositivo non è sincronizzato con lo stato reale del dispositivo.

ReadState esempi

Controlla se la luce è accesa o spenta utilizzando l'SendManagedThingCommandAPI:

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

Leggi tutte le proprietà dello stato relative alla matter.OnOff funzionalità:

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

Cambia OnTime for a light usando l'SendManagedThingCommandAPI:

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

Eventi

Gli eventi sono segnali unidirezionali gestiti dallo schema e implementati dal dispositivo.

Implementa gli eventi in base a questi vincoli:

• Includi solo eventi unici nell'array degli eventi

• Includi un numero qualsiasi di eventi che rientrano nei limiti di dimensione del documento dello schema