TC-IOT M2M CORE Services Protocol Manual de utilização Version: 1.0 Date:
Nome do Documento: TC-IOT M2M CORE Services Protocol - Manual de utilização Versão: 1.0 Data: Identificador: TC_IOT_M2M_CORE_Protocol_User_Manual_PT_v1.0 Conteúdo 1. Introdução... 3 2. O que é o TC-IoT CORE... 4 3. Mensagens do M2M CORE Services Protocol... 4 4. Métodos... 6 5. Query - Pesquisa de eventos... 9 6. Extra... 13 7. Referências... 14 2 de 14
1. Introdução Este documento apresenta uma descrição geral do M2M Core Services Protocol do componente Router (TC-IoT CORE) da TC M2M Cloud Platform (TC-IoT) desenvolvida pela Thought Creator. Pretende-se com este documento descrever e ilustrar a forma de utilização do Protocolo. Para clarificar os termos utilizados neste documento apresenta-se um resumo dos termos chave que irão ser utilizados. Termo Cliente Router Gateway (Adapter) Terminal Subscrição Feed Descrição Utilizador ou Aplicação que recebe e envia informação para o terminal. Corresponde ao componente TC-IoT CORE, responsável pela distribuição e armazenamento de eventos provenientes dos terminais M2M Componente de software responsável por converter a comunicação feita, através de protocolos específicos dos terminais M2M num protocolo de comunicação perceptível pelos Clientes e pelo Router Equipamento electrónico M2M com capacidade de interligação com outros equipamentos, e/ou sensores e com capacidade de comunicação com o Gateway. Ato de subscrever um Terminal no sistema. A subscrição, por parte de um cliente, de um Terminal ativa a recepção automática em tempo real de todos os eventos do mesmo. Mensagem assíncrona originada num terminal que é enviada para todos os Clientes que o subscrevem. Tipicamente correspondem a alterações de estado dos Terminais ou dos sensores. 3 de 14
2. O que é o TC-IoT CORE O TC-IoT CORE apresenta-se na solução da plataforma TC M2M Cloud Platform (TC-IoT) como a principal componente, sendo responsável pela distribuição e armazenamento de eventos provenientes dos terminais M2M. O TC-IoT CORE é um sistema de encaminhamento de mensagens de alto desempenho para todo tráfego entre Terminais/Gateways e aplicações (Clientes), responsável por replicar e armazenar as mensagens dos Terminais subscritos, bem como por toda a componente de autorização de acesso aos Terminais. Pode ser equiparado a um híbrido entre um router tradicional para distribuição de mensagens e um Directório de Recursos, ou seja, um repositório para registos (subscrições) e para consulta de mensagens e eventos passados desses recursos. Numa perspectiva de Serviços, o TC-IoT CORE funciona como um servidor Web, acessível através de um Web Browser ou de aplicações que comuniquem usando protocolo HTTP [1]. O TC-IoT CORE, ou seja, o componente Router, interliga de um lado os Clientes (aplicações M2M) que consomem a informação e podem produzir acções sobre os Terminais, aos Gateways, que consistem em aplicações (Adapter) que realizam a tradução dos protocolos M2M de baixo nível específicos dos Terminais, para a linguagem standard do M2M Core Services Protocol. Domínio de Rede Domínio de Adaptação Domínio Terminal App App App App App Serviços Aplicacionais M2M M2M CORE Services Protocol Mensagens específicas de Terminal M2M Adaptador M2M Terminal Redes de Acesso Adaptador M2M Terminal Directório Recursos Camada Aplicação Camada API IoT CORE (Cloud) IP, 2G/GRPS, 3G/HSPA Camada Agente O M2M Core Services Protocol é um protocolo de comunicações orientado a recursos e baseado em eventos, usando um paradigma RESTful [2] sobre HTTP, ou transporte em WebSocket [3] para comunicação tempo-real bidireccional de informação dos Terminais. O protocolo codifica os pedidos e respostas (mensagens trocadas entre Gateway, Router e Cliente) usando JSON [4,5], um formato de simples interpretação e leitura, amplamente suportado pelas diversas linguagens de programação e bases de dados. Esta arquitectura do M2M CORE Services Protocol torna-o altamente escalável, pela utilização sobre as infra-estruturas e implementações existentes que tenham por base o protocolo HTTP. 3. Mensagens do M2M CORE Services Protocol O M2M Core Services Protocol define dois tipos distintos de mensagens: as mensagens de informação, as mensagens de terminal e as mensagens de controlo. As mensagens de controlo estão associadas a comandos de resposta rápida, tais como subscrições e registos. As mensagens de terminal são tipicamente utilizadas para comandos de acção e pedidos de informação entre Cliente e Terminal e na pesquisa de informação acerca de Terminais no Directório de Recursos. 4 de 14
Mensagem de Controlo A mensagem de controlo serve para informar o Cliente do resultado de uma determinada operação, e consiste num objecto JSON formado pelos campos message e status. O campo message indica o resultado da operação ou o erro ocorrido, num formato de texto (string) alfanumérico. O campo status indica se a operação foi ou não bem sucedida e assume tipicamente um dos dois valores, 1 ou -1. O status com valor 1 indica que a operação foi realizada com sucesso. No caso do valor ser -1 indica que não foi possível executar a operação, tal como se exemplifica: "message": "status": "NO_PERMISSION", - 1 Mensagens de Terminal Uma mensagem de terminal pode conter um ou mais objetos JSON. Não existe limitação no conteúdo destas mensagens, apenas que devem conter obrigatoriamente os campos src, dst e timestamp. "src": "1234567", "dst": "1234567", "timestamp": 1388859768 O campo src deve indicar, no caso de uma mensagem enviada por um Cliente para um Terminal, o nome de utilizador desse Cliente (o utilizador autorizado a aceder ao Terminal). No caso de ser uma mensagem proveniente de um Terminal o campo src deve conter o identificador de Terminal. No campo dst deve estar definido o endereço de destino da mensagem. No caso de se tratar de um feed proveniente de um Terminal os campos src e dst serão iguais e correspondem ao identificador do Terminal. Os valores dos campos src e dst têm o formato texto (string) alfanumérico. O campo timestamp deve indicar a Era POSIX (Unix Timestamp) representativa da data do momento em que a mensagem foi criada, num formato numérico inteiro. Mensagens de Informação Uma mensagem de informação serve para obter listas de identificadores de Terminais conhecidos pelo CORE. As respostas são no formato vetor JSON. 5 de 14
4. Métodos Estão disponíveis diversos métodos (servlets) para interação com o TC-IoT CORE (componente Router). Estes métodos permitem a recepção de mensagens, a gestão de subscrições, leitura/ alteração de estados, etc. Todos os pedidos devem ser feitos usando o protocolo HTTP. Opcionalmente, para a recepção e envio de mensagens em tempo-real de/para os Terminais subscritos, pode ser utilizado WebSockets [3] ou HTTP Long Polling. Todos os pedidos requerem autenticação Básica de HTTP com as credenciais fornecidas pela Thought Creator A generalidade dos métodos disponíveis no Router funcionam numa perspectiva de pedidoresposta. A recepção de mensagens relacionada com a informação dos Terminais subscritos, é enviada para o Cliente, sempre que possível em tempo-real. Caso o Cliente não esteja online as mensagens são armazenadas temporariamente na plataforma TC-IoT e entregues a posteriori. Não se garante o armazenamento de mensagens durante longos períodos, pelo que é aconselhável que as aplicações estejam sempre ligadas à TC-IoT ou que cancelem as subscrições sempre que estas deixem de ser necessárias. Na seguinte Tabela descrevem-se os Métodos e Recursos suportados pelo Router, assim como o formato/sintaxe em que devem ser usados e as entidades que os podem usar. Apesar de disponíveis, não é aconselhada a utilização dos métodos assinalados com (**) por apresentarem menor performance e maior overhead nas comunicações. URI do Recurso - Método - Mensagem - pedido e/ou Entidade Descrição /index HTTP GET CONTROLO Todas Retorna a informação disponível na TC-IoT. /subscribe_terminal/<id> HTTP GET CONTROLO Cliente Subscreve o Terminal com o ID indicado. Retorna uma mensagem de controlo com o resultado da operação e, em caso de erro, o código de erro. /unsubscribe_terminal/ <ID> HTTP GET CONTROLO Cliente Remove a subscrição do Terminal com o ID indicado. Retorna uma mensagem de controlo com o resultado da operação e, em caso de erro, o código de erro. (**) /read_messages HTTP GET TERMINAL Todas Obtém a mensagem mais antiga guardada na TC-IoT. Caso não existam mensagens guardadas, a sessão HTTP mantém-se em aberto durante 30 segundos à espera de nova mensagem. Quando a sessão expirar é recebida uma mensagem de controlo com o timeout (Code 408). 6 de 14
URI do Recurso - Método - Mensagem - pedido e/ou Entidade Descrição (**) /message/<id> HTTP POST CONTROLO pedido Todas Envia a mensagem no corpo do pedido POST para o Cliente ou Terminal com o ID indicado. Retorna uma mensagem de controlo com o resultado da operação. O parâmetro ID no pedido é opcional uma vez que o conteúdo da mensagem deve conter o identificador do destinatário. /get_allowed HTTP GET INFORMAÇÃO [Vetor de IDs] Cliente Retorna a lista de Terminais aos quais o Cliente pode aceder, num formato vetor JSON. /get_subscriptions HTTP GET INFORMAÇÃO [Vetor de IDs] Cliente Retorna a lista de Terminais que o Cliente tem subscritos, num formato vetor JSON. /query HTTP POST TERMINAL pedido [Vetor de mensagens] Todas Questiona a TC-IoT através de uma query para informação sobre um determinado conjunto de Terminais. (Ver exemplo na secção 5) /messages WEBSOCKET Fluxo de MENSAGENS TERMINAL Todas Canal bidireccional de envio de mensagens entre o CORE e o Cliente/Gateway. No sentido Router -> Cliente são enviadas as mensagens dos terminais que o Cliente subscreveu. No sentido Cliente -> Terminal são enviadas as mensagens que o Cliente deseja enviar para os Terminais. Neste método apenas podem ser trocadas mensagens de terminal. (Ver secção 3) /register_terminal/<id> HTTP POST CONTROLO pedido Gateway Este método permite efectuar o registo de um Terminal no CORE. O corpo do POST deve conter a mensagem para o registo do Terminal. Este método retorna uma mensagem de controlo. /unregister_terminal/<id> HTTP GET CONTROLO Gateway Este método permite remover o registo de um Terminal no CORE. Este método retorna uma mensagem de controlo. 7 de 14
Respostas em Mensagens de Controlo A tabela seguinte descreve as respostas contidas no campo message e os correspondentes valores do campo status, para os comandos em que a resposta é uma mensagem de controlo: Mensagem Status Descrição NO_PERMISSION -1 Mensagem enviada sempre que não existam permissões para efetuar determinada operação, como por exemplo subscrever um Terminal não permitido. NOT_FOUND -1 Terminal não encontrado. Esta mensagem é recebida, por exemplo, quando um Terminal ou um Cliente não existem no sistema. OK 1 Quando a operação foi efetuada com sucesso ou a mensagem foi enviada. SUBSCRIBED, UNSUBSCRIBED, ALREADY SUBSCRIBED REGISTERED UNREGISTERED 1 Mensagens de sucesso para a subscrição de Terminais. 1 Mensagem de sucesso para o registo de Terminais. (Apenas para conta de Gateway) BROADCAST_SENT 1 Mensagem de feed enviada. (Apenas para conta de Gateway) MESSAGE_SENT 1 Mensagem enviada com sucesso para Cliente ou Terminal. MESSAGE_ERROR -1 Situação de erro sempre que não seja possível enviar mensagens para um Terminal ou para um Cliente. TIMEOUT_READING_MESSAGES 1 Mensagem recebida no comando /read_messages caso não existam novas mensagens num intervalo de 30 segundos. Respostas em Vetor No caso das mensagens de informação, a resposta em JSON é um vetor com a lista de identificadores dos Terminais, tal como se apresenta no exemplo seguinte: [123, 124, 1235] No caso das mensagens de terminal com método HTTP POST, como é o caso do comando / query a resposta em JSON será um vetor de mensagens de terminal. 8 de 14
Respostas HTTP Em paralelo com o conteúdo enviado pela mensagem de controlo é possível através do cabeçalho de resposta HTTP obter alguma informação sobre o sucesso da operação, como se apresenta na tabela seguinte. Código e Frase de Resposta HTTP Descrição 200 OK Comando realizado com sucesso. 403 Forbidden Sem permissão para aceder ao recurso ou sem permissão para aceder ao Terminal em questão. 404 Not Found Recurso não disponível. 401 Authorization Required Falha de autenticação no pedido HTTP. 500 Internal Server Error Esta mensagem poderá surgir sempre que a operação não possa ser concluída do lado do CORE. 408 Request Timeout Timeout no pedido de /read_messages. O corpo da resposta é uma mensagem de controlo com o campo message de valor TIMEOUT_READING_MESSAGES. 5. Query - Pesquisa de eventos Uma das características do M2M Core Services Protocol é que todas as mensagens que não sejam mensagem de controlo ficam armazenadas de forma persistente na plataforma TC-IoT tornando possível em qualquer momento efetuar consultas usando o comando /query. Nesta secção indica-se a sintaxe genérica utilizada para consulta dos campos e parâmetros contidos nas mensagens armazenadas na Plataforma TC-IoT, dado que o conteúdo dessas mensagens difere consoante o tipo e modelo do Terminal. Os detalhes dos campos e parâmetros das mensagens de cada modelo de Terminal, estão descritos em documentos apropriados, disponíveis no website da Thought Creator. Todas as pesquisas são feitas através do servlet /query e são enviadas para a plataforma TC-IoT usando um método HTTP POST cujo conteúdo (corpo do pedido) é uma query em formato JSON. Em reposta, a plataforma TC-IoT responde com um vetor (array) com todas as mensagens que correspondem à pesquisa efetuada. Os tempos de resposta diferem consoante a complexidade da query e a quantidade de dados envolvidos. Um exemplo de pedido /query é o seguinte: POST /query HTTP/1.1 Host: example.com Accept: application/json Content- Type: application/json Content- Length: 96 "src": "123456", "analog.value": $lt: 5 9 de 14
O exemplo de resposta ao pedido /query é o seguinte (retornou um vetor vazio): HTTP/1.1 200 OK Content- Type: application/json Content- Length: 2 [] Resposta em Vetor A TC-IoT retorna sempre o conjunto de mensagens que corresponde ao critério apresentado. Um exemplo de resposta, onde o critério de pesquisa retorna duas mensagens relativas a portos analógicos do Terminal, é o seguinte: [ ], "analog": "port": 3, "value": 9.968519071116713, "src": "1234567", "dst": "1234567", "timestamp": 1389815505 "analog": "port": 3, "value": 9.967189654342079, "src": "1234567", "dst": "1234567", "timestamp": 1389816242 Query não específica Os pedidos de procura na TC-IoT devem ser objetos JSON válidos contendo todas as condições que devem estar presentes nas respostas. Em pedidos de procura em que a query seja um objeto JSON vazio (não específico), serão devolvidas em resposta todas as mensagens existentes na base de dados: 10 de 14
Condições de pesquisa e filtragem As respostas a uma pesquisa podem ser filtradas tanto pelo identificador do Terminal como por qualquer outro conjunto de campos identificativos da mensagem. Para pesquisar mensagens que contenham um ou mais critérios, estes deverão ser indicados no conteúdo da query. Um exemplo com apenas um critério de pesquisa, em que serão retornadas todas as mensagens provenientes do terminal 123456, é o seguinte: "src": "123456" Num outro exemplo, dois campos são combinados para limitar a pesquisa. Tal é o caso de uma pesquisa por mensagens analógicas da porta 3 do Terminal 123456, onde se filtram apenas as mensagens com informação dessa porta: "src": "123456", "analog.port": 3 Caso fosse omitido o campo src seriam obtidas todas as mensagens analógicas da porta 3 independentemente do terminal em questão. Algumas das condições genéricas para pesquisa de mensagens são as seguintes: $lt e $gt As condições $gt (maior que / greater than), $lt (menor que / less than), permitem filtrar mensagens que contenham determinado campo cujo valor seja maior que ou menor que um determinado valor numérico. No exemplo seguinte pretendem-se obter todas as mensagens do Terminal 123456 com valores em porta analógica menor que 5: "src": "123456", "analog.value": $lt: 5 11 de 14
O mesmo mas para valores superiores a 9.94: "src": "123456", "analog.value": $gt: 9.94 $or A condição $or permite efectuar uma pesquisa sobre mensagens que reunam pelo menos uma das condições impostas. No exemplo seguinte a query conjuga os dois filtros exemplificados anteriormente: "src": ], "1234567", $or: [ "analog.value": $gt: 9.94 "analog.value": $lt: 5 $ne A condição $ne (não igual / not-equal) permite pesquisar por campos que não tenham um determinado valor. "timestamp": $ne: 0 $exists A condição $exists permite obter mensagens que contenham um determinado campo. Como exemplo, para se obterem todas as mensagens que contenham o campo GPIO, a query a executar seria a seguinte: "gpio": $exists: true 12 de 14
6. Extra Neste capitulo são apresentadas algumas informações complementares e sugestões de implementação. Subscrições Para aplicações que não estejam constantemente online é aconselhável remover a subscrição dos Terminais antes que as aplicações sejam colocadas em offline. Desta forma evita-se a acumulação de mensagens na plataforma TC-IoT enquanto as aplicações não estiverem ligadas. Receção de mensagens em tempo-real A receção de mensagens em tempo-real pode ser feita através de WebSockets ou de HTTP Long Polling. Recomenda-se preferencialmente o mecanismo WebSocket e, neste caso o Cliente deve apenas manter uma sessão HTTP de WebSocket com a plataforma TC-IoT. No caso de se utilizar o HTTP Long Polling é necessário ter atenção aos tempos de timeout. Aconselha-se sempre a realizar um novo pedido por cada mensagem recebida. Websockets A comunicação via WebSockets deve respeitar a implementação descrita no RFC 6455 [3]. Os WebSockets suportam comunicação bidirecional e full-duplex através de ligações persistentes. Uma ligação WebSocket é estabelecida através de HTTP que é então atualizado sem afetar a ligação original, funcionando com infra-estruturas de rede existentes, incluindo firewalls e proxies. Para estabelecer uma ligação WebSocket, o lado cliente envia um WebSocket handshake, para que lado o servidor retorne uma resposta WebSocket ao handshake, como no exemplo a seguir: GET /websock/proto/msg HTTP/1.1 Connection: Upgrade Upgrade: websocket Sec- WebSocket- Protocol: chat, better- chat Sec- WebSocket- Key: 50cLrugr7h3yAbe5Kpc52Q== Sec- WebSocket- Version: 13 Origin: http://example.com HTTP/1.1 101 Switching Protocols Connection: Upgrade Upgrade: WebSocket Sec- WebSocket- Accept: 58ij/Yod1NTjzqcyjkZbZk6V6v0= Sec- WebSocket- Protocol: chat Logo que a ligação fique estabelecida, o cliente e o servidor podem enviar tramas de texto WebSocket em ambos os sentidos, no modo full-duplex. Para manter o canal de comunicações vivo, é necessário enviar mensagens regularmente para indicar que o canal ainda está a ser usado. As mensagens PING/PONG do WebSockets não constituem tráfego ao nível de aplicação, mas impedem o canal de se fechar prematuramente. Uma mensagem PING pode ser enviada por qualquer um dos lados e é respondida com uma mensagem PONG. Todas as mensagens implementadas pela TC-IoT são no formato texto. 13 de 14
7. Referências [1] R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and T. Berners-Lee, Hypertext Transfer Protocol HTTP/1.1, RFC 2616, Internet Engineering Task Force, Jun. 1999. Updated by RFC 2817. [2] R. T. Fielding, REST: Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000. [3] I. Fette and A. Melnikov, The WebSocket Protocol, RFC 6455, Internet Engineering Task Force, Dec. 2011. [4] D. Crockford, The application/json Media Type for JavaScript Object Notation (JSON), RFC 4627, Internet Engineering Task Force, Jul. 2006. Updated by RFC 7158, 7159. [5] T. Bray (Ed.), The JavaScript Object Notation (JSON) Data Interchange Format, RFC 7159, Internet Engineering Task Force, Mar. 2014. 14 de 14