Esquema para las definiciones de capacidades

Una capacidad se documenta mediante un documento JSON declarativo que proporciona un contrato claro sobre cómo debe funcionar la capacidad en el sistema.

Para una capacidad, los elementos obligatorios son$id, nameextrinsicId, extrinsicVersion y al menos un elemento en al menos una de las siguientes secciones:

• properties

• actions

• events

Los elementos opcionales de una capacidad son $ref titledescription,version, $defs yextrinsicProperties. Para obtener una capacidad, $ref debe consultaraws.capability.

En las siguientes secciones se detalla el esquema utilizado para las definiciones de capacidad.

$id (obligatorio)

El elemento $id identifica la definición del esquema. Debe seguir esta estructura:

• Comience con el prefijo /schema-versions/ URI

• Incluya el tipo de capability esquema

• Utilice una barra inclinada (/) como separador de rutas de URI

• Incluya la identidad del esquema, con los fragmentos separados por puntos () .

• Utilice el @ carácter para separar el identificador del esquema y la versión

• Termine con la versión de semver, usando puntos (.) para separar los fragmentos de la versión

La identidad del esquema debe comenzar con un espacio de nombres raíz de entre 3 y 12 caracteres, seguido de un subespacio de nombres y un nombre opcionales.

La versión semver incluye una versión principal (hasta 3 dígitos), una versión SECUNDARIA (hasta 3 dígitos) y una versión PATCH opcional (hasta 4 dígitos).

nota

No puedes usar los espacios de nombres aws reservados o matter

ejemplo Ejemplo: $id

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

$ref

El $ref elemento hace referencia a una capacidad existente en el sistema. Sigue las mismas restricciones que el $id elemento.

nota

Debe existir una definición de tipo o una capacidad con el valor proporcionado en el $ref archivo.

ejemplo Ejemplo: $ref

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

nombre (obligatorio)

El elemento de nombre es una cadena que representa el nombre de la entidad en el documento de esquema. A menudo contiene abreviaturas y debe seguir estas reglas:

• Contiene únicamente caracteres alfanuméricos, puntos (.), barras diagonales (/), guiones (-) y espacios

• Comience con una letra

• Máximo 64 caracteres

El elemento name se utiliza en la documentación y la interfaz de usuario de la consola de Amazon Web Services.

ejemplo Ejemplos de nombres

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

título

El elemento de título es una cadena descriptiva de la entidad representada en el documento de esquema. Puede contener cualquier carácter y se utiliza en la documentación. La longitud máxima del título de una capacidad es de 256 caracteres.

ejemplo Ejemplos de títulos

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

description

El description elemento proporciona una explicación detallada de la entidad representada en el documento de esquema. Puede contener cualquier carácter y se utiliza en la documentación. La longitud máxima de la descripción de una capacidad es de 2048 caracteres

ejemplo Ejemplo de descripción

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.

versión

El elemento version es opcional. Es una cadena que representa la versión del documento de esquema. Se dan las siguientes restricciones:

• Utiliza el formato semver, con los siguientes fragmentos de versión separados por . (puntos).

  • MAJORversión, máximo 3 dígitos

  • MINORversión, máximo 3 dígitos

  • PATCHversión (opcional), máximo 4 dígitos

• La longitud puede oscilar entre 3 y 12 caracteres.

ejemplo Versiones de ejemplo

1.0

1.12

1.4.1

Trabajar con versiones de capacidades

Una capacidad es una entidad versionada inmutable. Se espera que cualquier cambio cree una nueva versión. El sistema utiliza el control de versiones semántico con el formato MAJOR.MINOR.PATCH, donde:

• La versión MAJOR aumenta cuando se realizan cambios en la API incompatibles con versiones anteriores

• La versión MINOR aumenta cuando se añade funcionalidad de forma compatible con versiones anteriores

• La versión PATCH aumenta al realizar pequeñas adiciones no impactantes en la capacidad.

Las capacidades derivadas de los clústeres de Matter se basan en la versión 1.4 y se espera que cada versión de Matter se importe al sistema. Como la versión Matter consume los niveles MAYOR y MENOR de Semver, las integraciones gestionadas solo pueden utilizar las versiones PATCH.

