Page tree
Skip to end of metadata
Go to start of metadata

Índice

Porque usar uma Plataforma?

Construir soluções de IoT que resolvem problemas do mundo real não é uma tarefá trivial. Em geral, é necessária uma combinação de habilidades:

  • OT, ou Operational Technology. Trata-se de entender o problema real que se está tentando resolver e como resolvê-lo no mundo real. Se a solução é uma solução de irrigação na agricultura, é necessário conhecer quais os problemas associados, quais os equipamentos são usados para irrigar, de que forma trabalham, onde estão suas limitações, e assim por diante.
  • HW, ou Hardware. Trata-se de construir o equipamento que trabalha como ponte entre OT e a Internet. Esse equipamento, dependendo das condições de trabalho, talvez tenha que ser resistente a humidade, sujeira, vibração, temperatura, conectividade. entre outros aspectos importantes para uma instalação em campo.
  • SW, ou Software. Trata-se do I (Internet) em "Internet das Coisas". Construir uma solução de software na Internet capaz de receber, armazenar, processar e analisar grandes volumes de dados, com alta disponibilidade, segurança e desempenho. Gerenciar os dispositivos.

A Plataforma Konker é uma ferramenta que endereça o último ponto desta lista: o Software na Internet. Trata-se de uma Plataforma na nuvem num modelo PaaS (Platform as a Service) que realiza a coleta de dados e a comunicação entre os dispositivos. O objetivo é que o criador de uma solução possa concentrar seus esforços pensando na solução em si, no hardware e no problema que deve ser resolvido - em lugar de desperdiçar tempo realizando setup de servidores, replicação, backup, monitoração e assim por diante. A prototipação de soluções é especialmente simples: em alguns minutos é possível começar a enviar e visualizar dados.

Conceitos

Para usar a Plataforma Konker, alguns conceitos são importantes:

Dispositivo

Um dispositivo na Pataforma Konker é uma representação de um dispositivo físico (ou virtual) que envia ou recebe dados. É o equivalente a "Things" quando se fala em "Internet of Things". Apenas dispositivos cadastrados na plataforma podem enviar e receber dados.

Canal

O conceito de canal está associado ao dispositivo e é uma maneira de agrupar mensagens com conteúdo semelhante para que possam ser tratadas em conjunto. Um exemplo é o caso em que um dispositivo tem 2 sensores: um sensor de umidade e um sensor de temperatura. Nesse caso, é aconselhável que os dados enviados pelo dispositivo sejam enviados para um canal "temperatura" e os dados de umidade para um canal de "umidade". Dessa forma, pode-se aplicar filtros ou visualizações apenas pra um tipo de informação ou de outra. Canais não precisam ser cadastrados: basta informar o nome do canal durante o envio da informação que ele será automaticamente criado a partir daquele momento.

Os canais também são relevantes para o dispositivo que recebe os dados. Suponha que um dispositivo receba da plataforma 2 tipos de informação, como por exemplo comandos e configurações. Nesse caso, o dispositivo pode fazer uma assinatura para receber apenas os dados de comandos ou apenas os dados de configuração. Os nomes de canais podem ser definidos com os caracteres de A a Z maiúsculos ou minúsculos, numerais de 0 a 9 e os caracteres especiais '-' e '_'. Espaços não são permitidos.

Rota

Uma rota é um caminho que liga um dispositivo de entrado a um dispositivo (ou webservice) de saída. Dessa forma, se há um dispositivo que contém um botão chamado "Botao 01" e um dispositivo que contém um LED chamado "LED 01", pode-se criar uma rota que liga o dispositivo "Botao 01" ao dispositivo "LED 01", de forma que as mensagens enviadas ao pressionar o botao sejam encaminhadas ao dispositivo que acende ou apaga o LED. Nesse cenário, também seria necessário especificar na rota qual o canal em que os dispositivos se comunicam.


Transformação

Um ponto de transformação permite que uma mensagem seja arbitrariamente manipulada durante o processamento da rota para que ela esteja no formato que o dispositivo de saída possa entender. Isso é realizado através de chamadas a serviços externos à plataforma que devem receber as mensagens, processá-las e devolvê-las à plataforma para continuar o processamento. Ver "Adicionando Comportamento Personalizado" para mais informações.


