Esquema para definições de capacidade - Integrações gerenciadas para AWS IoT Device Management
$id (obrigatório)$ refnome (obrigatório)títulodescriptionversionVersão extrínseca (obrigatória)ExtrinsICID (obrigatório)$ defsPropriedades extrínsecasPropriedadesAçõesEventos

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Esquema para definições de capacidade

Um recurso é documentado usando um documento JSON declarativo que fornece um contrato claro de como o recurso deve funcionar no sistema.

Para um recurso, os elementos obrigatórios são $idname,extrinsicId, extrinsicVersion e pelo menos um elemento em pelo menos uma das seções a seguir:

  • properties

  • actions

  • events

Os elementos opcionais em um recurso são $ref titledescription,version,, $defs extrinsicProperties e. Para obter uma capacidade, $ref deve consultar aws.capability a.

As seções a seguir detalham o esquema usado para definições de capacidade.

$id (obrigatório)

O elemento $id identifica a definição do esquema. Ele deve seguir esta estrutura:

  • Comece com o prefixo /schema-versions/ URI

  • Incluir o capability tipo de esquema

  • Use uma barra (/) como separador de caminho de URI

  • Inclua a identidade do esquema, com fragmentos separados por pontos () .

  • Use o @ caractere para separar o ID do esquema e a versão

  • Termine com a versão semver, usando pontos (.) para separar os fragmentos da versão

A identidade do esquema deve começar com um namespace raiz de 3 a 12 caracteres, seguido por um nome e um subnamespace opcionais.

A versão semver inclui uma versão MAJOR (até 3 dígitos), uma versão MINOR (até 3 dígitos) e uma versão PATCH opcional (até 4 dígitos).

nota

Você não pode usar os namespaces aws reservados ou matter

exemplo Exemplo $id
/schema-version/capability/aws.Recording@1.0

$ ref

O $ref elemento faz referência a um recurso existente no sistema. Ele segue as mesmas restrições do $id elemento.

nota

Deve existir uma definição de tipo ou capacidade com o valor fornecido no $ref arquivo.

exemplo Exemplo $ref
/schema-version/definition/aws.capability@1.0

nome (obrigatório)

O elemento name é uma string que representa o nome da entidade no documento do esquema. Geralmente contém abreviações e deve seguir estas regras:

  • Contém somente caracteres alfanuméricos, pontos (.), barras (/), hífens (-) e espaços

  • Comece com uma letra

  • Máximo de 64 caracteres

O elemento name é usado na interface de usuário e na documentação do console da Amazon Web Services.

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

título

O elemento title é uma string descritiva para a entidade representada pelo documento do esquema. Ele pode conter qualquer caractere e é usado na documentação. O tamanho máximo de um título de capacidade é de 256 caracteres.

exemplo Exemplos de títulos
Real-time Communication (RTC) Session Controller
Energy EVSE Capability

description

O description elemento fornece uma explicação detalhada da entidade representada pelo documento do esquema. Ele pode conter qualquer caractere e é usado na documentação. O tamanho máximo para uma descrição de capacidade é de 2.048 caracteres.

exemplo Descrição do exemplo
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

O elemento version é opcional. É uma string que representa a versão do documento do esquema. As seguintes restrições se aplicam:

  • Usa o formato semver, com os seguintes fragmentos de versão separados por . (pontos).

    • MAJORversão, máximo de 3 dígitos

    • MINORversão, máximo de 3 dígitos

    • PATCHversão (opcional), máximo de 4 dígitos

  • O comprimento pode ter entre 3 e 12 caracteres.

exemplo Versões de exemplo
1.0
1.12
1.4.1

Trabalhando com versões de recursos

Um recurso é uma entidade versionada imutável. Espera-se que qualquer alteração crie uma nova versão. O sistema usa versionamento semântico com formato MAJOR.MINOR.PATCH, onde:

  • A versão MAJOR aumenta ao fazer alterações de API incompatíveis com versões anteriores

  • A versão MINOR aumenta ao adicionar funcionalidades de maneira compatível com versões anteriores

  • A versão PATCH aumenta ao fazer pequenas adições não impactantes no recurso.