Cuando añadas versiones PATCH para Matter, asegúrate de tener en cuenta que Matter utiliza revisiones secuenciales. Todas las versiones de PATCH deben cumplir con la revisión documentada en la especificación Matter y deben ser compatibles con versiones anteriores.

Para solucionar cualquier problema de incompatibilidad con versiones anteriores, debe trabajar con Connectivity Standards Alliance (CSA) para resolver los problemas de la especificación y publicar una nueva revisión.

AWS-las capacidades gestionadas se publicaron con una versión inicial de. 1.0 Con ellas, se pueden utilizar los tres niveles de versión.

Versión extrínseca (obligatoria)

Se trata de una cadena que representa una versión gestionada fuera del sistema. AWS IoT Para las capacidades de Matter, se extrinsicVersion asigna a revision

Se representa como un valor entero en cadena y la longitud puede ser de 1 a 10 dígitos numéricos.

ejemplo Versiones de ejemplo

7

1567

ExtrinsicID (obligatorio)

El extrinsicId elemento representa un identificador gestionado fuera del sistema Amazon Web Services IoT. En el caso de las capacidades de Matter clusterId attributeIdcommandId, se asigna aeventId,fieldId, o, según el contexto.

extrinsicIdPuede ser un entero decimal en cadena (de 1 a 10 dígitos) o un entero hexadecimal en cadena (prefijo 0x o 0X, seguido de 1 a 8 dígitos hexadecimales).

nota

En el caso de AWS Matter, el identificador de proveedor (VID) es 0x1577 y, en el de Matter, es 0. El sistema garantiza que los esquemas personalizados no utilicen estas capacidades reservadas. VIDs

ejemplo Ejemplo: Extrinsicids

0018
0x001A
0x15771002

$defs

La $defs sección es un mapa de subesquemas al que se puede hacer referencia en el documento de esquema, según lo permita el esquema JSON. En este mapa, la clave se usa en las definiciones de referencia locales y el valor proporciona el esquema JSON.

nota

El sistema solo exige que $defs sea un mapa válido y que cada subesquema sea un esquema JSON válido. No se aplica ninguna regla adicional.

Siga estas restricciones cuando trabaje con definiciones:

• Utilice únicamente caracteres compatibles con el URI en los nombres de las definiciones

• Asegúrese de que cada valor sea un subesquema válido

• Incluya cualquier número de subesquemas que se ajusten a los límites de tamaño del documento de esquema

Propiedades extrínsecas

El extrinsicProperties elemento contiene un conjunto de propiedades definidas en un sistema externo pero mantenidas dentro del modelo de datos. En el caso de las capacidades de Matter, se asigna a diferentes elementos no modelados o parcialmente modelados dentro del clúster, atributo, comando o evento de ZCL.

Las propiedades extrínsecas deben seguir estas restricciones:

• Los nombres de las propiedades deben ser alfanuméricos sin espacios ni caracteres especiales

• Los valores de las propiedades pueden ser cualquier valor del esquema JSON

• Máximo de 20 propiedades

El sistema es compatible con varias extrinsicProperties accessapiMaturity,cli,cliFunctionName, y otras. Estas propiedades facilitan las transformaciones de la ACL a los modelos de datos AWS (y viceversa).

nota

Las propiedades extrínsecas son compatibles con los elementos actionevent,property, y struct campos de una capacidad, pero no con la capacidad o el clúster en sí.

Propiedades

Las propiedades representan los estados de la capacidad gestionados por el dispositivo. Cada estado se define como un par clave-valor, donde la clave describe el nombre del estado y el valor describe la definición del estado.

Cuando trabaje con propiedades, siga estas restricciones:

• Utilice únicamente caracteres alfanuméricos en los nombres de las propiedades, sin espacios ni caracteres especiales

• Incluya cualquier número de propiedades que se ajusten a los límites de tamaño del documento de esquema

Trabajar con propiedades

Una propiedad dentro de una capacidad es un elemento fundamental que representa un estado específico de un dispositivo impulsado por integraciones gestionadas. Representa el estado o la configuración actuales del dispositivo. Al estandarizar la forma en que se definen y estructuran estas propiedades, los sistemas domésticos inteligentes garantizan que los dispositivos de diferentes fabricantes puedan comunicarse de manera efectiva, creando una experiencia fluida e interoperable.

