Manufacturing floors, wind farms, and smart buildings share a common challenge: keeping physical assets running smoothly before they break down. Digital twins offer a solution by creating virtual replicas of physical equipment that mirror real-world conditions in real-time. Eclipse Ditto provides an open-source framework that makes this concept practical and scalable.
What Is Eclipse Ditto?
Eclipse Ditto is a lightweight framework for building digital twin solutions. It manages the state of physical devices and assets through a simple API, handling the complex synchronization between the physical and digital worlds. Rather than building twin infrastructure from scratch, Ditto provides ready-made components for device modeling, state management, and real-time updates.
The framework uses the concept of “Things” – digital representations of physical assets with attributes, features, and metadata. Each Thing maintains its state independently while Ditto handles communication, persistence, and access control.
Building a Predictive Maintenance Model
Let’s model a industrial pump that requires maintenance monitoring. The digital twin tracks operational parameters that indicate potential failures.
Defining the Thing:
{
"thingId": "com.factory:pump-01",
"policyId": "com.factory:default-policy",
"attributes": {
"location": "Building A - Floor 2",
"manufacturer": "AcmePumps",
"installDate": "2023-01-15",
"model": "HP-500"
},
"features": {
"temperature": {
"properties": {
"value": 65.5,
"unit": "celsius",
"status": "normal"
}
},
"vibration": {
"properties": {
"value": 2.1,
"unit": "mm/s",
"status": "warning"
}
},
"pressure": {
"properties": {
"value": 4.2,
"unit": "bar",
"status": "normal"
}
},
"operatingHours": {
"properties": {
"value": 12450,
"lastMaintenance": 11000
}
}
}
}
This structure separates static attributes from dynamic features. The features update frequently as sensors report new values, while attributes remain relatively constant.
Implementing Predictive Logic
Ditto doesn’t enforce how you implement predictions – it provides the infrastructure to act on data. Your predictive maintenance system reads from Ditto and writes back maintenance alerts.
Using Ditto’s Search API:
// Find all pumps with warning indicators GET /api/2/search/things?filter=or( eq(features/vibration/properties/status,"warning"), gt(features/temperature/properties/value,75), gt(features/operatingHours/properties/value,15000) )
This query identifies assets approaching maintenance thresholds. The search capabilities let maintenance systems monitor entire fleets without polling individual devices.
Real-Time Updates with Live Messages
Ditto supports bidirectional messaging between devices and applications. When a sensor detects an anomaly, it sends a message through Ditto to trigger immediate actions.
POST /api/2/things/com.factory:pump-01/inbox/messages/alert
{
"topic": "com.factory/pump-01/things/live/messages/alert",
"headers": {
"content-type": "application/json"
},
"value": {
"severity": "high",
"reason": "Vibration exceeds threshold",
"timestamp": "2025-10-10T14:30:00Z"
}
}
Maintenance applications subscribe to these messages and respond accordingly – creating work orders, notifying technicians, or adjusting operational parameters automatically.
Integrating with Analytics
Digital twins become powerful when connected to analytics pipelines. Ditto’s connection framework integrates with MQTT brokers, Apache Kafka, and HTTP endpoints.
A typical flow:
- Sensors push data to Ditto via MQTT
- Ditto updates the Thing state
- Connections forward changes to your analytics platform
- Machine learning models detect patterns
- Predictions write back to the Thing’s features
- Applications query Ditto for maintenance recommendations
This architecture keeps your predictive models separate from device management while maintaining a single source of truth.
Handling Historical Context
Predictive maintenance relies on trends, not just current values. While Ditto focuses on current state, you’ll typically pair it with a time-series database.
Configure a connection to persist state changes:
{
"name": "timescale-connection",
"connectionType": "http-push",
"uri": "https://timescale.example.com/api/ingest",
"sources": [],
"targets": [{
"address": "POST:/things",
"topics": ["_/_/things/twin/events"],
"authorizationContext": ["integration:timescale"]
}]
}
Now every state change flows to your historical database while Ditto maintains the current snapshot.
Security and Access Control
Industrial systems require granular permissions. Ditto’s policy system controls who can read or modify which aspects of a Thing.
{
"policyId": "com.factory:pump-policy",
"entries": {
"maintenance-team": {
"subjects": {
"integration:maintenance-app": { "type": "app" }
},
"resources": {
"thing:/": { "grant": ["READ"], "revoke": [] },
"thing:/features/operatingHours": { "grant": ["WRITE"], "revoke": [] }
}
}
}
}
The maintenance team can read all data but only update specific fields relevant to their operations.
Scaling Across Assets
The real value emerges when managing thousands of assets. Ditto handles this through efficient indexing and MongoDB-backed persistence. Each Thing operates independently, so adding assets doesn’t create bottlenecks.
For fleet-wide maintenance optimization, query across asset types:
// Find all equipment due for maintenance this month
GET /api/2/search/things?filter=and(
like(thingId,"com.factory:*"),
gt(features/operatingHours/properties/value,
sub(features/operatingHours/properties/lastMaintenance,1000))
)
Getting Started
Eclipse Ditto runs in Docker, making local development straightforward. The basic deployment includes the Ditto services, MongoDB, and Nginx for API routing.
A minimal approach:
- Deploy Ditto locally using Docker Compose
- Model one critical asset as a Thing
- Connect real sensors or simulate data updates
- Build a simple dashboard querying Ditto’s API
- Add predictive rules based on your domain knowledge
- Expand to more assets and sophisticated analytics
The framework handles the complexity of state synchronization, letting you focus on maintenance logic specific to your equipment.
Useful Resources
- Eclipse Ditto Documentation:
https://www.eclipse.dev/ditto/ - Getting Started Guide:
https://www.eclipse.dev/ditto/intro-overview.html - HTTP API Reference:
https://www.eclipse.dev/ditto/http-api-doc.html - GitHub Repository:
https://github.com/eclipse-ditto/ditto - Docker Deployment:
https://www.eclipse.dev/ditto/installation-running.html - Community and Support:
https://www.eclipse.dev/ditto/feedback.html
