1. Usando a interface WEB

This tutorial will show how to do basic operations in dojot, such as creating devices, checking its attributes and creating flows, import/export, firmware update, generating certificates and device history report.

Nota

  • Para quem é esse tutorial: usuários iniciantes

  • Nível: básico

  • Tempo de leitura: 30 minutos

1.1. Gerenciamento de dispositivo

Esta seção mostra como gerenciar dispositivos. Para tal, serão utilizados dois dispositivos sensores de temperatura e um dispositivo virtual, esse último com a função de observar as temperaturas medidas nos dois primeiros e gerar alarmes em determinadas condições.

Como descrito em Conceitos, todos os dispositivos são baseados em um ou mais modelos (templates). Para a criação de um modelo, você deve acessar a opção Modelos (Templates) na lateral esquerda da tela e então criar um Novo Modelo (New Template), como mostrado abaixo.

Para criar novos dispositivos, deve-se voltar para a opção Dispositivos (Devices) e criar um Novo Dispositivo (New Device), selecionando os modelos nos quais o dispositivo será baseado, como mostrado abaixo.

Note que, quando um modelo é selecionado no painel direito da tela de criação de dispositivo, todos os atributos são herdados para aquele dispositivo. É possível adicionar mais de um modelo, tendo em mente que modelos que compõem o dispositivo não podem compartilhar atributos com o mesmo nome.

Atenção

Como os dispositivos estão fortemente associados aos modelos, caso queira remover um modelo, primeiramente dave-se remover todos os seus dispositivos associados. Caso isso ocorra, a seguinte mensagem de erro aparecerá:

Error message when removing an used template

Atenção

Você pode adicionar e remover atributos dos modelos, fazendo com que as alterações sejam imediatamente refletidas nos dispositivos associados. No caso de novos atributos serem adicionados, no entanto, deve-se observar que os atributos dos modelos que compõem um determinado dispositivo não podem possuir o mesmo nome. Se isso acontecer, a seguinte mensagem aparecerá:

Error while adding overlapping attributes

Essa imagem da tela foi capturada quando um novo modelo foi criado (ExtraTemplate) com um atributo chamado level. Depois um novo dispositivo baseado em ambos os modelos foi criado e um novo atributo também chamado level foi adicionado ao modelo ThermTemplate.

When this happens, no modification is applied to the template (no attribute named “level” related to the “ThermTemplate” is created). However, it remains in the template configuration so the user can figure out what is happening. If the user refreshes the page, it will be reverted to what it was before the modification.

Agora os dispositivos físicos podem enviar mensagens para dojot. Há alguns pontos de atenção: o tópico MQTT deve estar no formato <tenant>:<device-id>/attrs.

Por questão de simplicidade, será emulado um dispositivo utilizando-se a ferramenta mosquito_pub. O parâmetro username será configurado utilizando a opção -u do mosquito_pub. Veja mais sobre em Utilizando a API da dojot no tópico Enviandos Mensagens.

Atenção

Nos vídeos, nós estamos utilizando o Mosca como broker MQTT, então as mensagens estão sendo enviadas para tópicos no formato antigo. Se você está utilizando o VerneMQ, mude-os de acordo com o formato supracitado. Verifique a página de Dúvidas Mais Frequentes para maiores informações.

Nota

Os exemplos estão utilizando MQTT sem segurança. A abordagem recomendada é utilizar TLS. Verifique a página Usando MQTT com segurança (TLS).

Estando criados os sensores de temperatura, falta agora a criação do dispositivo virtual. Ele será a representação de um alarme de sistema disparado quando algo ruim for detectado pelos sensores. Por exemplo, se os sensores de temperatura estivessem instalados em uma cozinha, a medição de uma temperatura acima de 40ºC poderia indicar que o local estaria em chamas. Essa representação do alarme poderia ter dois atributos: nível de severidade e mensagem textual, para que o usuário pudesse ser informado do acontecimento.

Assim como “dispositivos regulares”, dispositivos virtuais também são baseados em modelos. Portanto, um modelo será criado, como mostrado abaixo.

1.2. Configuração de fluxo

Once we’ve created the virtual device, we can add a flow to implement the logic behind the alarm generation. The idea is: if the temperature reading is less than 40, then the alarm system will be updated with a message of severity 4 (mildly important) and a message indicating that the kitchen is OK. Otherwise, if the temperature is higher than 40, then a message is sent with severity 1 (highest severity) and a message indicating that the kitchen is on fire. This is done as shown below.

É importante notar que os nós do tipo “change” têm uma referência a uma entidade “output”. Isso pode ser visto como uma simples estrutura de dados, onde existem os atributos message e severity que casam com aqueles do dispositivo virtual. Este “objeto” é referenciado no nó de saída (output) como uma fonte de dados para o dispositivo que será atualizado (nessa caso, o dispositivo virtual criado). Em outras palavras, pode-se dizer que há uma informação que é transferida dos nós do tipo “change” para o “dispositivo virtual” com os nomes “msg.output.message” e “msg.output.severity”, onde “message” e “severity” são atributos do dispositivo virtual.

Vamos, agora, enviar mais algumas mensagens e ver o que acontece para aquele dispositivo virtual.

1.3. Importar e Exportar

Essa seção mostra como usar as funcionalidades Importar e Exportar. Tais opções permitem que seus dados de configuração sejam salvos em um arquivo, no caso de uma exportação, e carregados na dojot, no caso de Importação. Esse arquivo possui o formato JSON e contém os dados de modelos, dispositivos, fluxos, nós remotos e tarefas de agendamento que foram cadastrados do seu tenant. Para executar o procedimento de exportação dos dados de configurações, expanda o menu no canto superior direito da página, clique em “Import/Export (Import./Exportação)” e então, em “Export (Exportar)”, conforme ilustrado no vídeo a seguir:

O arquivo exportado pode ser armazenado como backup e posteriormente importado novamente na Dojot.

Para executar o procedimento de importação de uma configuração, expanda o menu no canto superior direito da página, clique em “Import/Export (Import./Exportação)” e então, em “Import (Importar)”. Na janela que aparece é possível arrastar e soltar seu arquivo ou navegar na pasta de destino e selecioná-lo, sendo só permitido adicionar um arquivo de extensão JSON, no formato esperado, conforme ilustrado no vídeo a seguir:

Atenção

Ao executar o procedimento de importação todas as configurações atuais do tenant tais como: dispositivos, modelos, fluxos, nós remotos e tarefas de agendamento, serão excluídas permanentemente para que as novas sejam criadas. Os dados de histórico não fazem parte do importar e exportar!

1.4. Atualização de Firmware

Durante a vida útil de um dispositivo, pode ser necessário atualizar seu software de controle (firmware) a fim de corrigir eventuais problemas encontrados durante seu uso ou até mesmo adicionar novas funcionalidades. Atualmente a dojot suporta o procedimento de atualização de firmware via o protocolo de comunicação LwM2M. Para saber detalhes a respeito do procedimento para integração com seu dispositivo por favor verifique a especificação do protocolo LwM2M. Caso seu dispositivo se comunica via este protocolo e possui o procedimento de atualização de firmware implementado, você pode seguir os passos a seguir para atualizar a versão do seu dispositivo.

O processo de atualização de firmware é composto por três etapas:

  • gerenciamento das imagens

  • transferência da imagem para o dispositivo;

  • aplicação da imagem no dispositivo

O detalhamento da execução destas encontra-se a seguir.

Para que a habilitação de gerenciamento de firmware seja disponibilizada, é preciso criar um modelo e, depois de salvo, habilitar o gerenciador de firmware. Após isso, é possível enviar as imagens de firmware para o repositório da dojot que são associadas a este modelo. Atenção: o nome do arquivo da imagem deve possuir a extensão “.hex”.

Note que assim que o Gerenciador de Firmware é habilitado, são atribuídos ao modelo cinco atributos que são usados para suportar a atualização de imagens. Os nomes dos atributos podem ser editados conforme a necessidade da aplicação. Os atributos são:

  • Estado do dispositivo (Device State):

    • Estado atual da atualização de firmware

  • Resultado da versão de aplicação (Result of apply version)

    • Resultado da última aplicação de atualização de uma imagem de firmware;

  • Define qual versão transferir (Sets which version to transfer):

    • Indica ao agente IoT, responsável pelo dispositivo, qual deve ser o nome e a versão da imagem de firmware a ser transferida e atualizada no dispositivo

  • Acionar atualização da versão (Trigger version update)

    • Atuador utilizado para iniciar o procedimento de atualização de firmware

  • Versão atual da imagem (Current version of the image):

    • Versão atual da imagem de firmware, caso disponibilizado pelo mesmo

Após criar o modelo com a opção de gerenciamento de firmware habilitada, é preciso associá-lo a um dispositivo. Assim é possível transferir uma imagem e aplicá-la no dispositivo, conforme o vídeo abaixo:

Observe que em cada etapa, o status e o resultado do processamento da imagem são mostrados.

1.5. Gerando certificados para dispositivos

Nesta seção será demonstrado como gerar certificados x509 para um dispositivo, para que a dojot consiga se comunicar com os dispositivos de forma segura via TLS. Para conseguir realizar o envio de uma publicação é necessário o download dos três arquivos, sendo eles a chave privada “admin 4302d4.key”, o certificado do dispositivo “admin 4302d4.crt” e o certificado da CA “ca.crt”.

Atenção

A geração de certificados via interface gráfica (GUI) só funciona em deployments em que é possível acessar a GUI via HTTPS ou localhost.

Para conseguir executar o comando do vídeo de exemplo é necessário estar no mesmo diretório que os 3 arquivos estão. Comando utilizado no exemplo:

mosquitto_pub -h localhost -p 8883 -t admin: 4302d4/attrs -m '{"humidity": 7}' --cert "admin 4302d4.crt" --key "admin 4302d4.key" --cafile ca.crt

1.6. Gerando relatório de histórico de dispositivos

Nesta seção será demonstrado como gerar um relatório de histórico de um dispositivo. O relatório consegue mostrar os dados de um ou mais atributos do respectivo dispositivo. Para isso, é necessário selecionar os atributos desejados, definir o período e clicar em “gerar”.

1.7. Realizando acesso ao Dashboard

The dashboard is part of GUI-V2, to access it you need to use another URL, in the current version just add to the end of the URL “/v2” in relation to the interface used in the previous items, for example, in the case of localhost it would be http://localhost:8000/v2, see more at Componentes e APIs. The login and password credentials are the same as those used in the rest of dojot. After logging in, a new screen will open and an ADD button will appear in the upper right corner, which will give you the options for various types of viewing. At this moment, in the first “General” screen it will be necessary to add a name for the visualization and optionally a description. The list of devices will appear on the next screen, if you do not find the desired device, you can search by name. After selecting the device, the attributes that are linked to it will be listed, and a color can be chosen to display each attribute, it is also possible to add a caption for each attribute. In “retrieve records by:“ it will be possible to configure some filters, you can select the type of historical data filter as the “last records”, in “order” (minute, hours, days and months), and you can also choose an interval time, in addition you can still view the records in “Real time”, as new data is received they will be displayed in the chosen view. After everything is configured, a summary will be shown with the chosen name and attributes. When accessing the views, it will be possible to change the size, fix (which will disable the option to change the size) and still delete the views.