Como Usar

Registrando seu Dispositivo

Antes de começar a enviar dados, o dispositivo precisa ser registrado na Plataforma Konker. O processo de registro é simples: a partir do Menu Principal, na tela de Dispositivos, basta adicionar um Novo Dispositivo.




O cadastro é muito simples e rápido, basta informar:



  • Device ID: um ID único para aquele dispositivo. Como número serial, um identificador sequencial, qualquer informação que possa identificar unicamente aquele dispositvo;
  • Device Name: um nome amigável para o dispositivo.
  • Descrição: um texto mais longo do que é o dispositivo, o que ele faz e assim por diante;
  • Ativo: se esse dispositivo pode enviar ou receber dados. Dispositivos inativos não podem enviar ou receber dados.

Após registrar o dispositivo, é necessário solicitar as credenciais de acesso. Tais credenciais são usadas para que o dispositivo faça a autenticação. Trata-se de um usuário e uma senha que estão associados de forma intransferível àquele dispositivo. Se um usuário tem 10 dispositivos cadastrados, cada um desses dispositivo terão um usuário de dispositivo e uma senha de dispositivo associados. A geração das credenciais estão no botão Conectar:



Clicando no botão "Gerar Senha", uma nova senha será gerada para aquele dispositivo. O usuário está no campo "Usuário" destacado.


IMPORTANTE: Quando a senha for gerada, copie e salve em um local seguro. A Plataforma Konker não armazena essa senha por questões de segurança (armazena apenas o hash criptográfico) e portanto não é possível recuperá-la. Caso a senha seja perdida, uma nova senha deverá ser gerada.



Nesse exemplo específico, sempre que  o dispositivo precisar enviar dados (HTTP ou MQTT), deve usar como username 1skjet469ps e senha etvp6Iu9dkZY. Para os seus dispositivos, usuário e senha serão diferentes.

Enviando dados

É possível enviar dados para a Plataforma Konker através de HTTP / REST ou via MQTT. O comportamento é ligeiramente diferente, mas ambas são alternativas aceitáveis para o envio de informações.

Envio via REST

Para enviar os dados via REST, as informações precisam ser um documento JSON válido. Ao registrar o dispositivo e criar as credenciais de acesso, o dispositivo passa a ter um usuário e senha próprios que deverão ser usados no momento de enviar os dados. Os dados devem ser enviados via POST com o cabeçalho de 'Content-Type: application/json' e autorização do tipo Http-Basic, com o usuário e senha informados.

IMPORTANTE: um device só está autorizado a enviar dados para um canal associado àquele device específico. Não é possível autenticar-se com as credenciais de um device A e enviar dados para um canal do device B. Caso seja esse o desejo, deve-se usar uma rota do device A para o device B.

Suponha que o dispositivo já tenha sido cadastrado e que as credenciais de acesso já tenham sido geradas, e que o dispositivo deseja enviar a mensagem abaixo

  • Mensagem a ser enviada: {"temperature": 22, "unit": "celsius"}
  • Usuário de dispositivo gerado pela plataforma: gr4ouo53timc
  • Senha de dispositivo gerada pela plataforma: mflaCCWx9jSh
  • URL de envio (obtida na tela de acesso): http://api.hackathon.konkerlabs.net:80/pub/gr4ouo53timc/{canal}

Nesse caso, vamos enviar os dados para um canal chamado "temperature", para agregar informações relacionadas com temperatura. Alguns exemplos de como realizar o envio via REST:

Envio REST via linha de comando com cURL:

curl -u  gr4ouo53timc:mflaCCWx9jSh -X POST -H 'Content-Type: application/json' \
 -d '{"temperature": 22, "unit": "celsius"}' \
http://api.hackathon.konkerlabs.net:80/pub/gr4ouo53timc/temperature
Retorno: {"code":"200","message":"OK"}


Envio via MQTT