Os recursos derivados dos clusters do Matter são baseados na versão 1.4 e espera-se que cada versão do Matter seja importada para o sistema. Como a versão Matter consome os níveis MAJOR e MINOR do semver, as integrações gerenciadas só podem usar as versões PATCH.

Ao adicionar versões de PATCH para o Matter, lembre-se de que o Matter usa revisões sequenciais. Todas as versões do PATCH devem estar em conformidade com a revisão documentada na especificação Matter e devem ser compatíveis com versões anteriores.

Para corrigir quaisquer problemas de incompatibilidade com versões anteriores, você deve trabalhar com a Connectivity Standards Alliance (CSA) para resolver os problemas da especificação e lançar uma nova revisão.

AWS-os recursos gerenciados foram lançados com uma versão inicial do1.0. Com eles, todos os três níveis da versão podem ser usados.

Versão extrínseca (obrigatória)

Essa é uma string representando uma versão gerenciada fora do AWS IoT sistema. Para recursos do Matter, extrinsicVersion mapeia para revision

Ele é representado como um valor inteiro em cadeia e o comprimento pode ser de 1 a 10 dígitos numéricos.

exemplo Versões de exemplo
7
1567

ExtrinsICID (obrigatório)

O extrinsicId elemento representa um identificador gerenciado fora do sistema de IoT da Amazon Web Services. Para os recursos do MatterclusterId, ele mapeia para attributeId commandIdeventId,,fieldId, ou, dependendo do contexto.

O extrinsicId pode ser um inteiro decimal em sequência (1 a 10 dígitos) ou um inteiro hexadecimal em sequência (prefixo 0x ou 0X, seguido por 1 a 8 dígitos hexadecimais).

nota

Para AWS, o ID do fornecedor (VID) é 0x1577 e, para o Matter, é 0. O sistema garante que os esquemas personalizados não os usem reservados VIDs para recursos.

exemplo Exemplo de extrinsicidas
0018
0x001A
0x15771002

$ defs

A $defs seção é um mapa de subesquemas que podem ser referenciados no documento do esquema, conforme permitido pelo esquema JSON. Nesse mapa, a chave é usada nas definições de referência locais e o valor fornece o esquema JSON.

nota

O sistema apenas impõe que $defs seja um mapa válido e que cada subesquema seja um esquema JSON válido. Nenhuma regra adicional é aplicada.

Siga estas restrições ao trabalhar com definições:

  • Use somente caracteres compatíveis com URI em nomes de definição

  • Certifique-se de que cada valor seja um subesquema válido

  • Inclua qualquer número de subesquemas que se encaixem nos limites de tamanho do documento do esquema

Propriedades extrínsecas

O extrinsicProperties elemento contém um conjunto de propriedades definidas em um sistema externo, mas mantidas dentro do modelo de dados. Para os recursos do Matter, ele mapeia para diferentes elementos não modelados ou parcialmente modelados dentro do cluster, atributo, comando ou evento ZCL.

As propriedades extrínsecas devem seguir estas restrições:

  • Os nomes das propriedades devem ser alfanuméricos, sem espaços ou caracteres especiais

  • Os valores das propriedades podem ser qualquer valor do esquema JSON

  • Máximo de 20 propriedades

O sistema oferece suporte a vários extrinsicPropertiesaccess, incluindoapiMaturity,cli,cliFunctionName, e outros. Essas propriedades facilitam a ACL para AWS (e vice-versa) as transformações do modelo de dados.

nota

As propriedades extrínsecas são suportadas para os elementos actionevent,property, e struct fields de um recurso, mas não para o recurso ou cluster em si.

Propriedades

As propriedades representam os estados do recurso gerenciados pelo dispositivo. Cada estado é definido como um par de valores-chave, em que a chave descreve o nome do estado e o valor descreve a definição do estado.

Ao trabalhar com propriedades, siga estas restrições:

  • Use somente caracteres alfanuméricos nos nomes das propriedades, sem espaços ou caracteres especiais

  • Inclua qualquer número de propriedades que se encaixem nos limites de tamanho do documento do esquema

Trabalhando com propriedades

