Forma Padrão de Comunicação

Modelo de Requisição HTTP

O sistema Guardião Cloud trabalha com um modelo de requisição HTTP de forma bem simples para realizar a coleta e tratamento dos dados.

O método HTTP padrão utilizado é o GET (pode ser testado direto do navegador), com intenção de facilitar o acessso ao sistema foi criado um URL simplificada, que pode ser acessada através do endereço: http://guardiao.cl.

Um dado que será referenciado sempre é o Número de Série do Dispositivo e a API Key, então mantenha tais valores em mãos, e qualquer dúvida de como obter esse valor, acesse aqui.

Caso tenha dúvida do que poderia ser inventado acesse nosso site de exemplos.

Existe um padrão de código de retorno HTTP para todos os dispositivos, o código de retorno e seus significados está abaixo:

Código HTTP Significado
200 Informação obtida/armazenada com sucesso.
404 Número de série não encontrado.
500 Falha ao encontrar o projeto (ApiKey não encontrada)
501 Envio de estado inválido (apenas gatilho).

Dispositivo de Coleta

Para realizar a coleta de dados, apenas é necessário chamar a URL: /collect/ em seguida informar qual o Número de Série do dispositivo.

Após tal chamada é obrigatório passar o parâmetro contendo a API Key, no seguinte formato: ?apiKey={API_KEY} no nosso exemplo abaixo utilizamos o seguinte valor: ?apiKey=497aa991-d8e6-4bb6-ad17-f01a13648333.

Todo e qualquer outro valor passado após esse parâmetro será entendido como dado de coleta, ou seja, após o valor da API Key, separado por & será entendido como valor qualquer de coleta.

$ curl -X GET "http://guardiao.cl/collect/IOTWBS0001/?apiKey=497aa991-d8e6-4bb6-ad17-f01a13648333&temperatura=10&humidade=30&luminosidade=15"
# resposta: {"status":"OK"}

No nosso exemplo ao lado, três informações sendo coletadas: &temperatura=10&umidade=30&luminosidade=15. Para cada valor será apresentado conforme tabela abaixo:

Identificador Valor
temperatura 10
umidade 30
luminosidade 15

Lembrando!! O dado de coleta pode ter qualquer nome, porém deve ter valor numérico.

Gatilhos

O Gatilho sempre aguarda saber qual o estado que o dispositivo deva estar, se ativo ou inativo. Para tanto, existe duas URL's, que utilizam o começo: /trigger/, que pode ser chamado em condições específicas.

Pensando no seguinte cenário: tenho um sensor de presença, e foi disparado pelo sensor que existe algum movimento no cômodo a qual se monitora. Posso ativar/habilitar o gatilho, através da URL:

$ curl -X GET "http://guardiao.cl/trigger/IOTWBS0002/on/?apiKey=497aa991-d8e6-4bb6-ad17-f01a13648333"
# resposta: {"status":true,"dateUpdated":"2015-05-26T11:38:41.587Z"}

Dependendo da necessidade, é possível apenas ativar (existe um botão na dashboard a qual é possível inativar). Caso deseje desativar, conforme nosso exemplo, posso chamar a seguinte URL:

$ curl -X GET "http://guardiao.cl/trigger/IOTWBS0002/off/?apiKey=497aa991-d8e6-4bb6-ad17-f01a13648333"
# resposta: {"status":false,"dateUpdated":"2015-05-26T11:50:12.249Z"}

O único parâmetro que é alterado nas URL é o /on/ e o /off/ ou seja, ambos seguem o mesmo modelo.

Atuadores

Os atuadores são dispositivo que apenas se requisita o estado em que ele deva estar. Ou seja, através da URL: /actuator/ será questionado se o mesmo deve estar ativo ou inativo.

Para controlar o dispositivo, é possível ativar/inativar o dispositivo via Dashboard ou pela API de Serviço.

$ curl -X GET "http://guardiao.cl/actuator/IOTWBS0003/?apiKey=497aa991-d8e6-4bb6-ad17-f01a13648333"

Caso o dispositivo esteja inativo, o retorno será dado em JSON conforme exemplo:

{"state":false}

Caso o dispositivo esteja ativo, o retorno será dado em JSON conforme exemplo:

{"state":true}

Uma boa dica para testar, é através do dashboard ativa e desativar o dispositivo e chamar a URL conforme exemplo, e ver o retorno.