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.

Ela oferece

  • APIs abertas tornando o acesso fácil 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:

7.1.4. Então, encontrei um probleminha chato. Como posso informá-lo 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 de usuário ?

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 dojot para o docker-compose, 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 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-rc.1
  v0.4.3-rc.2
  v0.4.3


$ git checkout v0.4.2

De tempos em tempos nós lançaremos novas versões para componentes dadojot. Eles podem ser lançados individualmente (no entanto, tentaremossincronizar todos os lançamentos). Uma vez que nós tenhamos um conjunto decomponentes que opere de forma estável, atualizaremos o repositório do docker-compose

Atualize o ambiente com as imagens dockers mais recentes.

$ docker-compose pull && docker-compose up -d

Este procedimento também se aplica para as máquinas virtuais dojot uma vez que as mesmas utilizam docker-compose.

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 umhigrômetro; ele pode ser representado na dojot como um dispositivo com doisatributos (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 exisitisse um dispositivo chamado Laboratório quepossui um atributo emChamas? Assim a aplicação dependeria apenas desteatributo 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 aplataforma 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 templates?

Templates são “modelos para dispositivos” que servem como base para acriação de um novo dispositivo. Um dispositivo é construído usando um conjuntode templates - seus atributos serão herdados de cada template (não deve havernenhum atributo com mesmo nome, no entanto). Se um template é alterado, todosos dispositivos associados àquele template serão também alteradosautomaticamente.

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 meteorólogica 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.

Para enviar dados para a dojot via MQTT (usando o iotagent-mosca),existem algumas coisas para se ter em mente:

  • O tópico deve parecer com /<tenant>/<device-id>/attrs (por exemplo: /admin/efac/attrs). Dependendo de como o IoT agent foi inicializado (mais restritivo), o client ID deve ser também configurado para``<tenant>:<deviceid>``, como "admin:efac".
  • O payload MQTT precisa ser um JSON com as chaves correspondendo aos atributos definidos para o dispositivo na dojot, como:
{ "temperature" : 10.5,"pressure" : 770 }

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 e Text: 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 intergrá-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 contendoalgumas instruções sobre qual dispositivo deve ser configurado e os dados paraatuação. Mais detalhes podem ser encontrados na seção Device-Manager how-to - sending actuation messages.

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 IotAgent, conector, similar as existentes para MQTT, CoAP e HTTP. Dê uma olhada em https://github.com/dojot/iotagent-nodejs

7.3.11. Eu salvei um atributo, mas o mesmo sumiu do dispositivo. É um defeito?

Provavelmente você salvou o atributo, mas não o dispositivo. Se você não clicar no botão para salvar o dispositivo, o atributo adicionado será descartado. Estamos melhorando as mensagens da plataforma para avisar e lembrar os usuários de salvarem as suas configurações.

7.3.12. Compo eu posso obter dados históricos para um dispositivo em particular?

Você pode fazer isto 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 dodispositivo 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"
  }
]

Há mais operadores que podem ser usados para filtrar entradas. Check History API para ver todas os possíveis operadores e outros 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, inferirinformaçõ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.
  • Enviar notificações via email.
  • Enviar notificações via 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 How can I add a new node type to its menu? para mais informações sobreisto.

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

Ele segue o modo de uso do node-RED. Você pode ler a documentação para mais detalhes.

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

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

7.4.7. Posso correlacionar dados de diferentes dispositivos no mexmo 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.

Outra coisa que pode ser feita é construir um nó do flowbroker paralidar com contextos, os quais podem ser usados para armazenar e obter dadosrelacionados a um fluxo ou nó.

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 entada 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?

E é isso! Em https://github.com/dojot/flowbroker/tree/master/lib há 2 exemplos de como construir uma imagem do Docker que pode ser adicionada ao menu de nós do flowbroker.

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 API Listing page

7.5.2. Como posso usá-los?

Há um tutorial simples e rápido na in the Using API interface.

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

Isto deve ser bastante direto. Há duas 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 esta API (um lembrete apenas: todos os serviços descritos neste apiary deve ser precedido de /history/).
  • Usar os fluxos de dados para pré-processar dados: se for necessário realizar algum processamento extra, você pode usar os fluxos. Eles auxiliam no processamento e na transformação de dados para envio para sua aplicação via requisições HTTP. Uma outra forma é armazenar os dados em dispositivos virtuais e criar subscrições para enviar notificações toda vez que acontecer uma alteração em seus atributos.

Todas as requisições devem carregar um token de acesso, o qual pode ser obtido como descrito na pergunta Como posso usá-los?.