O Eclipse Ditto com MQTT é uma das formas mais práticas de construir gêmeos digitais open source: os dispositivos publicam em um broker, o Ditto mantém um gêmeo em JSON de cada dispositivo e as aplicações leem o estado do gêmeo por uma API ou recebem eventos de mudança. Neste tutorial você vai rodar o Ditto localmente, criar uma thing, conectar o Ditto a um broker MQTT, mapear o JSON simples dos dispositivos em features do gêmeo e publicar eventos do gêmeo de volta no MQTT.
Para entender onde um serviço de gêmeo se encaixa, veja o guia completo sobre gêmeo digital.
O Que o Eclipse Ditto Faz
O Eclipse Ditto é um framework open source da Eclipse Foundation para gerenciar gêmeos digitais. Ele não conversa diretamente com sensores. Em vez disso, mantém um documento de gêmeo por dispositivo, chamado thing, e oferece:
- Uma API REST e WebSocket para ler e modificar gêmeos.
- Políticas que controlam quem pode ler ou gravar cada parte de um gêmeo.
- Um serviço de conectividade que se conecta a brokers externos, incluindo MQTT 3.1.1 e MQTT 5.
- Mapeamento de payload para transformar mensagens arbitrárias de dispositivos em atualizações do gêmeo.
- Eventos de mudança e busca em todas as things.
Uma thing tem attributes (metadados majoritariamente estáticos, como localização ou número de série) e features (partes funcionais, cada uma com properties para valores reportados e, opcionalmente, desiredProperties para valores-alvo). Isso se encaixa perfeitamente no padrão reportado vs desejado descrito em sincronização de estado de gêmeo digital.
Arquitetura de uma Configuração Eclipse Ditto MQTT
devices --publish--> MQTT broker <--subscribe/publish-- Ditto connectivity
| |
| Ditto things (twins)
| |
dashboards <--subscribe--+ REST / WebSocket API for apps
O Ditto se conecta ao broker como um cliente MQTT comum. Isso significa que o broker pode ser qualquer um que siga o padrão: um Mosquitto local, o servidor MQTT público (gratuito) para testes e protótipos (nunca para dados de produção) ou um broker MQTT gerenciado como o ConnectMQ em produção.
Passo 1: Rode o Eclipse Ditto com Docker
O repositório do Ditto inclui uma configuração Docker Compose. Clone-o e suba a stack:
git clone https://github.com/eclipse-ditto/ditto.git
cd ditto/deployment/docker
docker compose up -d
Depois que os containers estiverem saudáveis, a API fica disponível via nginx em http://localhost:8080. As credenciais padrão de desenvolvimento são ditto / ditto para a API e devops / foobar para endpoints administrativos, como as conexões. Altere-as antes de expor o Ditto em qualquer lugar. A documentação do Eclipse Ditto descreve as opções de implantação em detalhes.
Passo 2: Crie uma Thing
Crie um gêmeo para uma bomba, por exemplo a de uma estação de tratamento de água de uma companhia de saneamento. Quando você cria uma thing sem uma política explícita, o Ditto cria uma política padrão que concede acesso total ao sujeito autenticado, que na configuração com nginx é nginx:ditto.
curl -u ditto:ditto -X PUT -H "Content-Type: application/json" \
http://localhost:8080/api/2/things/acme:pump-01 \
-d '{
"attributes": { "site": "plant1", "line": "water", "model": "CP-200" },
"features": {
"flow": { "properties": { "value": 0, "unit": "l/min" } },
"pressure": { "properties": { "value": 0, "unit": "bar" } },
"motor": { "properties": { "running": false } }
}
}'
Leia-a de volta com curl -u ditto:ditto http://localhost:8080/api/2/things/acme:pump-01.
Passo 3: Adicione uma Conexão MQTT
Agora diga ao Ditto para se conectar ao broker. O exemplo abaixo usa MQTT 5 no servidor MQTT público com um prefixo de topic único. Substitua e3b9 pela sua própria string aleatória.
{
"name": "connectmq-demo",
"connectionType": "mqtt-5",
"connectionStatus": "open",
"uri": "tcp://broker.connectmq.com:1883",
"specificConfig": {
"clientId": "ditto-e3b9",
"separatePublisherClient": "false"
},
"sources": [
{
"addresses": ["connectmq/demo/e3b9/devices/+/telemetry"],
"authorizationContext": ["nginx:ditto"],
"qos": 1,
"payloadMapping": ["telemetry"]
}
],
"targets": [
{
"address": "connectmq/demo/e3b9/twins/{{ thing:name }}/events",
"topics": ["_/_/things/twin/events"],
"authorizationContext": ["nginx:ditto"],
"qos": 0
}
],
"mappingDefinitions": {
"telemetry": {
"mappingEngine": "JavaScript",
"options": {
"incomingScript": "function mapToDittoProtocolMsg(headers, textPayload, bytePayload, contentType) { var name = headers['mqtt.topic'].split('/')[4]; var d = JSON.parse(textPayload); var value = { flow: { properties: { value: d.flow, unit: 'l/min' } }, pressure: { properties: { value: d.pressure, unit: 'bar' } }, motor: { properties: { running: d.running } } }; return Ditto.buildDittoProtocolMsg('acme', name, 'things', 'twin', 'commands', 'merge', '/features', headers, value); }"
}
}
}
}
Salve como connection.json e crie a conexão pela API de conexões com o usuário devops:
curl -u devops:foobar -X POST -H "Content-Type: application/json" \
http://localhost:8080/api/2/connections -d @connection.json
Pontos-chave desta configuração:
separatePublisherClientdefinido como false faz o Ditto usar um único cliente MQTT nas duas direções. Por padrão, o Ditto pode abrir um segundo cliente com um client ID derivado, o que falha em brokers que vinculam client IDs às credenciais emitidas, como o ConnectMQ faz nos brokers de produção.- A origem (source) assina a telemetria de todos os dispositivos com um wildcard de nível único.
- O mapeamento em JavaScript extrai o nome do dispositivo do topic e converte JSON simples em um comando Ditto
mergeem/features, para que os dispositivos nunca precisem conhecer o Ditto Protocol. - O destino (target) publica cada evento de mudança do gêmeo em um topic de eventos por thing.
Em produção, altere a URI para ssl://YOUR_BROKER_HOST:8883, defina clientId como YOUR_CLIENT_ID e acrescente as credenciais do portal do ConnectMQ, por exemplo ssl://YOUR_USERNAME:YOUR_PASSWORD@YOUR_BROKER_HOST:8883.
Passo 4: Publique a Telemetria do Dispositivo
Simule a bomba com mosquitto_pub. O quinto nível do topic é o nome da thing que o script de mapeamento extrai:
mosquitto_pub -h broker.connectmq.com -p 1883 -i pump-01-e3b9 -q 1 \
-t "connectmq/demo/e3b9/devices/pump-01/telemetry" \
-m '{"flow": 418.5, "pressure": 3.7, "running": true}'
Verifique o gêmeo:
curl -u ditto:ditto http://localhost:8080/api/2/things/acme:pump-01/features
Você deve ver os novos valores de vazão, pressão e operação.
Passo 5: Consuma Eventos do Gêmeo via MQTT
Agora qualquer aplicação pode acompanhar as mudanças do gêmeo sem chamar a API do Ditto. Assine o topic de eventos:
mosquitto_sub -h broker.connectmq.com -p 1883 -i events-viewer-e3b9 \
-t "connectmq/demo/e3b9/twins/+/events" -v
Publique outra mensagem de telemetria e um evento do Ditto Protocol aparece, contendo o topic acme/pump-01/things/twin/events/merged, o caminho e o valor alterado. Dashboards e visualizadores 3D podem assinar esses eventos ou se conectar à API WebSocket do Ditto, caso precisem de acesso por gêmeo controlado por políticas.
Considerações de Produção para Eclipse Ditto e MQTT
Passar desta configuração local para produção envolve algumas decisões fáceis de ignorar:
- Credenciais e políticas. Substitua os usuários padrão do nginx pelo seu provedor de identidade e crie políticas explícitas por thing ou por grupo de things, em vez de depender da política padrão. O authorization context da conexão deve ser um sujeito dedicado, apenas com as permissões necessárias.
- Contratos de topics. Documente o layout de topics que o script de mapeamento espera. Se o firmware dos dispositivos mudar a profundidade do topic, a extração baseada em índice do script quebra silenciosamente, então valide as entradas e registre as mensagens rejeitadas.
- Vazão. O Ditto persiste cada modificação do gêmeo. Alimentá-lo com cada amostra de alta frequência é desperdício; deixe os dispositivos publicarem na mudança ou em uma taxa moderada e envie os dados em taxa total para um assinante de séries temporais separado.
- Estado desejado. Se as aplicações definirem
desiredProperties, acrescente um target que publique essas mudanças em um topic de comando do dispositivo e faça os dispositivos reportarem de volta pelo mesmo caminho de telemetria. - Monitoramento. Acompanhe o status da conexão e a atividade de topics do broker em conjunto, para saber se um gêmeo desatualizado é causado pelo dispositivo, pelo broker ou pelo mapeamento.
Solução de Problemas em Conexões Eclipse Ditto MQTT
| Sintoma | Causa provável | Correção |
|---|---|---|
| O status da conexão continua como falha | Esquema de URI ou porta incorretos | Use tcp:// com 1883 ou ssl:// com 8883 |
| A conexão cai logo após conectar | Client ID duplicado ou não autorizado | Defina um clientId único, desative o publisher client separado |
| Mensagens recebidas, mas o gêmeo não é atualizado | Authorization context não está na política da thing | Faça o authorizationContext corresponder a um sujeito da política |
| Erros de mapeamento nos logs | O script lança exceção com payload inesperado | Proteja contra campos ausentes e JSON inválido |
| Nenhum evento no topic de destino | Filtro topics do target ausente |
Inclua _/_/things/twin/events |
Obtenha os diagnósticos da conexão com GET /api/2/connections/{connectionId}/status e /logs, depois de habilitar o logging pelo endpoint de comandos da conexão.
Quando Usar o Ditto vs Topics Retidos
O Ditto acrescenta um serviço de gêmeo com APIs, políticas, busca e histórico de mudanças. Se você só precisa que os visualizadores carreguem o estado atual, topics MQTT retidos podem ser suficientes e não exigem infraestrutura extra; veja gêmeo digital com retained MQTT. Escolha o Ditto quando precisar de consultas em muitos gêmeos, controle de acesso granular por gêmeo, propriedades desejadas ou uma API REST para aplicações de negócio. Para ver onde cada um se encaixa em uma stack completa, leia arquitetura de gêmeo digital.
Rode o Eclipse Ditto no ConnectMQ
O Ditto cuida dos gêmeos; o ConnectMQ cuida da mensageria. Como broker MQTT na nuvem com MQTT 3.1.1 e 5.0, TLS na porta 8883 e um explorador de topics ao vivo para acompanhar telemetria e eventos do Ditto lado a lado, ele elimina o trabalho de operar seu próprio broker. Cadastre-se em app.connectmq.com, crie um broker no plano Serverless gratuito, sem cartão de crédito, e use as credenciais dele na sua conexão do Ditto.
Perguntas frequentes
O Eclipse Ditto inclui um broker MQTT?
Não. O Ditto se conecta a um broker MQTT externo como cliente por meio do seu serviço de conectividade, então você escolhe e opera o broker separadamente ou usa um broker MQTT gerenciado.
O Ditto pode usar MQTT 5?
Sim. Defina connectionType como mqtt-5 para MQTT 5 ou mqtt para MQTT 3.1.1.
Os dispositivos precisam enviar mensagens no Ditto Protocol?
Não. Com um mapeamento de payload como o exemplo em JavaScript acima, os dispositivos podem publicar JSON simples e o Ditto o converte em comandos do gêmeo.
Como enviar valores desejados do Ditto para os dispositivos?
Atualize desiredProperties em uma feature e acrescente um target que publique essas mudanças, ou envie live messages, para um topic de comando que o dispositivo assina.