Para una propiedad de capacidad, los elementos obligatorios son extrinsicId y. value Los elementos opcionales de una propiedad de capacidad son description retrievablemutable, reportable yextrinsicProperties.

Valor

Una estructura ilimitada que permite a los creadores establecer cualquier restricción compatible con el esquema JSON para definir el tipo de datos de esta propiedad.

Al definir valores, siga estas restricciones:

• Para tipos simples, utilice type y cualquier otra restricción nativa del esquema JSON, como o maxLength maximum

• Para tipos compuestos, utilice oneOfallOf, o. anyOf El sistema no admite la not palabra clave

• Para hacer referencia a cualquier tipo global, $ref utilícelo con una referencia visible válida

• Para garantizar la nulabilidad, siga la definición del esquema de tipo OpenAPI proporcionando al atributo anulable una marca booleana (si null es un valor permitido) true

Ejemplo:

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

Recuperable

Un booleano que describe si el estado es legible o no.

El aspecto de legibilidad del estado depende de la implementación de la capacidad por parte del dispositivo. El dispositivo decide si un estado determinado es legible o no. Aún no se admite la inclusión de este aspecto del estado en el informe de capacidad y, por lo tanto, no se aplica en el sistema.

Ejemplo: true o false

Mutable

Un booleano que describe si el estado se puede escribir o no.

El aspecto de la capacidad de escritura del estado se transfiere a la implementación de la capacidad por parte del dispositivo. El dispositivo decide si un estado dado es escribible o no. Aún no se admite la inclusión de este aspecto del estado en el informe de capacidad y, por lo tanto, no se aplica en el sistema.

Ejemplo: true o false

Denunciable

Un booleano que describe si el dispositivo informa del estado cuando se produce un cambio en el estado.

El aspecto de reportabilidad del estado se transfiere a la implementación de la capacidad por parte del dispositivo. El dispositivo decide si un estado determinado es notificable o no. Aún no se admite la inclusión de este aspecto del estado en el informe de capacidad y, por lo tanto, no se aplica en el sistema.

Ejemplo: true o false

Acciones

Las acciones son operaciones gestionadas mediante un esquema que siguen un modelo de solicitud-respuesta. Cada acción representa una operación implementada en el dispositivo.

Siga estas restricciones al implementar acciones:

• Incluya solo acciones únicas en la matriz de acciones

• Incluya cualquier número de acciones que se ajusten a los límites de tamaño del documento de esquema

Trabajar con acciones

Una acción es una forma estandarizada de interactuar con las capacidades del dispositivo y de controlarlas en un sistema de integración gestionado. Representa un comando u operación específicos que se pueden ejecutar en un dispositivo, con un formato estructurado para modelar cualquier parámetro de solicitud o respuesta necesario. Estas acciones sirven de puente entre las intenciones del usuario y las operaciones del dispositivo, lo que permite un control uniforme y fiable de los distintos tipos de dispositivos inteligentes.

Para una acción, los elementos obligatorios son name yextrinsicId. Los elementos opcionales son descriptionextrinsicProperties, request yresponse.

Descripción

La descripción tiene una restricción de longitud máxima de 1536 caracteres.

Solicitud

La sección de solicitud es opcional y se puede omitir si no hay parámetros de solicitud. Si se omite, el sistema permite enviar una solicitud sin carga útil con solo usar el nombre de. Action Se utiliza en acciones sencillas, como encender o apagar una luz.

Las acciones complejas necesitan parámetros adicionales. Por ejemplo, una solicitud para transmitir imágenes de cámara puede incluir parámetros sobre el protocolo de transmisión que se debe utilizar o si se debe enviar la transmisión a un dispositivo de visualización específico.

Para una solicitud de acción, el elemento obligatorio esparameters. Los elementos opcionales son descriptionextrinsicId, yextrinsicProperties.

Descripción de la solicitud

La descripción sigue el mismo formato que en la sección 3.5, con una longitud máxima de 2048 caracteres.

Respuesta

En las integraciones gestionadas, para cualquier solicitud de acción enviada a través de la SendManagedThingCommandAPI, la solicitud llega al dispositivo y espera una respuesta asíncrona. La respuesta de acción define la estructura de esta respuesta.

Para una solicitud de acción, el elemento obligatorio esparameters. Los elementos opcionales son namedescription, extrinsicIdextrinsicProperties, errors yresponseCode.