Para enviar os dados via MQTT, as informações precisam ser um documento JSON válido. Ao registrar o dispositivo e criar as credenciais de acesso no portal de administração da Plataforma, o dispositivo passa a ter usuário e senha próprios que deverão ser usados no momento de enviar os dados. O usuário e senha deverão ser usados para se conectar via MQTT e publicar as informação numa esturuta de tópicos específica:

pub/<device_username>/<canal>

Suponha que o dispositivo já tenha sido cadastrado e que as credenciais de acesso já tenham sido geradas, e que o dispositivo deseja enviar a mensagem abaixo

  • Mensagem a ser enviada: {"temperature": 22, "unit": "celsius"}
  • Usuário de dispositivo gerado pela plataforma: gr4ouo53timc
  • Senha de dispositivo gerada pela plataforma: mflaCCWx9jSh
  • Endereço de envio (obtido na tela de acesso): mqtt://mqtt.hackathon.konkerlabs.net:1883
  • Tópico de envio (obtida na tela de acesso):  pub/gr4ouo53timc/{canal}

Nesse caso, vamos enviar os dados para um canal chamado "temperature", para agregar informações relacionadas com temperatura. Alguns exemplos de como realizar o envio:

Envio MQTT via Python:

import paho.mqtt.client as mqtt
import json

client = mqtt.Client()
client.username_pw_set("gr4ouo53timc", "mflaCCWx9jSh")
client.connect("mqtt.hackathon.konkerlabs.net", 1883)
client.publish("pub/gr4ouo53timc/temperature",
                 json.dumps({"temperature": 22, "unit": "celsius"}))



IMPORTANTE: um device só está autorizado a enviar dados para um canal daquele device específico. Não é possível autenticar-se com as credenciais de um device A e enviar dados para um canal do device B. Caso seja esse o desejo, deve-se usar uma rota do device A para o device B.

IMPORTANTE: A plataforma Konker suporta hoje MQTT com QOS=0, ou seja: não há garantias transacionais de entrega das mensagens caso o ambiente esteja sob carga elevada, por exemplo. Dessa forma, MQTT é o cenário ideal para envio de dados como sensores e streaming de dados. Caso seja necessário garantir que a mensagem tenha sido entregue e processada pela plataforma, o o serviço REST é recomendado.

Recebendo Dados

Recebendo os dados via REST

Para receber dados enviados pela plataforma via REST, o dispositivo precisa ter sido previamente cadastrado e ter credenciais geradas (usuário e senha específicos do dispositivo). A autenticação é do tipo Http-Basic.

O recebimento de dados via HTTP pode funcionar em dois modelos semelhantes, mas com características distintas: polling ou long polling. No modelo de polling, o device pode solicitar à Plataforma Konker as últimas mensagens recebidas. Caso não haja mensagens recebidas recentemente, a plataforma retorna uma lista vazia. No modelo de long polling, o device também solicita as mensagens mais recentes, mas informa também um tempo de espera. Caso não haja mensagens a serem retornadas, a Plataforma Konker irá esperar pelo tempo informado até que uma nova mensagem seja retornada.

O método HTTP usado em ambos os casos é o GET e dois parâmetros opcionais podem ser informados:

  • waitTime: tempo de espera em milissegundos, caso não haja mensagens a serem retornadas. Máximo de 30000.
  • offset: é um timestamp em UTC - número de milissegundos de 01/01/1970. Apenas mensagens que chegaram após esse timestamp serão retornadas

Caso não sejam informados waitTime ou offset, a última mensagem disponível será retornada. Caso seja informado um offset, apenas mensagens recebidas após esse timestamp serão retornadas. Em qualquer caso, o número máximo de mensagens retornadas é no máximo 100.

Além da mensagem em si, este serviço também retorna informações de metadados associados a esta mensagem. Um exemplo de retorno segue abaixo:

[
  {
    "meta": {
      "timestamp": 1476100297217,
      "incoming": {
        "deviceId": "sensorA",
        "channel": "temperature"
      },
      "outgoing": {
        "deviceId": "actuatorB",
        "channel": "out"
      }
    },
    "data": {
      "temperature": 21,
      "unit": "celsius"
    }
  },
  {
    "meta": {
      "timestamp": 1476102464535,
      "incoming": {
        "deviceId": "sensorA",
        "channel": "temperature"
      },
      "outgoing": {
        "deviceId": "actuatorB",
        "channel": "out"
      }
    },
    "data": {
      "temperature": 23,
      "unit": "celsius"
    }
  }
]


