Eclipse Ditto™
-
an introduction
01/2023
Digital Twins
- digital representation of physical devices
- twin as broker for communicating with assets
- applicable for both industrial and consumer-centric IoT scenarios
Twins in scope of Ditto
- a pattern for working with things in the IoT
- provide state persistence and search capabilities
- access twins always in an authorized way
- provide APIs - Device as a Service
- optionally normalize device payloads
Eclipse Ditto in context
Ditto as
Digital Twin
"middleware"
turn device data into APIs
{
"thingId": "io.foo:car1",
"policyId": "io.foo:car1",
"attributes": {
"manufacturer": "Foo",
"data": {
"serialNo": 4711
}
},
"features": {
"temp": {
"properties": {
"value": 23.42
}
}
}
}JSON repr. of a Thing
GET/PUT/DELETE /api/2/things/io.foo:car1
/api/2/things/io.foo:car1/thingId
/api/2/things/io.foo:car1/policyId
/api/2/things/io.foo:car1/attributes
/api/2/things/io.foo:car1/attributes/manufacturer
/api/2/things/io.foo:car1/attributes/data
/api/2/things/io.foo:car1/attributes/data/serialNo
/api/2/things/io.foo:car1/features
/api/2/things/io.foo:car1/features/temp
/api/2/things/io.foo:car1/features/temp/properties
/api/2/things/io.foo:car1/features/temp/properties/value
HTTP API of the Thing
→ docsmodeling thing capabilities
- by default, thing attributes and feature properties are "schemaless"
- a thing may be aware of one "definition"
- a feature may be aware of several "definitions"
{ "thingId": "io.foo:lamp-1", "policyId": "io.foo:lamp-1", "definition": "https://some.domain/floor-lamp-1.0.0.tm.jsonld", "attributes": { "Manufacturer": "Foo corp", "serialNo": "4711" }, "features": { "Spot1": { "definition": [ "https://some.domain/dimmable-colored-lamp-1.0.0.tm.jsonld", "https://some.domain/colored-lamp-1.0.0.tm.jsonld", "https://some.domain/switchable-1.0.0.tm.jsonld" ], "properties": { "on": true, "color": {... } } } } }
{ "thingId": "io.foo:lamp-1", "policyId": "io.foo:lamp-1", "definition": "https://some.domain/floor-lamp-1.0.0.tm.jsonld", "attributes": { "Manufacturer": "Foo corp", "serialNo": "4711" }, "features": { "Spot1": { "definition": [ "https://some.domain/dimmable-colored-lamp-1.0.0.tm.jsonld", "https://some.domain/colored-lamp-1.0.0.tm.jsonld", "https://some.domain/switchable-1.0.0.tm.jsonld" ], "properties": { "on": true, "color": {... } } } } }
{ "thingId": "io.foo:lamp-1", "policyId": "io.foo:lamp-1", "definition": "https://some.domain/floor-lamp-1.0.0.tm.jsonld", "attributes": { "Manufacturer": "Foo corp", "serialNo": "4711" }, "features": { "Spot1": { "definition": [ "https://some.domain/dimmable-colored-lamp-1.0.0.tm.jsonld", "https://some.domain/colored-lamp-1.0.0.tm.jsonld", "https://some.domain/switchable-1.0.0.tm.jsonld" ], "properties": { "on": true, "color": {... } } } } }
modeling thing capabilities
- integration of W3C Web of Things (WoT) standard
- reference in "definition" to WoT TMs (Thing Models)
- let Ditto automatically generate WoT TDs (Thing Descriptions) containing API endpoints and data formats + semantic annotations
persistence of device state
- devices are not always connected to the net
- applications always need to be able to access their data
- twin vs. live access on API level
authorization
- Ditto contains a built-in authorization mechanism (Policies)
- every API call is authorized
{
"policyId": "io.foo:car1-policy",
"entries": {
"owner": {
"subjects": {
"oidc:userid": {
"type": "OpenID connect extracted userid"
},
"oidc:/claim": {
"type": "OpenID connect extracted claim"
}
},
"resources": {
"thing:/": {
"grant": ["READ","WRITE"],
"revoke": []
},
"thing:/features/firmware": {
"grant": [],
"revoke": ["WRITE"]
},
"policy:/": {
"grant": ["READ","WRITE"],
"revoke": []
}
}
}
}
}search
- you must not
- Ditto has you covered
GET /api/2/search/things
?filter=like(attributes/manufacturer,"Foo*")GET /api/2/search/things
?filter=and(
eq(features/*/definition,"https://some.domain/switchable-1.0.0.tm.jsonld"),
like(attributes/manufacturer,"Foo*"),
not(gt(attributes/counter,42))
)
&fields=thingId,attributes/manufacturer,features/*/properties/on- search for arbitrary data with RQL query
- Ditto again ensures authorization
- apply field projection over the results
- don't worry about indexing
get notified about changes
- notification via various channels: WebSocket, SSE, MQTT (3.1.1 | 5), AMQP (0.9.1 | 1.0), Apache Kafka, HTTP hook
- server side filtering via RQL (same as in search)
payload normalization
- devices send data in various formats
- Ditto provides structured APIs of things (attributes, features)
- devices don't need to be aware of Ditto
- incoming and outgoing data can be transformed
nonfunctional
- modular architecture of Ditto services
- horizontal scalability of each Ditto service
- runtime dependency to MongoDB
- included monitoring (JVM metrics, roundtrips, MongoDB)
- codebase written in: Java
Demo
Links
- Ditto Blogpost about WoT integration
- Ditto docs about WoT integration
- GitHub - please give us a star ;)
- Chatroom to ask more questions
Eclipse Ditto™ - an introduction 01/2023