7. Dúvidas Mais Frequentes

Aqui estão algumas respostas às dúvidas mais frequentes sobre a plataforma dojot.

Não encontrou aqui uma resposta para a sua dúvida? Por favor, abra uma issue no repositório da dojot no Github.

Sumário

7.1. Gerais

7.1.1. O que é a dojot? Por que eu deveria utilizá-la? Por que abrir o código?

É uma plataforma brasileira para IoT que surgiu com uma proposta de código aberto, para facilitar o desenvolvimento de soluções e o ecossistema IoT com conteúdo local voltado às necessidades brasileiras.

O dojot atua como uma plataforma facilitadora com:

  • APIs abertas tornando fácil o acesso das aplicações aos recursos da plataforma.

  • Capacidade de armazenamento de grandes volumes de dados em diferentes formatos.

  • Conectores para diferentes tipos de dispositivos.

  • Construção de fluxos de dados e regras de forma visual, permitindo a rápida prototipação e validação de cenários de aplicações IoT.

  • Processamento de eventos em tempo real aplicando regras definidas pelo desenvolvedor.

7.1.2. Onde eu posso baixar?

Todos os componentes estão disponíveis no repositório da dojot no GitHub: https://github.com/dojot.

7.1.3. Qual é o principal repositório?

Existem 3 repositórios principais:

Veja como usar os repositórios docker-compose e ansible-dojot em Guia de instalação.

7.1.4. Então, encontrei um probleminha chato. Como posso informá-los sobre isso?

Não encontrou aqui uma resposta para a sua dúvida? Por favor, abra uma issue no repositório da dojot no Github.

Se você puder analisar e resolver o problema, por favor faça isso e crie um pull-request com uma breve descrição do que foi feito.

7.2. Uso

7.2.1. Por onde eu começo? É baseado em CLI ou possui uma interface gráfica?

A dojot pode ser acessada via Interface Web ou APIs REST. Considerando que você já tenha instalado o docker e o docker-compose e tenha clonado o repositório docker-compose da dojot, para iniciar todos os serviços, basta executar o comando abaixo:

$ docker-compose up -d

E é isto.

A interface Web está disponível em http://localhost:8000. O usuário é admin e a senha é admin.

APIs REST são explicadas na seção Aplicações.

7.2.2. Pronto, já iniciei e fiz o login. E agora?

Legal! Agora você pode criar seus primeiros modelos (templates) e dispositivos, descrito em Dispositivos, criar alguns fluxos e registrar-se para eventos de dispositivos, ambos descritos em Fluxos de Dados.

7.2.3. Como posso atualizar o meu ambiente com a última versão da dojot?

Basta seguir alguns passos:

1 Atualize o repositório do docker compose com a última versão.

$ cd <path-to-your-clone-of-docker-compose>
$ git checkout master && git pull

Se você precisar de uma outra versão, você pode fazer checkout de uma tag:

$ git tag
  0.1.0-dojot
  0.1.0-dojot-RC1
  0.1.0-dojot-RC2
  0.2.0
  v0.3.0-beta.1
  v0.3.1
  v0.4.0
  v0.4.1
  v0.4.1_rc2
  v0.4.2
  v0.4.2-rc.1
  v0.4.3
  v0.4.3-rc.1
  v0.4.3-rc.2
  v0.5.0-alpha.1
  v0.5.0-alpha.2
  v0.5.0-alpha.3
  v0.5.0-alpha.4
  v0.5.0-rc.1
  v0.5.0
  v0.5.1
  v0.5.2
  v0.6.0
  v0.7.0
  v0.7.1


$ git checkout v0.7.1

7.3. Dispositivos

7.3.1. O que são dispositivos para a dojot?

Na dojot, um dispositivo é uma representação digital para um dispositivo real ou gateway com um ou mais sensores ou uma representação para um dispositivo virtual com sensores/atributos inferidos de outros dispositivos.

Considere, por exemplo, um dispositivo real com um termômetro e um higrômetro; ele pode ser representado na dojot como um dispositivo com dois atributos (um para cada sensor). Chamamos este tipo de dispositivo de dispositivo normal ou usando o seu protocolo de comunicação, como dispositivo MQTT ou dispositivo CoAP.

Nós também podemos criar dispositivos que não correspondem diretamente a dispositivos reais, por exemplo, podemos criar um dispositivo com informação em alto nível de temperatura (está ficando mais quente ou está ficando mais frio) cujos valores são inferidos a partir de sensores de temperatura de outros dispositivos. Este tipo de dispositivo é denominado de dispositivo virtual.

7.3.2. Qual é a relação entre este dispositivo e um dispositivo real?

É simples como parece: o dispositivo para a dojot é um espelho (gêmeo/cópia digital) do dispositivo real. Você pode escolher quais atributos são disponibilizados para as aplicações e outros componentes, adicionando cada um deles através da interface de criação de dispositivo.

7.3.3. O que são dispositivos virtuais? Como se diferenciam dos demais?