Uma propriedade dentro de um recurso é um elemento fundamental que representa um estado específico de um dispositivo alimentado por integrações gerenciadas. Ela representa a condição ou configuração atual do dispositivo. Ao padronizar a forma como essas propriedades são definidas e estruturadas, os sistemas domésticos inteligentes garantem que dispositivos de diferentes fabricantes possam se comunicar de forma eficaz, criando uma experiência perfeita e interoperável.

Para uma propriedade de capacidade, os elementos obrigatórios são extrinsicId value e. Os elementos opcionais em uma propriedade de capacidade são description retrievablemutable,, reportable extrinsicProperties e.

Valor

Uma estrutura ilimitada que permite que os construtores coloquem qualquer restrição compatível com o esquema JSON para definir o tipo de dados dessa propriedade.

Ao definir valores, siga estas restrições:

  • Para tipos simples, use type e quaisquer outras restrições nativas do esquema JSON, como ou maxLength maximum

  • Para tipos compostos, use oneOfallOf, ouanyOf. O sistema não suporta a not palavra-chave

  • Para se referir a qualquer tipo global, use $ref com uma referência detectável válida

  • Para a nulidade, siga a definição do esquema do tipo OpenAPI fornecendo ao atributo anulável um sinalizador booleano (se nulo for um valor permitido) true

Exemplo:

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

Recuperável

Um booleano que descreve se o estado é legível ou não.

O aspecto de legibilidade do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é legível ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema.

Exemplo: true ou false

Mutable

Um booleano que descreve se o estado é gravável ou não.

O aspecto de capacidade de gravação do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é gravável ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema.

Exemplo: true ou false

Reportável

Um booleano que descreve se o estado é relatado pelo dispositivo quando há uma mudança no estado.

O aspecto de reportabilidade do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é reportável ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema.

Exemplo: true ou false

Ações

As ações são operações gerenciadas pelo esquema que seguem um modelo de solicitação-resposta. Cada ação representa uma operação implementada pelo dispositivo.

Siga estas restrições ao implementar ações:

  • Incluir somente ações exclusivas na matriz de ações

  • Inclua qualquer número de ações que se encaixem nos limites de tamanho do documento do esquema

Trabalhar com ações

Uma ação é uma forma padronizada de interagir e controlar os recursos do dispositivo em um sistema de integração gerenciado. Ele representa um comando ou operação específica que pode ser executada em um dispositivo, com um formato estruturado para modelar quaisquer parâmetros de solicitação ou resposta necessários. Essas ações servem como ponte entre as intenções do usuário e as operações do dispositivo, permitindo um controle consistente e confiável em diferentes tipos de dispositivos inteligentes.

Para uma ação, os elementos obrigatórios são name extrinsicId e. Os elementos opcionais são descriptionextrinsicProperties, request response e.

Descrição

A descrição tem uma restrição de tamanho máximo de 1536 caracteres.

Solicitação

A seção de solicitação é opcional e pode ser omitida se não houver parâmetros de solicitação. Se omitido, o sistema suporta o envio de uma solicitação sem qualquer carga usando apenas o nome de. Action Isso é usado em ações simples, como acender ou apagar uma luz.

As ações complexas precisam de parâmetros adicionais. Por exemplo, uma solicitação para transmitir imagens da câmera pode incluir parâmetros sobre o protocolo de streaming a ser usado ou se o stream deve ser enviado para um dispositivo de exibição específico.

Para uma solicitação de ação, o elemento obrigatório éparameters. Os elementos opcionais são descriptionextrinsicId, extrinsicProperties e.

Descrição da solicitação

A descrição segue o mesmo formato da seção 3.5, com um tamanho máximo de 2048 caracteres.

Resposta

Nas integrações gerenciadas, para qualquer solicitação de ação enviada pela SendManagedThingCommandAPI, a solicitação chega ao dispositivo e espera uma resposta assíncrona. A resposta da ação define a estrutura dessa resposta.

Para uma solicitação de ação, o elemento obrigatório éparameters. Os elementos opcionais são name descriptionextrinsicId,extrinsicProperties,, errors responseCode e.