O retorno é uma lista de documentos. Cada um dos documentos, contém duas chave principais:

  • "meta": metainformação relacionada com aquela mensagem. São dados que não foram enviados por dispositivos, mas são informações de controle, tais como quando a mensagem foi recebida, qual o dispositivo e canal que originaram a mensagem, qual o dispositivo e canal de destino da mensagem.
  • "data": o conteúdo da mensagem enviada pelo dispositivo, incluindo possíveis alterações que tenham ocorrido durante a execução da rota, tais como transformações.

IMPORTANTE: um device pode apenas receber dados de canais associados a ele. Caso seja necessário receber dados associados a outro dispositivo, uma rota deve realizar esse trabalho.

Abaixo, alguns exemplo de uso.

Suponha que o dispositivo já tenha sido cadastrado e que as credenciais de acesso já tenham sido geradas. Desejamos receber os dados que foram destinados ao dispositivo em seu canal "out".

  • Usuário de dispositivo gerado pela plataforma: gr4ouo53timc
  • Senha de dispositivo gerada pela plataforma: mflaCCWx9jSh
  • Endereço de recebimento (obtido na tela de acesso): http://api.hackathon.konkerlabs.net:80/sub/gr4ouo53timc/out

Recebendo dados via REST Polling usando cURL

curl -u gr4ouo53timc:mflaCCWx9jSh http://api.hackathon.konkerlabs.net/sub/gr4ouo53timc/out

Retorno: [{"meta":{"timestamp":1476495431147,
"incoming":{"deviceId":"MeuDispositivo01","channel":"temperature"},
"outgoing":{"deviceId":"MeuDispositivo01","channel":"out"}},
"data":{"unit":"celsius","temperature":22}}]


Recebendo dados via REST Polling usando PHP

O mesmo exemplo acima em PHP:

<?php
$username="gr4ouo53timc";
$password="mflaCCWx9jSh";
$channel="out";

$url="http://api.hackathon.konkerlabs.net:80/sub/$username/$channel";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERPWD, "$username:$password");
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
$output = curl_exec($ch);
$decoded = json_decode($output);
curl_close($ch);
print_r($decoded);
?>

Recebendo dados via REST no browser, através de JSONP

O mesmo exemplo acima pode ser implementado diretamente no browser, usando JSONP.

A URL usada tem o seguinte formato:

http://<usuario>:<senha>@api.hackathon.konkerlabs.net/sub/<usuario>/<canal>

Nesse caso, o usuário e senha devem fazer parte da URL, como no exemplo abaixo:

$.ajax({
  url: "http://gr4ouo53timc:mflaCCWx9jSh@api.hackathon.konkerlabs.net/sub/gr4ouo53timc/out",
  type: "GET",
  dataType: 'jsonp',
  success: function(data, textStatus, XMLHttpRequest) {
// os dados são retornados no campo data.
      console.log(JSON.stringify(data))
  },
  error: function(XMLHttpRequest, textStatus, errorThrown) {
      console.log("Error!")
  }
});

É necessário incluir o jQuery para executar esse exemplo.

Recebendo dados via REST Polling de forma paginada, usando cURL

Nesse caso, basta usar o timestamp da última mensagem recebida no passo anterior. Por exemplo: recebendo os dados mais recentes, que chegaram depois do exemplo anterior (usando portanto o filtro de timestamp > 1476495431147).

curl -u gr4ouo53timc:mflaCCWx9jSh http://api.hackathon.konkerlabs.net/sub/gr4ouo53timc/out?offset=1476495431147

Retorno: [{"meta":{"timestamp":1476495678084,"incoming":{"deviceId":"MeuDispositivo01","channel":"temperature"},"outgoing":{"deviceId":"MeuDispositivo01","channel":"out"}},"data":{"unit":"celsius","temperature":22}},{"meta":{"timestamp":1476495679381,"incoming":{"deviceId":"MeuDispositivo01","channel":"temperature"},"outgoing":{"deviceId":"MeuDispositivo01","channel":"out"}},"data":{"unit":"celsius","temperature":22}}]

