Dúvidas Mais Frequentes

Here are some answers to frequently-asked questions from users of dojot platform.

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

Gerais

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

It’s a brazilian IoT platform launched as open source software with aims to ease the development of solutions and the IoT ecosystem with local resources geared towards brazilians needs.

It takes a role as an enabler platform with:

  • 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.

Onde eu posso baixar?

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

Qual é o principal repositório?

Existem dois repositórios principais:

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

Pedimos que você abra uma issue com o problema no repositório da dojot no Github. Se você souber exatamente qual componente está com o problema, você pode abrir a issue no respectivo repositório (funcionará do mesmo modo).

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.

Uso

Por onde eu começo? É baseado em CLI ou possui uma interface gráfica de usuário ?

dojot can be accessed by a nice web-based interface and by REST APIs. Considering that you installed docker and docker-compose and cloned the docker-compose repository, starting it up is done by just one command:

$ 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.

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

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

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

Basta seguir alguns passos:

1 Update the docker-compose repository to the cutting-edge version (beware the
bugs though)
$ cd <path-to-your-clone-of-docker-compose>
$ git checkout master && git pull

If you need a more stable version, you could checkout a tag instead:
$ git tag
0.1.0-dojot
0.1.0-dojot-RC1
0.1.0-dojot-RC2
0.2.0-aikido

$ git checkout 0.2.0-aikido -b 0.2.0

2 Deploy the latest docker images. This command might need sudo.

$ 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.

Dispositivos

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.

Consider, for instance, an actual device with thermal and humidity sensors; it can be represented inside dojot as a device with two attributes (one for each sensor). We call this kind of device as regular device or by its communication protocol, for instance, MQTT device or CoAP device.

We can also create devices which don’t directly correspond to their physical counterparts, for instance, we can create one with a higher level of temperature information (is becoming hotter or is becoming colder) whose values are inferred from temperature sensors of other devices. This kind of device is called virtual device.

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

It is as simple as it seems: the regular device for dojot is a mirror (digital twin) of your actual device. You can choose which attributes are available for applications and other components by adding each one of them at the device creation interface.

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

Regular devices are created to serve as a mirror (digital twin) for the actual devices and sensors. A virtual device is an abstraction that models things that are not feasible in the real world. For instance, let’s say that a user has few smoke detectors in a laboratory, each one with different attributes.

Wouldn’t it be nice if we had one device called Laboratory that has one attribute isOnFire? Therefore, the applications could rely only on this attribute to take an action.

Another difference is how virtual devices are populated. Regular ones will be filled with information sent by devices or gateways to the platform and virtual ones will be filled by flows or by applications.

And what are templates?

Templates, simply put, are “blueprints for devices” which serve as basis to create a new device. A single device is built using a set of templates - its attributes will be inherited from each template (their names must not be exactly the same, though). If one template is changed, then all associated devices will also be changed.

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.

Let’s take as example a weather station which measures temperature and humidity, and publishes them periodically through MQTT. First, you create a device of type MQTT with two attributes (temperature and humidity). Then you set your actual device to push the data to dojot.

In order to send data to dojot via MQTT (using iotagent-mosca), there are some things to keep in mind:

  • If you don’t define any topic in device template, it will assume the pattern /<service-id>/<device-id>/attrs (for instance: /admin/efac/attrs). This should be the topic to which the device will publish its information to.
  • If you do define a topic in device template, then your device should publish its data to it and set the client-id parameter. It should follow the following pattern: <service>:<deviceid>, such as 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 }

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.

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. Os requisitos para tal integração são descritos na questão Como posso enviar dados via MQTT para a dojot de forma que apareçam no dashboard?.

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

For now, you can send HTTP requests to dojot containing a few instructions about which device should be configured and the actuation payload itself. More details on that can be found in Device-Manager how-to - sending actuation messages.

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 conector similar as existentes para MQTT, CoAP e HTTP.

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.

How can I retrieve historical data for a particular device?

You can do this by sending a request to /history endpoint, such as:

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

which will retrieve the last 3 entries of temperature attribute from the device 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"
  }
]

There are more operators that could be used to filter entries. Check history-ws API documentation to check out all possible operators.

Fluxos de Dados

O que é um fluxo?

It’s a sequence of functional blocks to process incoming device messages. With a flow you can dynamically analyze each new message in order to apply validations, infer information and trigger actions or notifications.

Por que eu deveria usar um fluxo?

It allows one of the coolest things of IoT in an easy and intuitive way, which is to analyze data for extracting information and then take actions.

O que ele pode fazer, exatamente?

Você pode fazer coisas como:

  • Create views from a particular device, by renaming, aggregating and changing values, etc).
  • Infer information based on switch, edge-detection and geo-fence rules.
  • 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.

There are mechanisms to add new processing blocks to new flows. Check the How can I add a new node type to its menu? question for more information on that.

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.

Posso aplicar o mesmo fluxo para múltiplos dispositivos?

You can use a template as input to indicate that the flow should be applied to all devices associated to that template. It’s worth to point out that the flow is processed individually for each new input message, i.e. for each input device.

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.

Eu quero enviar uma notificação por e-mail, como devo fazer?

Basicamente, você deve adicionar um nó ‘e-mail’ e configurá-lo. Este nó tem como servidor pré-definido o gmail-smtp-in-l.google.com, mas você pode alterá-lo livremente. Para escrever o corpo do email, você deve usar um nó ‘template’ e associar a variável criada nestenó com o nó de e-mail através do campo ‘source’ deste último.

../_images/df_email.gif

É importante notar que a dojot não contém um servidor de e-mail. A plataforma gera os comandos SMTP e os envia ao servidor especificado.

E se eu quiser enviar um HTTP POST?

É quase a mesma coisa de enviar um e-mail.

../_images/df_http_request.gif

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

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

First of all, you need to create a virtual device with the new attributes, then you build a data flow to rename them. This can be done connecting a ‘change’ node after the input device to map the input attributes to the corresponding ones into an output, and finally connecting the ‘change’ to the virtual device and assigning to it the output.

../_images/df_attributes_renaming.gif

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

How can I add a new node type to its menu?

It’s pretty easy, actually, although it needs a few commands in bash. To add a new node, you should send the following request:

curl -H "Authorization: Bearer ${JWT}" http://localhost:8000/flows/v1/node
-H "content-type: application/json" -d '{"image": "mmagr/kelvin:latest",
"id":"kelvin"}'

This will add a new node called ‘kelvin’ which is implemented by a docker image located at “mmagr/kelvin”. There’s only one caveat: you should pull this image in your target system (where dojot is installed) before adding it to the flow menu.

If you don’t want this node anymore, you could delete it:

curl -X DELETE -H "Authorization: Bearer ${JWT}"
"http://localhost:8000/flows/v1/node/kelvin"

And that’s it! In the flowbroker repository, there is an example of how to build a Docker image that could be added to flow node menu.

Aplicações

Como posso usá-los?

There is a very quick and useful tutorial in the Using API interface.

I’m interested in integrating my application with dojot. How can I do it?

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/).
  • Subscrição de eventos relacionados a dispositivos: se sua aplicação é capaz de esperar por eventos, você poderá achar mais interessante usar subscrições, as quais podem ser criadas usando esta API (todos os serviços deste apiary devem ser precedidos por /metrics/).
  • 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 ou e-mail. 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?.