O que é o processo de inicialização?

O processo de inicialização (bootstrap process),é responsável por conectar o Gateway com o Central Management Software ou "CMS", neste caso, o IoTHub. O gateway é um dispositivo que atua como uma ponte entre o CMS e os dispositivos da rede, "traduzindo" as informações que os dispositivos enviam para o CMS e vice-versa, o que garante a interoperabilidade entre diferentes dispositivos.

De forma simples podemos descrever o processo de inicialização em algumas etapas:

Pré-requisitos de segurança: o gateway deve ter acesso ao endereço do CMS (cmsUri) e as chaves de segurança adequadas. Para estabelecer uma troca de informações segura na rede, é usado o protocolo TLS (Transport Layer Security) de segurança, protocolo que criptografa dados e autentica rotas de conexão. Para mais informações acesse: "API TALQ - Autenticação e Proteção de Rotas"

Anúncio do Gateway: nesta primeira etapa, o gateway anuncia sua presença e suas capacidades ao CMS. Em resposta, o CMS fornece um endereço TALQ exclusivo, que será utilizado para a troca de dados;

Anúncio de Serviços: após o anúncio do gateway o mesmo envia uma lista dos serviços TALQ que ele suporta, com suas respectivas opções. Essa etapa permite ao CMS definir como irá configurar, controlar, comandar e monitorar os dispositivos na rede operacional do gateway;

Anúncio de Classe de Dispositivo: por fim, o gateway envia a lista de classes de dispositivos que suporta, junto com a descrição de suas funções e atributos. Com isso, o CMS alinha a forma de gerenciar os dispositivos na rede do gateway.

Importante notar, que durante o processo de inicialização, o gateway não deve enviar nenhuma informação além das especificadas no processo de inicialização. Qualquer outra solicitação não relacionada, enviada pelo gateway, será rejeitada pelo CMS com o código HTTP 403.

O suporte de um gateway para mais de um CMS é opcional, e caso ocorra, antes da inicialização atual, se houverem outros CMS previamente conectados, o gateway deve sinalizar aos mesmos que houve conexão com outro CMS.

A seção seguinte desta documentação visa detalhar tecnicamente o processo de inicilização.

Detalhes técnicos

Anúncio do Gateway

Estabelecida uma conexão segura através do protocolo TLS, o gateway deve enviar as seguintes requisições ao CMS.

POST para /devices

O gateway se apresenta ao CMS enviando uma requisição que deve conter um payload JSON contendo o gatewayUri dentro da função GatewayFunction.
Embora nenhuma classe de dispositivo tenha sido anunciada ainda, entende-se implicitamente que esta GatewayFunction é obrigatória e, portanto, é esperada no dispositivo que representa o gateway. Outras funções podem ser incluídas nesta primeira etapa.
Então ao receber a requisição, se bem sucedida, o CMS cria um endereço único gatewayAdress e envia junto do seu endereço cmsAdress como payload JSON de sua resposta a requisição.
Ambos os endereços devem ser um UUID válido (não nulo).

POST para /device-classes?clientAddress=<gatewayAddress>

Após receber os endereços, o gateway envia as capacidades e lista de atributos que o dispositivo do gateway suporta.

PATCH para /devices/<gatewayAddress>?clientAddress=<gatewayAddress>

O gateway então envia os valores de cada atributo da GatewayFunction para o dispositivo que a está implementado. Essa requisição deve incluir o atributo gatewayUri dentro da função GatewayFunction, para que o CMS saiba para onde enviar as requisições.

PATCH /devices/<gatewayAddress>?clientAddress=<cmsAddress>

A última etapa deste processo, é uma requisição do CMS, de forma a definir ou atualizar qualquer atributo de configuração no dispositivo que implementa a função do gateway, GatewayFunction. A requisição deve incluir o endereço TALQ do CMS.

Anúncio de Serviços

O gateway anuncia a lista de serviços e opções de serviço TALQ que suporta através da requisição POST para o endpoint /services?clientAddress=<gatewayAddress>. O clientAddress é o UUID gerado na etapa anterior.

Segue exemplo da requisição:

Request URL: https://<cmsUri>/services?clientAddress=110a8321-e34c-112p5-b567-566655648453
Request Method: POST
Status Code: "201 OK"
Request Header: {
 “talq-api-version”: “2.6.0”,
}
Request Content: [
 {
     "name": "ControlService",
     "maximumCalendars": 100,
     "maximumPrograms": 300,
     "maxProgramsPerCalendar": 30,
     "maxSwitchPointsPerProgram": 10,
     "dayOffset": 0,
     …
 },
 {
     "name": "groupManagementService",
     "maximumNumberOfGroups": 20,
     "maximumGroupSize": 40
 },
 …
]

Veja que cada objeto JSON do conteúdo da requisição, representa um serviço TALQ.

Anúncio de Classe de Dispositivo

O gateway deve então, anunciar a lista de classes de dispositivo, junto de funções e atributos que as classes devem suportar. Isto é feito enviando uma requisição POST para o endpoint /device-classes?clientAddress=<gatewayAddress>. Se tudo der certo o CMS valida os dados e responde com HTTP 201 Created.
Se o gateway não tiver mais classes para anunciar, ele deve enviar uma lista vazia para informar que o processo inicialização terminou.

Segue exemplo de requisição:

Request URL: https://<cmsUri>/device-classes?clientAddress=110a8321-e34c-112p5-b567-566655648453
Request Method: POST
Status Code: "201 OK"
Request Header: {
 “talq-api-version”: “2.6.0”,
}
Request Content: [
 {
     "name": "<deviceClassName>"
     "functions": [
      {
         "name": "BasicFunction",
         "attributes":[
         {
         "name": "displayName"
         },
         {
         "name": "assetId"
         },
         …
         ]
     },
 {
     "name": "LampActuatorFunction",
     "attributes":[
         {
         "name": "lampTypeId"
         },
         {
         "name": "maintenanceFactor",
         "minValue": 0
         "maxValue": 100
         },
         {
         "name": "maintenancePeriod",
         "unit": "Hours"
         },
         …
     ]
    }
  ]
 },
 …
]

Importante notar que, o gateway pode vir a adicionar funções e atributos a uma classe de dispositivo mesmo depois de ter sido anunciada, mas nunca deve reduzir o escopo de uma classe de dispositivo (como remover um atributo) depois de ser anunciada. Se necessário, por exemplo, remover um atributo, o gateway deve anunciar essa mudança na classe de dispositivo como uma nova classe de dispositivo ao CMS.
Se por algum motivo um dispositivo mudar sua classe de dispositivo, a API permite essa mudança enviando uma requisição PATCH/PUT ao CMS.

Referências

"TALQ Specification 2.6.1" Disponível em:
https://github.com/TALQ-consortium/TALQ_specification. Acesso em: 13 mar. 2025

Processo de Inicialização - Bootstrap Process

O que é o processo de inicialização?#

Detalhes técnicos#

Anúncio do Gateway#

Anúncio de Serviços#