Veja que nesse caso, a mensagem do exemplo anterior não foi retornada.

Esse processo de usar o timestamp da última mensagem reecebida no polling como ofsset da próxima pode ser usada para paginação. As páginas tem tamanho de 100 mensagens.

Recebendo dados via REST Long Polling de forma paginada, usando cURL

Se realizarmos a mesma operação do passo anterior, usando o timestamp da última mensagem como offset na próxima chamada, eventualmente não haverá mais mensagens disponíveis. Quando isso acontecer, ele retornará uma lista vazia:

curl -u gr4ouo53timc:mflaCCWx9jSh http://api.herlabs.net/sub/gr4ouo53timc/out?offset=1476495679381
Retorno: [ ]

Se quisermos que o servidor fique bloqueado esperando uma nova mensagem num modelo de leitura bloqueante, podemos passar o parâmetro waitTime em millisegundos.

curl -u gr4ouo53timc:mflaCCWx9jSh http://api.herlabs.net/sub/gr4ouo53timc/out?offset=1476495679381&waitTime=30000

Nesse caso, o servidor esperará por até 30s aguardando que alguma mensagens esteja disponível para o dispositivo.


Recebendo dados via MQTT

Para receber os dados via MQTT, basta realizar um subscribe em um tópico específico relacionado ao canal que se deseja escutar. É necessário que tenham sido previamente geradas as credenciais específicas para o dispositivo: username e senha de dispositivo.


A estrutura de canais que se deve fazer o subscribe é a seguinte:

sub/<device_username>/<canal>


Abaixo alguns exemplo de recebimento de mensagens via MQTT.

Recebendo via MQTT em Python

import paho.mqtt.client as mqtt
import json

def on_connect(client, userdata, flags, rc):
    print("Connected!")
    client.subscribe("sub/gr4ouo53timc/out")

def on_message(client, data, msg):
    print(msg.topic + " " + str(msg.payload))


client = mqtt.Client()
client.on_message = on_message
client.on_connect = on_connect
client.username_pw_set("gr4ouo53timc", "mflaCCWx9jSh")
client.connect("mqtt.hackathon.konkerlabs.net", 1883)
client.loop_forever()

Visualizando os Dados

A Plataforma Konker permite visualização rápida de dados que tenham sido ingeridos tanto via MQTT quanto via REST.



A visualização pode ser realizada de duas formas:


- Tabular. Nesse caso, as últimas 100 mensagens ingeridas de um dispositivo ou entregues ao dispositivo pela plataforma estão disponíveis para consulta. Essa opção está disponível através do botão "Eventos" na tela de dispositivos.


- Gráfica. Nesse caso, é possível visualizar graficamente uma série temporal. É um gráfico de linha, onde o eixo X representa o tempo e o eixo Y representa um campo numérico, à sua escolha. Essa opão está disponível no menu principal, através do item "Visualização". Esta tela está limitada a exibir, no máximo, 100 pontos por vez. Apenas dados numéricos que tenham sido ingeridos serão exibidos nessa tela.

Adicionando Comportamento Personalizado

É possível adicionar comportamento mais sofisticado à Plataforma através dos conceitos de Rotas, Filtros e Transformação.

Enviando dados de um dispositivo para outro através de Rotas

A Plataforma Konker permite que os dados enviados por um dispositivo sejam transportados até um outro dispositivo. É o que permite a ligação simples entre eles. Um botão poderia enviar uma mensagem para acionar um LED, por exemplo. O mecanismo usado para isso é a criação de Rotas.

Para criar uma Rota entre dois dispositivos, basta usar o menu "Roteador de Eventos"



A criação de uma rota envolve basicamente definir qual o dispositivo e o canal de origem da mensagem e o dispositivo e canal de destino de mensagem. Múltiplas rotas podem ser criadas para um mesmo dispositivo, de forma que uma mensagem (um clique de botão por exemplo) e um único dispositivo.

Por exemplo, para direcionar as mensagens do canal temperature de um Sensor para o canal cmd de um Atuador.




  • No labels