Eclipse IoT Eclipse Ditto

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 in action

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

→ docs

modeling 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": {...
        }
      }
    }
  }
}
→ docs

modeling thing capabilities

W3C Web of Things logo
  • 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
Ditto twin channel Ditto live channel

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": []
          }
        }
      }
    }
  }
→ docs

search


Meme Dino
  • 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
→ docs

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
JavaScript logo
  • incoming and outgoing data can be transformed

nonfunctional


Ditto context overview
  • 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

Ditto UI Screenshot

Links