Dispositivos são criados para serem como espelhos (gêmeo/cópia digital) dos dispositivos e sensores reais. Um dispositivo virtual é uma abstração que modela coisas que não são factíveis no mundo real. Por exemplo, digamos que um usuário tenha alguns sensores para detectar fumaça em um laboratório, sendo que cada um tem diferentes atributos.

Não seria bom se existisse um dispositivo chamado Laboratório que possui um atributo emChamas? Assim a aplicação dependeria apenas deste atributo para tomar alguma ação.

Uma outra diferença é a maneira como os dados dos dispositivos virtuais são populados. Os dispositivos são preenchidos com informações enviadas a plataforma dojot por dispositivos ou gateways e os virtuais são preenchidos por fluxos ou por aplicações.

7.3.4. E o que são modelos (templates)?

Modelos (templates) são “modelos para dispositivos” que servem como base para a criação de um novo dispositivo. Um dispositivo é construído usando um conjunto de templates - seus atributos serão herdados de cada template (não deve haver nenhum atributo com mesmo nome, no entanto). Se um modelo é alterado, todos os dispositivos associados àquele modelo serão também alterados automaticamente.

7.3.5. Como posso enviar dados via MQTT para a dojot de forma que apareçam no dashboard?

Primeiramente, crie uma representação digital para o seu dispositivo real. Depois, configure o seu dispositivo real para enviar dados para a dojot de maneira que os dados possam ser associados ao seu representante digital.

Tomemos como exemplo uma estação meteorológica que monitora temperatura e umidade e publica essas medidas via MQTT periodicamente. Inicialmente, cria-se um dispositivo do tipo MQTT com dois atributos (temperatura e umidade) e, em seguida, configura-se a estação meteorológica para publicar os dados para a dojot.

Atenção

A partir da versão v0.5.2, você pode escolher entre dois brokers MQTT: Mosca ou VerneMQ. Por padrão, o VerneMQ é utilizado, mas você pode utilizar o Mosca também. Verifique o Guia de instalação para mais informações.

Para enviar dados para a dojot via MQTT (usando o Mosca ou VerneMQ), existem alguns pontos a se ter em mente:

  • Ao usar o Mosca, o tópico deve seguir o formato /<tenant>/<device-id>/attrs (e.g.: /admin/efac/attrs). Dependendo de como o IoT agent MQTT foi inicializado (mais restritivo), o client ID também deve ser configurado para <tenant>:<device-id>, como admin:efac.

  • Ao utilizar o VerneMQ, o tópico deve seguir o formato <tenant>:<device-id>/attrs (e.g.: admin:efac/attrs). Além disso, você deve passar o username do cliente no formato <tenant>:<device-id>, como admin:efac, sendo que este deve ser igual à mesma parte passada no tópico. Você também pode passar o ID do cliente (opcional).

  • O payload MQTT precisa ser um JSON com cada chave sendo um atributo de um dispositivo definido na dojot, como:

{ "temperature" : 10.5, "pressure" : 770 }

Você pode usar certificados com MQTT, veja Usando MQTT com segurança (TLS) para mais informações.

7.3.6. No dashboard alguns atributos são exibidos como tabelas e outros como gráficos. Como são escolhidos/configurados?

O tipo do atributo determina o modo de exibição dos dados no dashboard como segue:

  • Geo: mapa georreferenciado.

  • Boolean, Text e JSON: tabela.

  • Integer e Float: gráfico de linha.

7.3.7. Estou interessado em integrar à dojot o meu dispositivo que é super legal. Como eu faço isso?

Se o seu dispositivo envia mensagens via MQTT (com payload do tipo JSON), CoAP ou HTTP, existe uma grande chance de ser possível integrá-lo com mínima ou nenhuma modificação.

7.3.9. Como posso enviar comandos para o meu dispositivo através da dojot?

Por enquanto, você pode enviar requisições HTTP para a dojot contendo algumas instruções sobre qual dispositivo deve ser configurado e os dados para atuação. Mais detalhes podem ser encontrados em Enviando mensagens.

7.3.10. Não encontrei o protocolo suportado pelo meu dispositivo na lista de tipos, existe algo que eu possa fazer?

Existem algumas possibilidades. A primeira é desenvolver um proxy para traduzir o seu protocolo para um dos suportados pela dojot. A segunda é desenvolver um agente IoT, conector, similar aos existentes para MQTT, CoAP e HTTP. Dê uma olhada em https://github.com/dojot/iotagent-nodejs.

7.3.11. Como eu posso obter dados históricos para um dispositivo em particular?

Você pode fazer isso enviando uma requisição para /history/, como:

curl -X GET \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn...' \
  "http://localhost:8000/history/device/3bb9/history?lastN=3&attr=temperature"

o qual retornará as últimas 3 entradas do atributo temperature do dispositivo 3bb9:

[
  {
    "device_id": "3bb9",
    "ts": "2018-03-22T13:47:07.050000Z",
    "value": 29.76,
    "attr": "temperature"
  },
  {
    "device_id": "3bb9",
    "ts": "2018-03-22T13:46:42.455000Z",
    "value": 23.76,
    "attr": "temperature"
  },
  {
    "device_id": "3bb9",
    "ts": "2018-03-22T13:46:21.535000Z",
    "value": 25.76,
    "attr": "temperature"
  }
]