Descripción de la respuesta

La descripción sigue el mismo description formato y tiene una longitud máxima de 2048 caracteres.

Nombre de la respuesta

El nombre tiene el mismo formato quenombre (obligatorio), con los siguientes detalles adicionales:

• El nombre convencional de una respuesta se obtiene agregándolo Response al nombre de la acción.

• Si desea utilizar un nombre diferente, puede proporcionarlo en este name elemento. Si name se proporciona a en la respuesta, este valor tiene mayor prioridad que el nombre convencional.

Errores

Una matriz ilimitada de mensajes únicos proporcionados en la respuesta, si hay errores al procesar la solicitud.

Restricciones:

• Un elemento de mensaje se declara como un objeto JSON con los siguientes campos:

  • code: cadena que contiene caracteres alfanuméricos y _ (guiones bajos), con una longitud entre 1 y 64 caracteres

  • message: un valor de cadena ilimitado

ejemplo Ejemplo de mensaje de error

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

Código de respuesta

Un código entero que muestra cómo se gestionó la solicitud. Se recomienda que el código del dispositivo devuelva un código que utilice la especificación del código de estado de respuesta del servidor HTTP para permitir la uniformidad en el sistema.

Restricción: valor entero comprendido entre 100 y 599.

Parámetros de solicitud o respuesta

La sección de parámetros se define como un mapa de pares de nombres y subesquemas. Se puede definir cualquier número de parámetros dentro de los parámetros de la solicitud, si caben en el documento de esquema.

Los nombres de los parámetros solo pueden contener caracteres alfanuméricos. No se permiten espacios ni ningún otro carácter.

campo de parámetros

Los elementos obligatorios de a parameter son extrinsicId yvalue. Los elementos opcionales son description yextrinsicProperties.

El elemento de descripción sigue el mismo formato quedescription, con una longitud máxima de 1024 caracteres.

extrinsicIdy extrinsicProperties anula

las extrinsicId y extrinsicProperties siguen el mismo formato que ExtrinsicID (obligatorio) yPropiedades extrínsecas, con estos detalles adicionales:

• Si extrinsicId se proporciona una en la solicitud o respuesta, este valor tiene mayor prioridad que el valor proporcionado en el nivel de acción. El sistema debe usar extrinsicId primero el request/response nivel y, si falta, usar el nivel de acción extrinsicId

• Si extrinsicProperties se proporcionan en la solicitud o la respuesta, estas propiedades tienen mayor prioridad que el valor va proporcionado en el nivel de acción. El sistema debe adoptar el nivel de acción extrinsicProperties y reemplazar los pares clave-valor proporcionados en ese nivel request/response extrinsicProperties

ejemplo Ejemplo de anulación de ExtrInsicID y ExtrinsicProperties

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

En el ejemplo anterior, los valores efectivos de la solicitud de acción serían:

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

Acciones integradas

Para todas las funciones, puede realizar acciones personalizadas utilizando las palabras clave ReadState yUpdateState. Estas dos palabras clave de acción actuarán sobre las propiedades de la capacidad definidas en el modelo de datos.

ReadState

Envía un comando a la managedThing para leer los valores de sus propiedades de estado. Se utiliza ReadState como una forma de forzar la actualización del estado del dispositivo.

UpdateState

Envía un comando para actualizar algunas de las propiedades.

Forzar la sincronización del estado de un dispositivo puede resultar útil en los siguientes escenarios:

1. El dispositivo estuvo desconectado durante un período de tiempo y no emitía eventos.

2. El dispositivo se acaba de aprovisionar y aún no se ha mantenido ningún estado en la nube.

3. El estado del dispositivo no está sincronizado con el estado real del dispositivo.

ReadState ejemplos

Comprueba si la luz está encendida o apagada mediante la SendManagedThingCommandAPI:

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

Lea todas las propiedades de estado para ver la matter.OnOff capacidad:

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

Cambia la luz OnTime por una con la SendManagedThingCommandAPI:

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

Eventos

Los eventos son señales unidireccionales gestionadas por un esquema e implementadas por el dispositivo.

Implemente los eventos de acuerdo con estas restricciones:

• Incluya solo eventos únicos en la matriz de eventos

• Incluya cualquier número de eventos que se ajusten a los límites de tamaño del documento de esquema