Descrição da resposta

A descrição segue o mesmo formato e tem um tamanho máximo de 2048 caracteres. description

Nome da resposta

O nome segue o mesmo formato denome (obrigatório), com esses detalhes adicionais:

  • O nome convencional de uma resposta é derivado do acréscimo Response ao nome da ação.

  • Se quiser usar um nome diferente, você pode fornecê-lo nesse name elemento. Se a name for fornecido na resposta, esse valor terá maior precedência do que o nome convencional.

Erros

Uma matriz ilimitada de mensagens exclusivas fornecidas na resposta, se houver erros durante o processamento da solicitação.

Restrições:

  • Um item de mensagem é declarado como um objeto JSON com os seguintes campos:

    • code: uma sequência de caracteres contendo caracteres alfanuméricos e _ (sublinhados), com um comprimento entre 1 e 64 caracteres

    • message: um valor de string ilimitado

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

Código de resposta

Um código inteiro mostrando como a solicitação foi tratada. Recomendamos que o código do dispositivo retorne um código usando a especificação do código de status de resposta do servidor HTTP para permitir uniformidade no sistema.

Restrição: um valor inteiro que varia de 100 a 599.

Parâmetros de solicitação ou resposta

A seção de parâmetros é definida como um mapa de pares de nomes e subesquemas. Qualquer número de parâmetros pode ser definido nos parâmetros da solicitação, se eles couberem no documento do esquema.

Os nomes dos parâmetros só podem conter caracteres alfanuméricos. Espaços ou quaisquer outros caracteres não são permitidos.

campo de parâmetros

Os elementos obrigatórios em um parameter são extrinsicId value e. Os elementos opcionais são description extrinsicProperties e.

O elemento de descrição segue o mesmo formato quedescription, com um comprimento máximo de 1024 caracteres.

extrinsicIde extrinsicProperties substituições

o extrinsicId e extrinsicProperties segue o mesmo formato de ExtrinsICID (obrigatório) ePropriedades extrínsecas, com esses detalhes adicionais:

  • Se um extrinsicId for fornecido na solicitação ou resposta, esse valor terá maior precedência do que o valor fornecido no nível da ação. O sistema deve usar o request/response nível extrinsicId primeiro, se estiver faltando, use o nível de ação extrinsicId

  • Se extrinsicProperties forem fornecidas na solicitação ou resposta, essas propriedades terão maior precedência do que o valor va fornecido no nível da ação. O sistema deve assumir o nível de ação extrinsicProperties e substituir os pares de valores-chave fornecidos no nível request/response extrinsicProperties

exemplo Exemplo de substituição de extrinsicId e extrinsicProperties
{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

No exemplo acima, os valores efetivos para a solicitação de ação seriam:

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

Ações integradas

Para todos os recursos, você pode realizar ações personalizadas usando as palavras-chave ReadState UpdateState e. Essas duas palavras-chave de ação atuarão nas propriedades do recurso definidas no modelo de dados.

ReadState

Envia um comando para o managedThing para ler os valores de suas propriedades de estado. Use ReadState como forma de forçar a atualização do estado do dispositivo.

UpdateState

Envia um comando para atualizar algumas das propriedades.

Forçar a sincronização do estado do dispositivo pode ser útil nos seguintes cenários:

  1. O dispositivo ficou off-line por um período de tempo e não estava emitindo eventos.

  2. O dispositivo acabou de ser provisionado e ainda não tem nenhum estado mantido na nuvem.

  3. O estado do dispositivo está fora de sincronia com o estado real do dispositivo.

ReadState exemplos

Verifique se a luz está acesa ou apagada usando a SendManagedThingCommandAPI:

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

Leia todas as propriedades do estado do matter.OnOff recurso:

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

Altere o OnTime por uma luz usando a SendManagedThingCommandAPI:

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

Eventos

Os eventos são sinais unidirecionais gerenciados pelo esquema implementados pelo dispositivo.

Implemente eventos de acordo com essas restrições:

  • Inclua somente eventos exclusivos na matriz de eventos

  • Inclua qualquer número de eventos que se encaixem nos limites de tamanho do documento do esquema