Para mais detalhes sobre a recuperação de dados do histórico, verifique o tutorial em Conferindo dados históricos.

Há mais operadores que podem ser usados para filtrar entradas. Veja a API do History em Componentes e APIs para ver todos os possíveis operadores e filtros.

7.4. Fluxos de Dados

7.4.1. O que é um fluxo?

É um processamento de mensagens de um dispositivo. Com um fluxo, você pode analisar dinamicamente cada nova mensagem para fazer validações, inferir informações e tomar ações ou gerar notificações.

7.4.3. Por que eu deveria usar um fluxo?

Ele permite uma das coisas mais interessantes do IoT de uma forma simples e intuitiva que é analisar dados para extração de informações e execução de ações.

7.4.4. O que ele pode fazer, exatamente?

Você pode fazer coisas como:

  • Criar visões para um dispositivo (renomear atributos, agregá-los, alterá-los, etc.)

  • Inferir informações baseadas em regras de detecção de borda e georreferenciamento.

  • Notificar de várias maneiras, como HTTP.

O componente responsável pelo fluxo de dados está em desenvolvimento constante e novas funcionalidades são adicionadas a cada versão.

Há mecanismos para adicionar novos blocos de processamento a fluxos. Veja Como eu posso adicionar um novo tipo de nó no menu? para mais informações sobre isto.

7.4.5. Pois bem, como eu posso usá-lo?

Há um tutorial para como utilizar a fluxo, veja mais em Usando o construtor de fluxos (Flowbroker).

7.4.6. Posso aplicar o mesmo fluxo para múltiplos dispositivos?

Você pode usar um modelo como entrada para indicar que ele deve ser executado para todos os dispositivos associados àquele modelo (template). É válido indicar que o fluxo é sempre executado para cada mensagem.

7.4.7. Posso correlacionar dados de diferentes dispositivos no mesmo fluxo?

Uma vez que os fluxos são aplicados individualmente para cada mensagem, você deve criar um dispositivo virtual para agregar todos os atributos e então usar este dispositivo como entrada de um novo fluxo.

Você também pode criar um nó (ou usar um já existente) que lida com contextos.

7.4.8. E se eu quiser enviar um HTTP POST?

../_images/df_http_request.gif

Um aviso importante: assegure-se de que a dojot consegue acessar seu servidor.

7.4.9. Eu quero renomear os atributos de um dispositivo. O que eu devo fazer?

Primeiramente, você deve criar um dispositivo virtual com os novos atributos, para então construir um fluxo de dados para renomeá-los. Isto pode ser feito conectando um nó ‘change’ após um dispositivo de entrada para mapear os atributos de entrada a seus correspondentes na saída.

../_images/df_attributes_renaming.gif

7.4.10. Quero agregar os atributos de múltiplos dispositivos. O que eu devo fazer?

Inicialmente, você deve criar um dispositivo virtual para agregar todos os atributos. Com este dispositivo criado, você deve criar fluxos para mapeamento dos atributos de cada dispositivo real de entrada neste dispositivo virtual. Isto pode ser feito em nós ‘change’ conectados a cada um dos dispositivos de entrada a fim de criar uma variável contendo todos os atributos de saída. Todos os nós change devem ser, por fim, conectados ao nó de saída representando o dispositivo virtual.

../_images/df_attributes_aggregation.gif

7.4.11. Como eu posso adicionar um novo tipo de nó no menu?

Há um tutorial sobre como adicionar novos nós e dois exemplos de nós também, verifique flowbroker library para mais detalhes.

7.5. Aplicações

7.5.1. Quais APIs estão disponíveis para aplicações?

Você pode ver todas as APIs disponíveis na página Componentes e APIs..

7.5.2. Como posso usá-los?

Há um tutorial simples e rápido em Utilizando a API da dojot.

7.5.3. Estou interessado(a) em integrar minha aplicação com a dojot. O que devo fazer?

Isto deve ser bastante direto. Há três formas de integrar sua aplicação à dojot:

  • Obtenção de dados históricos: você pode querer ler todos os dados históricos relacionados a um dispositivo de forma periódica. Isto pode se feito usando a API do history

  • Recuperando dados em tempo real: você pode querer ler dados em tempo real relacionados ao dispositivo. Isso pode ser feito usando o Kafka WS, uma implementação baseada em websocket. Para entender melhor como usar Kafka WS confira Kafka WS.

  • Usando o flowbroker para pré-processar dados: eles podem ajudar a processar e transformar os dados para que possam ser enviados corretamente para o seu aplicativo por meio de solicitação HTTP ou armazenados em um dispositivo virtual (que pode ser usado para gerar notificações conforme descrito anteriormente).

Todos esses endpoints devem ter um token de acesso. Para isso, confira Obtendo um token de acesso

Verifique a documentação da API do History e do Kafka WS em Componentes e APIs. E para um tutorial de como usar o fluxo veja Usando o construtor de fluxos (Flowbroker).