Eclipse Ditto Blog

Announcing Eclipse Ditto Release 3.9.0

Wed, 13 May 2026 00:00:00 +0000

Eclipse Ditto team is excited to announce the availability of a new minor release, including new features: Ditto 3.9.0.

The focus of this release is on policies, multi-tenancy and reuse. Operating Ditto for several tenants sharing one cluster — or for organizations that want to apply consistent governance and audit rules across many policies — has historically required either duplicating policy entries across every tenant’s policy or maintaining ad-hoc policy templates outside Ditto. Ditto 3.9.0 brings these patterns into the platform itself with three complementary building blocks:

Namespace-scoped policy entries let a single policy carry entries that only apply to Things in specific namespaces — so a tenant’s policy can be expressed as a small set of namespace-aware rules instead of as separate policies per tenant.
Namespace root policies let operators configure policies that are transparently merged into every policy of a given namespace, without each policy author having to opt in. This is the natural home for cross-tenant concerns: governance and audit READ access, compliance monitoring, break-glass SRE accounts, or forced minimum logging.
Entry-level references for policies and policy imports replace duplicated subject/resource blocks with a uniform mechanism for additively merging from other entries — both inside the same policy and from imported “template” policies. Imported entries can declare exactly what kinds of additions (subjects, resources, namespaces) referencing entries are allowed to contribute via allowedAdditions, and transitiveImports opt selected imports in to multi-level resolution. The new resolved policy view (policy-view=resolved) returns the merged effective policy after imports and namespace-root resolution, which makes debugging effective permissions much easier.

To round off the multi-tenancy story, gateway-level namespace access control restricts which namespaces an authenticated request may touch — for example by matching a JWT claim — so that a token issued for one tenant cannot reach Things in another tenant’s namespace.

Beyond policies, this release also brings a new WoT Discovery “Thing Directory” endpoint, dynamically scoping a WoT Thing Description to the requesting user’s permissions, partial change notifications based on Policy READ permissions, the checkPermissions API for all protocols (WebSocket, AMQP, MQTT — not only HTTP), encryption key rotation for connection secrets, an empty() RQL filter, the fn:format() placeholder pipeline function, slow search query logging, configurable custom MongoDB search indexes, per-namespace activity-check configuration, a history exploration mode in the Explorer UI and quite a number of further enhancements.

On the operations side, Ditto now builds and runs on Java 25, and the bundled Helm chart no longer ships an ingress-nginx controller — the choice of ingress controller is left to the operator. To reflect this breaking change, the Helm chart moves to a major version 4.0.0, and from now on the chart follows its own semantic versioning, decoupled from Ditto’s appVersion. Chart-only changes will increment the chart version independently of the Ditto release cycle.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.9.0 are:

Namespace-scoped policy entries to limit a policy entry’s scope to a configured set of Thing namespaces
Namespace root policies which are transparently merged into all policies of a configured namespace
Limiting which namespaces are accessible at the gateway level via configurable, placeholder-based rules
Entry-level references in policies and policy imports, with transitiveImports for selective multi-level resolution and allowedAdditions to control what may be merged in
Resolved policy view API option returning the merged effective policy after imports and namespace-root resolution
Partial change notifications based on Policy READ permissions
checkPermissions API for all protocols — previously only HTTP — making permission checks available via WebSocket, AMQP and MQTT
WoT Discovery “Thing Directory” endpoint following the W3C WoT Discovery specification
Dynamically scoping a WoT Thing Description to the requesting user’s policy permissions
Encryption key rotation for connectivity service secrets, including DevOps-triggered re-encryption of stored credentials
X509 client-certificate authentication to MongoDB, with a configurable CA root certificate for the TLS connection
empty() RQL filter to match absent or empty fields in search and event filters
fn:format() placeholder pipeline function for correlated field extraction from JSON arrays
Slow search query logging with configurable threshold to identify expensive queries
Configurable custom MongoDB search indexes for tuning Ditto search to specific workloads
Per-namespace activity-check configuration to vary entity passivation timeouts per namespace
Live entities Prometheus metric per namespace and entity type
OpenID Connect prerequisite-conditions for early JWT rejection (e.g. audience validation)
Local/relative tm:ref references in WoT ThingModel resolution
ditto:deprecationNotice WoT extension term to mark deprecated properties, actions and events
“Time Travel” mode in the Explorer UI to inspect a Thing’s state at any past revision or timestamp, alongside live and historical event browsing

The following non-functional work is also included:

Building and running Ditto with Java 25
Optimizing the MongoReadJournal aggregation pipelines and the ThingEventEnricher hot path
JFR-guided CPU optimisations in the things, things-search, gateway and connectivity services
Stackless 4xx exceptions (feature-toggled) to eliminate stack-capture overhead on flow-control errors
Configurable SSE publisher backpressure buffer size to suppress noisy backpressure WARN logs from slow SSE consumers
Comprehensive JavaDoc for the public WoT model interfaces
Helm chart bumped to 4.0.0 with the bundled ingress-nginx controller removed — operators provide their own ingress controller; the chart now uses its own semantic version, decoupled from Ditto’s appVersion
Updating dependencies to their latest versions
Providing additional configuration options to Helm values

The following notable fixes are included:

Surfacing enforcement and validation errors for fire-and-forget commands instead of silently swallowing them
Fixing checkPermissions ignoring permissions inherited from imported policies
Fixing partial-access SSE event filtering for subscribers with multiple authorization subjects
Fixing a MongoDB aggregation pipeline performance regression affecting connections_journal reads
Fixing a Kafka consumer crash loop triggered by messages with blank header values
Fixing a Fluency thread leak in the connection logger publisher
Fixing subscription handling for multiple topics combined with extra fields in connectivity outbound mapping
Redacting sensitive header values in DittoHeaders.toString() to prevent accidental log leaks
Converting transient enforcement AskTimeoutException to HTTP 503 instead of 500 during rolling restarts, so clients see a retryable error
Fixing ssl-config not being picked up for self-signed certificates against the OpenID Connect issuer
Closing a shadowing vulnerability in namespace-policies by routing namespace-policy entries through rewritten labels

Please have a look at the 3.9.0 release notes for more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team

Helm chart now ingress controller agnostic

Wed, 13 May 2026 00:00:00 +0000

Starting with Helm chart version 4.0.0, Eclipse Ditto’s Kubernetes deployment is no longer tied to a specific ingress controller. The chart now provides clean, standard Kubernetes Ingress resources that work with any ingress controller — whether you use ingress-nginx, Traefik, HAProxy, Kong, or any other implementation.

What changed

Previously, the Ditto Helm chart bundled an entire ingress-nginx controller deployment (854 lines of RBAC, Deployments, Services, admission webhooks, and IngressClass) and hardcoded nginx.ingress.kubernetes.io/* annotations across all Ingress resource templates. This forced users to use ingress-nginx and prevented adoption of other ingress controllers.

In version 4.0.0, we made the following changes:

Removed the bundled ingress-nginx controller deployment — users bring their own ingress controller
Removed all nginx-specific annotations from Ingress resources — annotations are now empty by default
Simplified path types to standard Prefix and Exact — no more controller-specific regex paths
Added per-group enabled flags — each route group (api, ws, ui, devops) can be independently toggled
Replaced the backendSuffix pattern with explicit service.name references

Breaking changes

This is a major version bump (3.x → 4.0.0) with breaking changes to values.yaml:

ingress.controller.* — entire block removed (no longer deploying a controller)
ingress.annotations — global nginx-specific annotations removed
ingress.api.kubernetesAuthAnnotations — removed
ingress.className — default changed from "nginx" to "" (empty)
ingress.host — default changed from "localhost" to "" (catch-all)
backendSuffix — replaced by service.name in each path entry
All per-group nginx-specific annotation blocks — removed

New values.yaml structure

The ingress section is now clean and controller-agnostic:

ingress:
  enabled: false
  className: ""        # Set to your controller's IngressClass
  host: ""             # Optional hostname — if empty, no host rule (catch-all)
  tls: []

  api:
    enabled: true
    annotations: {}    # Add your controller-specific annotations here
    paths:
      - path: /api
        pathType: Prefix
        service:
          name: gateway
      - path: /stats
        pathType: Prefix
        service:
          name: gateway
      - path: /overall
        pathType: Prefix
        service:
          name: gateway

  ws:
    enabled: true
    annotations: {}
    paths:
      - path: /ws
        pathType: Prefix
        service:
          name: gateway

  ui:
    enabled: true
    annotations: {}
    # defaultBackend serves as the catch-all for unmatched paths (e.g. the landing page)
    defaultBackend:
      service:
        name: nginx
    paths:
      - path: /
        pathType: Exact
        service:
          name: nginx
      - path: /apidoc
        pathType: Prefix
        service:
          name: swaggerui
      - path: /ui
        pathType: Prefix
        service:
          name: dittoui

  devops:
    enabled: true
    annotations: {}
    paths:
      - path: /devops
        pathType: Prefix
        service:
          name: gateway
      - path: /health
        pathType: Prefix
        service:
          name: gateway
      - path: /status
        pathType: Prefix
        service:
          name: gateway
      - path: /api/2/connections
        pathType: Prefix
        service:
          name: gateway

Deployment modes

The chart supports three deployment modes:

Standalone nginx pod (default, unchanged)

The standalone nginx reverse proxy remains the default for local and development setups. No ingress controller needed — access Ditto via port-forward:

helm install ditto ditto/ditto
kubectl port-forward svc/ditto-nginx 8080:8080

Ingress with nginx pod

Use Ingress resources for external access while keeping the nginx pod for the landing page and static resources:

helm install ditto ditto/ditto \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=ditto.example.com

Ingress only (no nginx pod)

For production setups where the landing page is not needed, disable the nginx pod and the UI ingress’s root path:

helm install ditto ditto/ditto \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=ditto.example.com \
  --set nginx.enabled=false

Controller-specific configuration

Since controller-specific behavior (authentication, CORS, timeouts, URL rewriting) is now the user’s responsibility, here are examples for common ingress controllers.

ingress-nginx

For the Ditto UI and Swagger API docs, ingress-nginx requires regex paths and a rewrite annotation to strip the path prefix before forwarding to the backend.

Note that when use-regex is enabled, the root path / must be specified as /$ with pathType: ImplementationSpecific to ensure it matches only the exact root path and does not conflict with the ingress controller’s default catch-all:

ingress:
  enabled: true
  className: nginx
  host: ditto.example.com
  api:
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "70"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "70"
  ws:
    annotations:
      nginx.ingress.kubernetes.io/proxy-read-timeout: "86400"
      nginx.ingress.kubernetes.io/proxy-send-timeout: "86400"
      nginx.ingress.kubernetes.io/proxy-buffering: "off"
  ui:
    annotations:
      nginx.ingress.kubernetes.io/use-regex: "true"
      nginx.ingress.kubernetes.io/rewrite-target: /$2
    paths:
      - path: /$
        pathType: ImplementationSpecific
        service:
          name: nginx
      - path: /apidoc(/|$)(.*)
        pathType: ImplementationSpecific
        service:
          name: swaggerui
      - path: /ui(/|$)(.*)
        pathType: ImplementationSpecific
        service:
          name: dittoui

Traefik

Traefik requires a Middleware CRD to strip path prefixes. First, create the middleware in the Ditto namespace:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: strip-prefix
  namespace: ditto
spec:
  stripPrefix:
    prefixes:
      - /ui
      - /apidoc

Then reference it in the ingress configuration:

ingress:
  enabled: true
  className: traefik
  host: ditto.example.com
  ui:
    annotations:
      traefik.ingress.kubernetes.io/router.middlewares: ditto-strip-prefix@kubernetescrd

HAProxy

ingress:
  enabled: true
  className: haproxy
  host: ditto.example.com
  ui:
    annotations:
      haproxy.org/path-rewrite: "/ /"

What stays the same

The standalone nginx pod for local/development deployments is unchanged
The OpenShift Route template is unchanged
All Ditto service templates (gateway, things, policies, connectivity, etc.) are unchanged
The 4 route groups (api, ws, ui, devops) cover all Ditto endpoints — the root landing page is now part of the ui group

Migrating from 3.x

Install your ingress controller separately (e.g., via its own Helm chart)
Update your values.yaml to match the new structure — replace backendSuffix with service.name, remove ingress.controller.* and global annotations
Add controller-specific annotations to the appropriate route groups
Upgrade the chart to version 4.0.0

–
The Eclipse Ditto team

WoT Tooling: Code Generation and OpenAPI from Thing Models

Mon, 02 Feb 2026 00:00:00 +0000

Eclipse Ditto’s W3C WoT (Web of Things) integration lets you reference Thing Models in Thing Definitions, generate Thing Descriptions, and create Thing skeletons at runtime. Alongside that, the ditto-wot-tooling project provides build-time and CLI tools to generate Kotlin code and OpenAPI specifications from the same WoT Thing Models.

This post gives an overview of the available tools, their configuration, and some best practices so the Ditto community can use them effectively.

Overview of ditto-wot-tooling

The ditto-wot-tooling repository hosts two main tools:

Tool	Purpose
WoT Kotlin Generator	Maven plugin that downloads a WoT Thing Model (JSON-LD) via HTTP and generates Kotlin data classes and path helpers for type-safe use in your application.
WoT to OpenAPI Generator	Converts WoT Thing Models into OpenAPI 3.1.0 specifications that describe Ditto’s HTTP API for Things conforming to that model. Usable as CLI or library.

Both tools consume Thing Models from a URL (e.g. a deployed model registry). They complement Ditto’s runtime WoT support: Ditto fetches Thing Models (TMs) to build skeletons and Thing Descriptions; the tooling uses the same TMs at build time or in CI to generate client code and API docs.

WoT Kotlin Generator Maven plugin

The WoT Kotlin Generator produces Kotlin code (data classes, builders, path DSL) from a single Thing Model URL. The generated code aligns with Ditto’s API and can be used to build merge commands, RQL filters, and path references in a type-safe way.

Why use generated models?

Using the Kotlin generator gives you a single source of truth: your backend models are derived directly from the WoT Thing Models, which act as the schema for your Things. Ditto supports WoT-based validation of Things and Features against the referenced Thing Model. If you maintain models by hand, they can drift from the WoT schema and become incompatible—leading to validation errors at runtime, failed updates, or subtle bugs. Generated models stay in sync with the Thing Model you point the plugin at, so the payloads you build are valid by construction. That makes development easier, safer, and more predictable: you get compile-time safety and alignment with Ditto’s validation instead of discovering mismatches only when Ditto rejects a request.

Maven setup

Add the common-models dependency (required by the generated code) and the plugin to your pom.xml:

<dependency>
    <groupId>org.eclipse.ditto</groupId>
    <artifactId>wot-kotlin-generator-common-models</artifactId>
    <version>1.0.0</version>
</dependency>

<plugin>
    <groupId>org.eclipse.ditto</groupId>
    <artifactId>wot-kotlin-generator-maven-plugin</artifactId>
    <version>1.0.0</version>
    <executions>
        <execution>
            <id>code-generator-my-model</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>codegen</goal>
            </goals>
            <configuration>
                <thingModelUrl>${modelBaseUrl}/my-domain/my-model-${my-model.version}.tm.jsonld</thingModelUrl>
                <packageName>com.example.wot.model.mymodel</packageName>
                <classNamingStrategy>ORIGINAL_THEN_COMPOUND</classNamingStrategy>
            </configuration>
        </execution>
    </executions>
</plugin>

Full plugin configuration options

Parameter	Type	Required	Default	Description
`thingModelUrl`	String	Yes	-	Full HTTP(S) URL of the WoT Thing Model (JSON-LD). The plugin downloads it at build time.
`packageName`	String	No	`org.eclipse.ditto.wot.kotlin.generator.model`	Target package for generated Kotlin classes.
`outputDir`	String	No	`target/generated-sources`	Directory where generated sources are written (Maven adds it as a source root).
`enumGenerationStrategy`	String	No	`INLINE`	How to generate enums: `INLINE` (nested in the class that uses them) or `SEPARATE_CLASS` (standalone enum classes).
`classNamingStrategy`	String	No	`COMPOUND_ALL`	How to name generated classes: `COMPOUND_ALL` (e.g. `RoomAttributes`, `BatteryProperties`) or `ORIGINAL_THEN_COMPOUND` (use schema title when possible, compound only on conflict).
`generateSuspendDsl`	boolean	No	`false`	If `true`, generated DSL builder functions are `suspend` functions for Kotlin coroutines.

Use Maven properties for the base URL and model version so you can switch environments and pin versions in one place:

<properties>
    <modelBaseUrl>https://models.example.com</modelBaseUrl>
    <my-model.version>1.0.0</my-model.version>
</properties>

Enum and class naming strategies

Enum generation

INLINE (default): Enums are nested inside the class that uses them (e.g. Thermostat.ThermostatStatus). Keeps the number of files lower and is convenient for simple enums.
SEPARATE_CLASS: Enums are generated as standalone classes in separate files. Better for IDE navigation and reuse across multiple classes.

Class naming

COMPOUND_ALL (default): Class names always combine parent and child (e.g. SmartheatingThermostat, RoomAttributes). Guarantees unique names and makes hierarchy clear.
ORIGINAL_THEN_COMPOUND: Uses the schema title when there is no conflict (e.g. Thermostat); falls back to compound names (e.g. SmartheatingThermostat) when needed. Produces shorter, more readable names when possible.

DSL: regular vs suspend

By default, the plugin generates regular Kotlin DSL functions for building thing/feature/property objects. Set generateSuspendDsl=true to generate suspend DSL functions instead, so you can use them inside coroutines and call suspend code from within the DSL block.

Generated code structure

The plugin generates a package structure aligned with your Thing Model:

Main thing class – root class for the thing (e.g. FloorLamp, Device).
attributes/ – interfaces/classes for thing-level attributes (e.g. Location, Room).
features/ – one subpackage per feature with feature and property types (e.g. lamp/Lamp.kt, LampProperties.kt).
DSL functions – fluent builders (e.g. floorLamp { ... }, features { lamp { ... } }).
Path and RQL helpers – provided by the common-models dependency; the generated code uses them for type-safe paths and RQL expressions.

You must add the wot-kotlin-generator-common-models dependency to your project; the generated code extends interfaces and uses path builders from that artifact.

What the generator supports

The plugin follows the WoT Thing Model specification: it handles properties (read/write, various types), actions (with input/output schemas), events, and links (e.g. tm:extends, tm:submodel). Supported data types include primitives (string, number, integer, boolean), object, array, and custom types via $ref. Enums in the schema become Kotlin enums according to enumGenerationStrategy.

Best practices

Pin model versions in pom.xml (or a BOM) so builds are reproducible and you can upgrade TMs in a controlled way.
One execution per “logical” model: use a separate <execution> for each Thing Model you need (e.g. device, room, building). Each execution has its own thingModelUrl and packageName.
Align with runtime definitions: use the same base URL and versioning as the Thing Definition URLs you send to Ditto, so the generated types match what Ditto expects.
Add the common-models dependency: the generated code depends on wot-kotlin-generator-common-models for path building and Ditto RQL helpers; do not omit it.

Running the plugin from the command line

You can invoke the plugin directly without a full POM execution by passing parameters with -D:

mvn org.eclipse.ditto:wot-kotlin-generator-maven-plugin:codegen \
  -DthingModelUrl=https://models.example.com/device-1.0.0.tm.jsonld \
  -DpackageName=com.example.wot.model.device \
  -DoutputDir=target/generated-sources \
  -DenumGenerationStrategy=SEPARATE_CLASS \
  -DclassNamingStrategy=ORIGINAL_THEN_COMPOUND

Optional: -DgenerateSuspendDsl=true for suspend DSL. Useful for one-off generation or scripts.

Path generation and type-safe RQL

The common-models dependency provides a path builder API that works with the generated classes. You get compile-time–safe paths and RQL expressions instead of string concatenation.

Path builder API

pathBuilder().from(start = SomeClass::property) – start a path from a property (e.g. Thing::features, Device::attributes).
.add(NextClass::property) – append path segments (e.g. Features::thermostat, Attributes::location).
.build() – finalize as a path string (e.g. for logging or custom use).
.buildSearchProperty() – create a search property object for RQL comparisons (see below).
.buildJsonPointer() – build a Ditto JSON Pointer (e.g. for MergeThing, DeleteAttribute). Useful when the generated model exposes a startPath (e.g. Location::startPath) for a nested type.

RQL combinators

Use these from DittoRql.Companion to combine conditions:

and(condition1, condition2, ...) – all conditions must hold.
or(condition1, condition2, ...) – at least one condition must hold.
not(condition) – negate a condition.

Each condition is often a search property expression (see below). Call .toString() on the result to get the RQL string for Ditto’s search API or conditional request headers.

Search property methods

After .buildSearchProperty() you can chain one of:

Method	RQL	Example
`exists()`	property exists	`.exists()`
`eq(value)`	equals	`.eq("THERMOSTAT")`
`ne(value)`	not equal	`.ne(0)`
`gt(value)`	greater than	`.gt(20.0)`
`ge(value)`	greater or equal	`.ge(timestamp)`
`lt(value)`	less than	`.lt(timestamp)`
`le(value)`	less or equal	`.le("2026-02-20T08:00:00Z")`
`like(pattern)`	wildcard `?` / `*`	`.like("room-*")`
`ilike(pattern)`	case-insensitive like	`.ilike("sensor")`
`in(values)`	value in collection	`.in(listOf("A", "B"))`

Example: conditional merge (RQL for Ditto headers)

Typical use is building a condition for Ditto’s conditional request header (e.g. for merge or delete). Below, we require that the thing has a given attribute type and either no mountedOn or mountedOn less than or equal to a timestamp:

import com.example.wot.model.path.DittoRql.Companion.and
import com.example.wot.model.path.DittoRql.Companion.or
import com.example.wot.model.path.DittoRql.Companion.not
import com.example.wot.model.path.DittoRql.Companion.pathBuilder

// Condition: type eq "THERMOSTAT" AND
//   (NOT exists(location/mountedOn) OR location/mountedOn <= eventDate)
val updateCondition = and(
    pathBuilder().from(Device::attributes)
        .add(Attributes::type)
        .buildSearchProperty()
        .eq("THERMOSTAT"),
    or(
        not(
            pathBuilder().from(Device::attributes)
                .add(Attributes::location)
                .add(Location::mountedOn)
                .buildSearchProperty()
                .exists()
        ),
        pathBuilder().from(Device::attributes)
            .add(Attributes::location)
            .add(Location::mountedOn)
            .buildSearchProperty()
            .le(eventDate)
    )
).toString()

// Use in Ditto merge headers
val mergeCmd = MergeThing.withThing(
    thingId,
    thing,
    null,
    null,
    dittoHeaders.toBuilder().condition(updateCondition).build()
)

Example: JSON pointer for DeleteAttribute

For commands that take a JSON pointer (e.g. delete a nested attribute), use the generated startPath and buildJsonPointer():

val deleteLocationAttribute = DeleteAttribute.of(
    thingId,
    pathBuilder().from(Location::startPath).buildJsonPointer(),
    dittoHeaders
)

Example: RQL for search

The same RQL string can be passed to Ditto’s search API (e.g. GET /search/things?filter=...):

val filter = pathBuilder().from(Device::attributes)
    .add(Attributes::location)
    .buildSearchProperty()
    .exists()

dittoClient.searchThings(filter.toString(), ...)

The exact property names and types (Device, Attributes, Location, etc.) come from your Thing Model; the generator produces the matching classes and path helpers so that paths and RQL stay in sync with the model.

WoT to OpenAPI Generator

The WoT to OpenAPI Generator turns a WoT Thing Model into an OpenAPI 3.1.0 YAML (or JSON) that describes Ditto’s HTTP API for Things that follow that model: thing and attribute paths, feature properties, and actions (e.g. inbox messages).

Benefits for frontends and API consumers

The generated OpenAPI spec is a standard, tool-friendly contract. Frontend teams can feed it into code generators (e.g. OpenAPI Generator, Orval, or the OpenAPI TypeScript/JavaScript generators) to generate TypeScript or JavaScript models, typed HTTP client methods, and request/response types for thing, attribute, feature, and action endpoints. That keeps the UI in sync with the backend: API changes are reflected in the spec, and regenerating client code updates types and calls in one step. You get autocomplete, fewer manual typos, and consistent request shapes. The same spec can drive API documentation (e.g. Swagger UI or Redoc), integration tests, or other clients (mobile, scripts). One Thing Model (TM) thus drives both backend Kotlin models and frontend API usage from a single source of truth.

Usage

The generator is available as a CLI (run with java -jar) or as a library. You can get the JAR from Maven Central or build from source.

Command-line:

java -jar wot-to-openapi-generator-1.0.0.jar <model-base-url> <model-name> <model-version> [ditto-base-url]

Argument	Description
`model-base-url`	Base URL where the TM is served (e.g. `https://models.example.com`).
`model-name`	Model name (e.g. `dimmable-colored-lamp`). The generator will load `{model-base-url}/{model-name}-{model-version}.tm.jsonld`.
`model-version`	Version (e.g. `1.0.0`).
`ditto-base-url`	(Optional) Base URL of the Ditto API (e.g. `https://ditto.example.com/api/2/things`). Used in the generated `servers` section.

Example:

java -jar wot-to-openapi-generator-1.0.0.jar \
  https://eclipse-ditto.github.io/ditto-examples/wot/models/ \
  dimmable-colored-lamp \
  1.0.0 \
  https://ditto.example.com/api/2/things

Generated specs are written under a generated/ directory (path may vary by version). The output includes thing-level and attribute-level endpoints, feature properties, and action endpoints with request/response schemas derived from the TM.

Best practices

Run in CI: generate OpenAPI from your main Thing Models in your pipeline and publish the artifacts (e.g. to a docs site or S3) so API consumers always see up-to-date specs.
Use the same model base URL and versions as in your Kotlin generator and Ditto Thing definitions, so docs and code stay in sync.
Set ditto-base-url when you want the generated servers section to point at your Ditto instance; otherwise the generator may use a default.

Summary

ditto-wot-tooling provides the WoT Kotlin Generator (Maven plugin) and the WoT to OpenAPI Generator (CLI/library). Both take a WoT Thing Model URL and produce artifacts you can use at build time or in CI.
WoT Kotlin Generator: configure thingModelUrl, packageName, outputDir, enumGenerationStrategy (INLINE / SEPARATE_CLASS), classNamingStrategy (COMPOUND_ALL / ORIGINAL_THEN_COMPOUND), and optionally generateSuspendDsl; pin model versions; add one execution per model; depend on wot-kotlin-generator-common-models. The generated code plus common-models give you type-safe path building (e.g. pathBuilder().from().add().buildSearchProperty()) and RQL combinators (and, or, not) and comparison methods (exists, eq, gt, lt, like, in, etc.) for Ditto search and conditional requests.
WoT to OpenAPI Generator: run with model base URL, model name, and version (and optionally Ditto base URL); integrate into CI to keep API docs aligned with your Thing Models.

For more on WoT in Ditto (definitions, skeleton generation, Thing Descriptions), see the WoT integration documentation and the WoT integration blog post. For the tools themselves, go to eclipse-ditto/ditto-wot-tooling.

Feedback?

Please get in touch if you have feedback or questions about the WoT tooling.

–
The Eclipse Ditto team

Announcing Eclipse Ditto Release 3.8.0

Fri, 10 Oct 2025 00:00:00 +0000

Eclipse Ditto team is excited to announce the availability of a new minor release, including new features: Ditto 3.8.0.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.8.0 are:

Diverting Ditto connection responses to other connections (e.g. to allow multi-protocol workflows)
Dynamically re-configuring WoT validation settings without restarting Ditto
Enforcing that WoT model based thing definitions are used and match a certain pattern when creating new things
Support for OAuth2 “password” grant type for authenticating outbound HTTP connections
Configure JWT claims to be added as information to command headers
Added support for client certificate based authentication for Kafka and AMQP 1.0 connections
Extend “Normalized” connection payload mapper to include deletion events
Support silent token refresh in the Ditto UI when using SSO via OAuth2/OIDC
Enhance conditional updates for merge thing commands to contain several conditions to dynamically decide which parts of a thing to update and which not

The following non-functional work is also included:

Improving WoT based validation performance for merge commands
Enhancing distributed tracing, e.g. with a span for the authentication step and by adding the error response for failed API requests
Updating dependencies to their latest versions
Providing additional configuration options to Helm values

The following notable fixes are included:

Fixing nginx CORS configuration which caused Safari / iOS browsers to fail with CORS errors
Fixing transitive resolving of Thing Models referenced with tm:ref
Fixing sorting on array fields in Ditto search
Fixing issues around “put-metadata” in combination with merge commands
Fixing that certificate chains for client certificate based authentication in Ditto connection was not fully parsed
Fixing deployment of Ditto on OpenShift

Please have a look at the 3.8.0 release notes for a more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team

Response diversion - Multi-protocol workflows made easy

Thu, 09 Oct 2025 00:00:00 +0000

Today we’re excited to announce a powerful new connectivity feature in Eclipse Ditto: Response Diversion. This feature enables sophisticated multiprotocol workflows by allowing responses from one connection to be redirected to another connection instead of being sent to the originally configured reply target.

With response diversion, Eclipse Ditto becomes even more versatile in bridging different IoT protocols and systems, enabling complex routing scenarios that were previously challenging or impossible to achieve.

The challenge: Multi-protocol IoT landscapes

Modern IoT deployments often involve multiple protocols and systems working together. Consider these common scenarios:

Cloud integration: Your devices use MQTT to communicate with AWS IoT Core, but your analytics pipeline consumes data via Kafka
Protocol translation: Legacy systems expect HTTP webhooks, but your devices communicate via AMQP
Response aggregation: You want to collect all device responses in a central monitoring system regardless of the original protocol

Until now, implementing such multiprotocol workflows required complex external routing logic or multiple intermediate systems. Response diversion brings this capability directly into Ditto’s connectivity layer.

How response diversion works

Response diversion is configured at the connection source level using a key in the specific config and special header mapping keys:

{
  "headerMapping": {
    "divert-response-to-connection": "target-connection-id", 
    "divert-expected-response-types": "response,error,nack"
   }, 
    "specificConfig": {
        "is-diversion-source": "true"
    }
}

And in the target connection, by defining a target. In the case of multiple sources one or exactly the same number of sources targets are required. If multiple targets are configured they are mapped to the sources by order. Only diverted responses will be accepted by source connections which ids are defined in the specific config under the key ‘authorized-connections-as-sources’ in a comma separate format.

{
    "id": "target-connection-id-1",
    "targets": [
        {
            "address": "command/redirected/response",
            "topics": [],
            "qos": 1,
            "authorizationContext": [
                "pre:ditto"
            ],
            "headerMapping": {}
        }
    ],
    "specificConfig": {
        "is-diversion-target": "true"
    }
}

  {
    "targets": [
        {
            "address": "command/redirected/response",
            "topics": [],
            "qos": 1,
            "authorizationContext": [
                "pre:ditto"
            ],
            "headerMapping": {}
        }
    ],
    "specificConfig": {
        "is-diversion-target": "true",
        "authorized-connections-as-sources": "target-connection-id-1,..."
    }
}

When a command is received through a source with response diversion configured, Ditto intercepts the response and routes it through the specified target connection instead of the original reply target.

Real-world use case: AWS IoT Core with Kafka

Let’s explore a practical scenario that demonstrates the power of response diversion. In this setup:

Devices communicate with AWS IoT Core via MQTT (bidirectional)
Apache Kafka IoT Core pushes device commands to a Kafka topic
Device commands are consumed from Kafka topics
Responses must go back to AWS IoT Core via MQTT (since IoT Core doesn’t support Kafka consumers)

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  AWS IoT Core   │    │   Kafka Bridge  │    │  Apache Kafka   │    │  Eclipse Ditto  │
│    (MQTT)       │    │   /Analytics    │    │                 │    │                 │
│                 │    │                 │    │                 │    │                 │
│ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │    │ ┌─────────────┐ │
│ │Device       │ │───▶│ │MQTT→Kafka   │ │───▶│ │device-      │ │───▶│ │Kafka Source │ │
│ │Commands     │ │    │ │Bridge       │ │    │ │commands     │ │    │ │Connection   │ │
│ │(MQTT topics)│ │    │ │             │ │    │ │topic        │ │    │ │             │ │
│ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │    │ └─────────────┘ │
│        ▲        │    │                 │    │                 │    │        │        │
│        │        │    │                 │    │                 │    │        ▼        │
│        │        │    │                 │    │                 │    │ ┌─────────────┐ │
│        │        │    │                 │    │                 │    │ │Command      │ │
│        │        │    │                 │    │                 │    │ │Processing   │ │
│        │        │    │                 │    │                 │    │ │             │ │
│        │        │    │                 │    │                 │    │ └─────────────┘ │
│        │        │    │                 │    │                 │    │        │        │
│        │        │    │                 │    │                 │    │        ▼        │
│        │        │    │                 │    │                 │    │ ┌─────────────┐ │
│        │        │    │                 │    │                 │    │ │Response     │ │
│        │        │    │                 │    │                 │    │ │Diversion    │ │
│        │        │    │                 │    │                 │    │ │Interceptor  │ │
│        │        │    │                 │    │                 │    │ └─────────────┘ │
│        │        │    │                 │    │                 │    │        │        │
│        │        │    │                 │    │                 │    │        ▼        │
│ ┌─────────────┐ │    │                 │    │                 │    │ ┌─────────────┐ │
│ │Device       │ │◀───┼─────────────────┼────┼─────────────────┼────│ │MQTT Target  │ │
│ │Responses    │ │    │                 │    │                 │    │ │Connection   │ │
│ │(MQTT topics)│ │    │                 │    │                 │    │ │(AWS IoT)    │ │
│ └─────────────┘ │    │                 │    │                 │    │ └─────────────┘ │
└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘

Legend:
───▶ Command Flow (MQTT → Kafka → Ditto)
◀─── Response Flow (Ditto → MQTT, bypassing Kafka)

Example Configuration

First, create the Kafka connection that consumes device commands:

{
  "id": "kafka-commands-connection",
  "connectionType": "kafka",
  "connectionStatus": "open",
  "uri": "tcp://kafka-broker:9092",
  "specificConfig": {
    "bootstrapServers": "kafka-broker:9092",
    "saslMechanism": "plain"
  },
  "sources": [{
    "addresses": ["device-commands"],
    "authorizationContext": ["ditto:kafka-consumer"],
    "headerMapping": {
      "device-id": "{{ header:device-id }}",
      "divert-response-to-connection": "aws-iot-mqtt-connection",
      "divert-expected-response-types": "response,error"
    }
  }]
}

Next, create the MQTT connection that will handle diverted responses:

{
  "id": "aws-iot-mqtt-connection", 
  "connectionType": "mqtt",
  "connectionStatus": "open",
  "uri": "ssl://your-iot-endpoint.amazonaws.com:8883",
  "sources": [],
  "targets": [
      {
    "address": "device/{{ header:device-id }}/response",
    "topics": [],
    "headerMapping": {
      "device-id": "{{ header:device-id }}",
      "correlation-id": "{{ header:correlation-id }}"
    }
  }
  ],
    "specificConfig": {
        "is-diversion-target": "true"
    }
}

Flow explanation

Command ingestion: Kafka connection consumes device commands from the device-commands topic
Response diversion: Commands are configured to divert responses to the aws-iot-mqtt-connection
Response routing: Responses are automatically published to AWS IoT Core via MQTT on the device-specific response topic
Device notification: Devices receive responses via their subscribed MQTT topics in AWS IoT Core

This setup enables a seamless flow from Kafka-based systems back to MQTT-based device communication without requiring external routing logic.

Try it out

Response diversion is available starting with Eclipse Ditto version 3.8.0. Update your deployment and start experimenting with multi-protocol workflows!

The feature documentation provides comprehensive configuration examples and troubleshooting guidance. We’d love to hear about your use cases and feedback.

Get started with response diversion today and unlock new possibilities for your IoT connectivity architecture.

–
The Eclipse Ditto team

Announcing Eclipse Ditto Release 3.7.0

Wed, 26 Feb 2025 00:00:00 +0000

Eclipse Ditto team is excited to announce the availability of a new minor release, including new features: Ditto 3.7.0.

The focus of this release was to ease the migration of Things “definitions” (following WoT Things Models) and to provide a new Policy decision API to check permissions for a logged-in user.
On the operating side, it is now possible to configure extra fields to be proactively added to Things in order to optimize cluster roundtrips and to throttle the amount of updates to the search index after a re-used policy was updated.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.7.0 are:

Introduce new Policy decision API to check with a single request what a logged-in user is allowed to do with a specific resource
Include current entity revision of a resource (thing and policy) in the response of requests (commands) and in all emitted events
Support updating referenced WoT ThingModel based thing definition for a Thing by defining a migration payload and when to apply it

The following non-functional work is also included:

Add option to configure pre-defined extra fields (enrichments) to be proactively added internally in Ditto in order to save cluster roundtrips
Include throttling configuration option for updating the search index as a result of a policy update targeting many things
Add namespace to Ditto Helm chart managed Kubernetes resources

The following notable fixes are included:

Fix flattening of JSON objects in arrays when an exists() RQL condition was used e.g. as a Ditto evaluated condition

Please have a look at the 3.7.0 release notes for a more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team

Announcing Eclipse Ditto Release 3.6.0

Mon, 07 Oct 2024 00:00:00 +0000

After a longer time of “bugfix releases” only, the Eclipse Ditto team is once again happy to announce the availability of a new minor release, including new features: Ditto 3.6.0.

The most work in this release went into the enforcement/validation of a linked WoT (Web of Thing) “Thing Model” to make sure that a Ditto managed digital twin can only be modified in ways which are valid based on the defined WoT model.

But also other features like SSO in the Ditto-UI were added, so inform yourself in this blogpost about the changes in the new release.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.6.0 are:

WoT (Web of Things) Thing Model based validation of modifications to things and action/event payloads
AWS IAM based authentication against MongoDB
Configure defined aggregation queries to be exposed as Prometheus metrics by Ditto periodically
SSO (Single-Sign-On) support in the Ditto UI via OpenID connect provider configuration

The following non-functional work is also included:

Update Java runtime to run Eclipse Ditto with to Java 21
Run Ditto system tests in GitHub actions

The following notable fixes are included:

Fix JWT placeholder not resolving correctly in JSON arrays nested in JSON objects
Fix retrieving a Thing at a given historical timestamp
Generating UNIX “Epoch” as neutral element when creating new things based on WoT TM models for types declared as “date-time” format

Please have a look at the 3.6.0 release notes for a more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team

Access Ditto Things from an Asset Administration Shell

Tue, 27 Feb 2024 00:00:00 +0000

Integrating digital representations of devices into an IT infrastructure is a recurring task in different domains and application areas. To address this challenge in Industry 4.0 scenarios along the supply chain, the community specified the Asset Administration Shell within the Industrial Digital Twin Association (IDTA) to handle all kinds of information of a physical asset over its lifecycle.

Eclipse Ditto provides a backend for handling such device data as Things and takes care of a number of general tasks that are otherwise easy to be done wrong, such as handling device connectivity over different protocols or state management. Therefore, it is promising to use the benefits of Eclipse Ditto for populating an AAS infrastructure when the devices already communicate with an existing instance of Eclipse Ditto.

In this post we want to share our solution and learnings from setting up an AAS infrastructure based on Eclipse Basyx and Eclipse Ditto as a source for device state.

Figure 1: User-device interaction via BaSyx and Ditto

Background

We start with some background on the AAS and Eclipse Basyx. If you are allready familiar with both, it is safe to skip this section.

Asset Administration Shell

The Asset Administration Shell (AAS) is a standardization effort of the Industrial Digital Twin Association (IDTA) that originated from the Platform Industry 4.0 (I4.0) (AAS Spec Part I; AAS Spec Part II).

An AAS is a digital representation of a physical asset and consists of one or more submodels. Each submodel contains a structured set of submodel elements. Submodels, as well as their submodel elements, can either be a type or an instance. The AAS metamodel defines the possible elements for modeling an AAS like Asset, AssetAdminstrationShell (AAS), Submodel (SM), SubmodelElementCollection (SMEC), Property, and SubmodelElement (SME). You can find further details here and here.

A user who wants to interact with an AAS over HTTP follows the sequence of service calls depicted in Figure 2. The flow starts by requesting an AAS ID from the AAS discovery interface based on a (local) specific asset ID or a global asset ID. An example of such an asset ID is a serial number written on the device. With the AAS ID, the user retrieves the endpoint for the AAS through the AAS registry interface. The user then requests the SM ID from that AAS endpoint and uses this SM ID to get the SM endpoint from the SM Registry. From that SM endpoint, the user can request the SME, which contains the required value.

Figure 2: Sequence of data flow through AAS infrastructure

If you want to dig deeper into the specifics of the AAS, consult the AAS Reading Guide, which helps the interested reader to navigate through the available material.

Eclipse BaSyx

Eclipse BaSyx is an open-source project hosted by the Eclipse Foundation providing components to deploy an Industry 4.0 middleware. Apart from other features, Eclipse BaSyx provides several easy-to-use off-the-shelf components to realize an AAS infrastructure:

You can pull them from Docker Hub or follow the instructions to build them yourself.

In this post, we mainly work with the AAS Server Component and the Registry Component.

Architectural Considerations

Making Eclipse Ditto Things available in an AAS infrastructure, in our case from the Eclipse Basyx project, boils down to making Thing data available as Submodels of an AAS accessible via the AAS Interface.

We see three approaches to achieve this:

BaSyx AAS SM server pulls the current state from Eclipse Ditto via a wrapper around Eclipse Ditto. This approach requires the creation of a custom AAS infrastructure around Eclipse Ditto without the chance of reusing existing components of the Eclipse Basyx project. The Eclipse Ditto project followed a comparable approach to support Web of Things (WoT) definitions, which is another specification to integrate IoT devices from different contexts and align their utilized data model. Ditto now allows the generation of new Things based on a WoT Thing Description.
BaSyx AAS SM server pulls the current state from Eclipse Ditto via a bridge component, which Eclipse Basyx already provides. To integrate the bridge, the BaSyx SM-server component has a delegation feature, where the user can configure an SME with an endpoint to which the server delegates incoming requests. The configured endpoint can reference the bridge that then retrieves the actual data from Ditto and applies transformation logic.
Eclipse Ditto pushes the latest updates to a BaSyx SM server. For this approach, we configure Eclipse Ditto to notify the BaSyx SM server about any change to the relevant Things. During the creation of the notification message, Ditto applies a payload mapping to transform the data into the AAS format. The BaSyx SM server then stores the received submodel element and responds directly to the requests by the users.

Figure 3: Push approach sequence

We follow the push approach here because it treats the AAS infrastructure as a blackbox and almost all configuration happens within Eclipse Ditto.

Mapping of Data Models

Eclipse Ditto and Eclipse Basyx work with different data structures and conceptual elements to represent device and asset data. Since we want to convert between these data models, we need to come up with a mapping between them.

Eclipse Ditto	Asset Administration Shell
Namespace	Asset Administration Shell
Thing	—
Features	Submodel
Property	Submodel Element
Attribute	Submodel Element

Table 1: Concept mapping from Eclipse Ditto to the AAS

We map a Ditto Namespace to a single AAS. An AAS holds multiple SMs, and not all of these SMs necessarily have counterparts in Ditto. We thus treat a Thing as an opaque concept and do not define an explicit mapping for a Thing but map each feature to one SM. property and Attribute are mapped to SMEs.

By that, it is possible to have more than one Thing organized in one AAS. This can especially be useful if an AAS organizes complex equipment with different sensors and actuators, which belong together but are organized in multiple Things.

Integration Steps

With the more theoretical details completed, we can now turn to the actual implementation and describe what is required to integrate Eclipse Ditto into an AAS infrastructure of Eclipse BaSyx.

Prerequisites

Running instance of Eclipse Ditto
Running instance of Eclipse BaSyx AAS Server
Running instance of Eclipse BaSyx AAS Registry

Those three instances must be available and a network connection must exist between them. In the code snippets below, we use placeholders for the URLs of Ditto as well as BaSyx. So, you need to replace <ditto-instance-url>, <basyx-server-instance-url>, <basyx-registry-instance-url> with the proper URLs in your environment.

For our setup, we used version 3.0.1 for Eclipse Ditto and version 1.4.0 for Eclipse BaSyx. Please note that the Ditto demo instance, does not work for the described setup and requests because it does not allow to directly invoke the /devops endpoints through which we later configure connections.

Payload Mappers from Ditto to BaSyx

Let us assume a device with a sensor named machine:sensor that is capable of measuring temperature values. This device may send sensor data to an Eclipse Ditto instance as a Ditto Protocol message Ditto Protocol message:

{
  "topic": "machine/sensor/things/twin/commands/modify",
  "headers": {},
  "path": "/features/temperature/properties/value",
  "value": 46
}

Listing 1: Ditto Protocol message for the Thing machine:senor

If the device uses another message format, you can find more details on how to map it to a Ditto Protocol message.

After an update to a Thing, we want Ditto to map the information to an AAS-conforming representation and forward this via an outbound connection to an AAS server. The task in Eclipse Ditto is to define payload mappers for these transformations in accordance with the mapping from Mapping of Data Models. Ditto allows the usage of JavaScript to create the mappers. We thus configure connections in Ditto to the BaSyx components, where we filter for the relevant changes to a Thing and then trigger the respective mapper.

We need to implement the following mappers:

Creation of an AAS triggered by creation of new namespaces
Creation of a SM triggered by creation of feature
Creation and update of an SME triggered by creation and modification of a property

Map from Thing Creation to AAS Creation

The next snippet performs a mapping from a Thing to an AAS. It gets executed every time a Thing is created.

function mapFromDittoProtocolMsg(
  namespace,
  name,
  group,
  channel,
  criterion,
  action,
  path,
  dittoHeaders,
  value,
  status,
  extra
) {
  let headers = dittoHeaders;
  let textPayload = JSON.stringify({
    conceptDictionary: [],
    identification: {
      idType: 'Custom',
      id: namespace
    },
    idShort: namespace,
    dataSpecification: [],
    modelType: {
      name: 'AssetAdministrationShell'
    },
    asset: {
      identification: {
        idType: 'Custom',
        id: namespace + '-asset'
      },
      idShort: namespace + '-asset',
      kind: 'Instance',
      dataSpecification: [],
      modelType: {
        name: 'Asset'
      },
      embeddedDataSpecifications: []
    },
    embeddedDataSpecifications: [],
    views: [],
    submodels: []
  });
  let bytePayload = null;
  let contentType = 'application/json';
  return Ditto.buildExternalMsg(
    headers, // The external headers Object containing header values
    textPayload, // The external mapped String
    bytePayload, // The external mapped byte[]
    contentType // The returned Content-Type
  );
}

Listing 2: Payload mapping that creates a new AAS if a new Thing appears

As we map the Thing namespace to an AAS we only use the namespace, which is the first part of the ID of a Thing. For example machine in our machine:sensor example Thing (Listing 1). More precisely, the mapping creates a representation of an AAS with the ID namespace and returns a new message with this text as payload. The Ditto connectivity service then runs the mapping and pushes the new message to the BaSyx AAS server to create the described AAS. For example, whenever a Thing with the ID machine:sensor is created, an AAS with the ID machine will be created.

Map from Feature creation to Submodel creation

The next mapper creates an AAS submodel and will be executed every time a new feature is created for a Thing.

function mapFromDittoProtocolMsg(
  namespace,
  name,
  group,
  channel,
  criterion,
  action,
  path,
  dittoHeaders,
  value,
  status,
  extra
) {
  
  let feature_id = path.split('/').slice(2);
  let headers = dittoHeaders;
  let textPayload = JSON.stringify(
    {
      parent: {
        keys: [
          {
            idType: 'Custom',
            type: 'AssetAdministrationShell',
            value: namespace,
            local: true
          }
        ]
      },
      identification: {
        idType: 'Custom',
        id: name+'_'+feature_id
      },
      idShort: name+'_'+feature_id,
      kind: 'Instance',
      dataSpecification: [],
      modelType: {
        name: 'Submodel'
      },
      embeddedDataSpecifications: [],
      submodelElements: []
    }

  );
  let bytePayload = null;
  let contentType = 'application/json';
  return Ditto.buildExternalMsg(
    headers, // The external headers Object containing header values
    textPayload, // The external mapped String
    bytePayload, // The external mapped byte[]
    contentType // The returned Content-Type
  );
}

Listing 3: Payload mapping that creates a new AAS submodel if a new Feature appears

Besides namespace, this mapper uses the parameters name and path from the Ditto Protocol message. The name represents the second part of the Thing-ID, e.g., sensor from our machine:sensor example Thing (Listing 1). The path describes the part of the Thing whose change triggered the processed Ditto Protocol message. It may include the feature ID of the Thing or the whole path of the affected property of the Thing, but it could be only / after the creation of a Thing. In our example message above, the path is /features/temperature/properties/value.

The mapping function extracts the ID of the feature from the parameter path and uses this together with the name of the Thing to build the ID of the corresponding AAS submodel. For example, whenever the feature temperature of a Thing called machine:sensor is created, an AAS submodel with the ID sensor_temperature in the AAS machine will be created.

Similarly to the AAS creation mapping, the listed function returns a new message with a custom text payload. Below, we will create a connection so that this payload gets pushed to the BaSyx AAS server to trigger the creation of an AAS submodel there.

Map from Property Update to Submodel Update

The next mapper creates an AAS submodel element. we use it in the connection for every modification of a property in a Thing.

function mapFromDittoProtocolMsg(
  namespace,
  name,
  group,
  channel,
  criterion,
  action,
  path,
  dittoHeaders,
  value,
  status,
  extra
) {
  let property_id = path.split('/').slice(3).join('_');
  let feature_id = path.split('/').slice(2,3);
  let headers = dittoHeaders;
  let dataType = typeof value;
  dataType = mapDataType(dataType)

  function mapDataType(dataType) {
    switch (dataType) {
        case 'undefined':
        return 'Undefined';
        case 'boolean':
        return 'boolean';
        case 'number':
        return 'int';
        case 'string':
        return 'string';
        case 'symbol':
        return 'Symbol';
        case 'bigint':
        return 'BigInt';
        case 'object':
        return 'string';
        case 'function':
        return 'Function';
        default:
        return 'Unknown';
    }
  }
  let textPayload = JSON.stringify(
  {
    parent: {
      keys: [
        {
          idType: 'Custom',
          type: 'Submodel',
          value: name+'_'+feature_id,
          local: true
        }
      ]
    },
    idShort: property_id,
    kind: 'Instance',
    valueType: dataType,
    modelType: {
      name: 'Property'
    },
    value: value
  }
  );
  let bytePayload = null;
  let contentType = 'application/json';
  return Ditto.buildExternalMsg(
    headers, // The external headers Object containing header values
    textPayload, // The external mapped String
    bytePayload, // The external mapped byte[]
    contentType // The returned Content-Type
  );
}

Listing 4: Payload mapping that modifies an AAS submodel element if a property is changed

The mapper extracts the feature_id and the property_id from the path, which is only possible if the parameter path includes the property_id. So, in the configuration of the connection, we have to ensure that this mapper only runs for the right messages. Moreover, we can access the value of the modified property, which will be set as value in the submodel element from the textPayload output.

For example, if a message updates the path: /features/temperature/properties/value in the Thing machine:sensor, the submodel element with the ID properties_value in the submodel sensor_temperature will be updated with the new temperature as value.

We update a submodel element instead of the whole submodel if an existing Thing changes because the mapper only has access to the changed property of the Thing and no information about the other properties. Therefore, submodel elements, which may already be part of the submodel due to previous updates, would implicitly be dropped. With our approach, we preserve the existing properties and only modify the updated properties.

Create a Connection to the BaSyx AAS Server

To apply the introduced mappers, we configure a new Ditto connection to a BaSyx AAS server. The listings below show the respective HTTP calls using curl to configure this connection.

The JavaScript mappers from above are part of piggybackCommand.connection.mappingDefinitions in mappingforShell, mappingforSubmodel and mappingforSubmodelElement.

In the example, we use the placeholder <ditto-instance-url> for the used Ditto instance. You need to adjust to the valid URL of your environment. We assume you have access rights to the Ditto Devops Commands credentials in the used instance (username: devops, password: `foobar is the default).

You can change the password by setting the environment variable DEVOPS_PASSWORD in the gateway service.

Alternatively, an already existing password can be obtained and stored as an environment variable using the following command:

export DEVOPS_PWD=$(kubectl --namespace ditto get secret my-ditto-gateway-secret -o jsonpath="{.data.devops-password}" | base64 --decode)

Please be aware that this command assumes Ditto has been deployed within a namespace ditto.

Finally, you adjust the parameter piggybackCommand.connection.uri with the URL of the running BaSyx server to which Ditto should have network connectivity.

As HTTP requires us to replace certain characters for proper processing, we encode the payload by escaping certain characters and removing the line breaks. We replaced newlines with \n and ' with '"'.

curl -X POST -u devops:foobar -H 'Content-Type: application/json' --data-binary '{
    "targetActorSelection": "/system/sharding/connection",
    "headers": {
      "aggregate": false
    },
    "piggybackCommand": {
      "type": "connectivity.commands:createConnection",
      "connection": {
        "id": "basyxserver-http-connection",
        "connectionType": "http-push",
        "connectionStatus": "open",
        "uri": "<basyx-server-instance-url>:4001",
        "failoverEnabled": true,
        "mappingDefinitions": {
          "mappingforShell": {
            "mappingEngine": "JavaScript",
            "options": {
              "outgoingScript": "function mapFromDittoProtocolMsg(namespace, name, group, channel, criterion, action, path, dittoHeaders, value, status, extra) {\n  let headers = dittoHeaders;\n  let textPayload = JSON.stringify({\n    conceptDictionary: [],\n    identification: {\n      idType: '"'Custom'"',\n      id: namespace\n    },\n    idShort: namespace,\n    dataSpecification: [],\n    modelType: {\n      name: '"'AssetAdministrationShell'"'\n    },\n    asset: {\n      identification: {\n        idType: '"'Custom'"',\n        id: namespace + '"'-asset'"'\n      },\n      idShort: namespace + '"'-asset'"',\n      kind: '"'Instance'"',\n      dataSpecification: [],\n      modelType: {\n        name: '"'Asset'"'\n      },\n      embeddedDataSpecifications: []\n    },\n    embeddedDataSpecifications: [],\n    views: [],\n    submodels: []\n  });\n  let bytePayload = null;\n  let contentType = '"'application/json'"';\n  return Ditto.buildExternalMsg(headers, textPayload, bytePayload, contentType);}"            
            }
          },
          "mappingforSubmodel": {
            "mappingEngine": "JavaScript",
            "options": {
                "outgoingScript": "function mapFromDittoProtocolMsg(namespace, name, group, channel, criterion, action, path, dittoHeaders, value, status, extra) {\n  \n  let feature_id = path.split('"'/'"').slice(2);\n  let headers = dittoHeaders;\n  let textPayload = JSON.stringify(\n    {\n      parent: {\n        keys: [\n          {\n            idType: '"'Custom'"',\n            type: '"'AssetAdministrationShell'"',\n            value: namespace,\n            local: true\n          }\n        ]\n      },\n      identification: {\n        idType: '"'Custom'"',\n        id: name+'"'_'"'+feature_id\n      },\n      idShort: name+'"'_'"'+feature_id,\n      kind: '"'Instance'"',\n      dataSpecification: [],\n      modelType: {\n        name: '"'Submodel'"'\n      },\n      embeddedDataSpecifications: [],\n      submodelElements: []\n    }\n\n  );\n  let bytePayload = null;\n  let contentType = '"'application/json'"';\n  return Ditto.buildExternalMsg(headers, textPayload, bytePayload, contentType);}"
            }
          },
          "mappingforSubmodelElement": {
            "mappingEngine": "JavaScript",
            "options": {
              "outgoingScript": "function mapFromDittoProtocolMsg(namespace, name, group, channel, criterion, action, path, dittoHeaders, value, status, extra) {\n  let property_id = path.split('"'/'"').slice(3).join('"'_'"');\n  let feature_id = path.split('"'/'"').slice(2,3);\n  let headers = dittoHeaders;\n  let dataType = typeof value;\n  dataType = mapDataType(dataType)\n\n  function mapDataType(dataType) {\n    switch (dataType) {\n        case '"'undefined'"':\n        return '"'Undefined'"';\n        case '"'boolean'"':\n        return '"'boolean'"';\n        case '"'number'"':\n        return '"'int'"';\n        case '"'string'"':\n        return '"'string'"';\n        case '"'symbol'"':\n        return '"'Symbol'"';\n        case '"'bigint'"':\n        return '"'BigInt'"';\n        case '"'object'"':\n        return '"'string'"';\n        case '"'function'"':\n        return '"'Function'"';\n        default:\n        return '"'Unknown'"';\n    }\n  }\n  let textPayload = JSON.stringify(\n  {\n    parent: {\n      keys: [\n        {\n          idType: '"'Custom'"',\n          type: '"'Submodel'"',\n          value: name+'"'_'"'+feature_id,\n          local: true\n        }\n      ]\n    },\n    idShort: property_id,\n    kind: '"'Instance'"',\n    valueType: dataType,\n    modelType: {\n      name: '"'Property'"'\n    },\n    value: value\n  }\n  );\n  let bytePayload = null;\n  let contentType = '"'application/json'"';\n  return Ditto.buildExternalMsg(headers, textPayload, bytePayload, contentType);}"
            }
          }
        },
        "sources": [],
        "targets": [
          {
            "address": "PUT:/aasServer/shells/{{ thing:namespace }}",
            "headerMapping": {
              "content-type": "{{ header:content-type }}"
            },
            "authorizationContext": ["nginx:ditto"],
            "topics": [
              "_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),eq(resource:path,'"'/'"'))"
            ],
            "payloadMapping": [
              "mappingforShell"
            ]
          },
          {
            "address": "PUT:/aasServer/shells/{{ thing:namespace }}/aas/submodels/{{ thing:name }}_{{ resource:path | fn:substring-after('"'/features/'"') }}",
            "headerMapping": {
              "content-type": "{{ header:content-type }}"
            },
            "authorizationContext": ["nginx:ditto"],
            "topics": [
              "_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),not(eq(resource:path,'"'/features'"')),like(resource:path,'"'/features*'"'),not(like(resource:path,'"'*properties*'"')))"
            ],
            "payloadMapping": [
              "mappingforSubmodel"
            ]
          },
          {
            "address": "PUT:/aasServer/shells/{{ thing:namespace }}/aas/submodels/{{ thing:name }}_{{ resource:path | fn:substring-after('"'/features/'"') | fn:substring-before('"'/properties'"') }}/submodel/submodelElements/properties_{{ resource:path | fn:substring-after('"'/properties/'"') | fn:replace('"'/'"','"'_'"') }}",
            "headerMapping": {
              "content-type": "{{ header:content-type }}"
            },
            "authorizationContext": ["nginx:ditto"],
            "topics": [
              "_/_/things/twin/events?filter=and(in(topic:action,'"'modified'"'),not(eq(resource:path,'"'/features'"')),like(resource:path,'"'/features*'"'),like(resource:path,'"'*properties*'"'),not(like(resource:path,'"'*properties'"')))"
            ],
            "payloadMapping": [
              "mappingforSubmodelElement"
            ]
          }
        ]
      }
    }
  }' <ditto-instance-url>/devops/piggyback/connectivity

Listing 5: Request to add a new Connection to a Ditto instance

When Ditto established the connection and our payload mappings work, it returns a successful HTTP response and otherwise an error message.

Without any further means, the payload mappings defined in piggybackCommand.mappingDefinition and set in piggybackCommand.targets would get executed for all changes to a Thing. To prevent this, we use filtering with RQL expressions to make sure that our payload mappings are only executed for the correct messages. For example, the filter:

_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),eq(resource:path,'"'/'"'))

before mappingforShell in piggybackCommands.targets[0].topics[0] makes sure that it only triggers for messages, which create a Thing.

Another filter for mappingForSubmodel in pigybackCommands.targets[1].topics[0] makes sure, that the parameter path contains a feature and not a property:

"_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),not(eq(resource:path,'"'/features'"')),like(resource:path,'"'/features*'"'),not(like(resource:path,'"'*properties*'"')))"

Setup Connection to an BaSyx AAS Registry

Within an AAS environment it is required that AAS are discoverable via an AAS registry. We make an AAS discoverable by adding an entry for that AAS into the AAS registry for a new Thing. In our setup we achieve this through the definition of a new connection between Eclipse Ditto and the BaSyx AAS Registry with a respective payload mapping.

function mapFromDittoProtocolMsg(
  namespace,
  name,
  group,
  channel,
  criterion,
  action,
  path,
  dittoHeaders,
  value,
  status,
  extra
) {
  let headers = dittoHeaders;
  let textPayload = JSON.stringify({
    endpoints: [
        {
            address: '<basyx-server-instance-url>:4001/aasServer/shells/' + namespace + '/aas',
            type: 'http'
        }
    ],
    modelType: {
        name: 'AssetAdministrationShellDescriptor'
    },
    identification: {
        idType: 'Custom',
        id: namespace
},
    idShort: namespace,
      asset: {
          identification: {
              idType: 'Custom',
              id: namespace + '-asset'
          },
          idShort: namespace + '-asset',
          kind: 'Instance',
          dataSpecification: [],
          modelType: {
              name: 'Asset'
          },
          embeddedDataSpecifications: []
      },
      submodels: []
  });
  let bytePayload = null;
  let contentType = 'application/json';
  return Ditto.buildExternalMsg(
    headers, // The external headers Object containing header values
   textPayload, // The external mapped String
   bytePayload, // The external mapped byte[]
    contentType // The returned Content-Type
);
}

Listing 6: Snippet to add a new AAS Registry entry for an AAS

As introduced in Mapping of Data Models, we map a namespace in Ditto to an AAS. The new entry in the BaSyx Registry has to contain the endpoint of the BaSyx AAS server, which hosts the new AAS. You find this in the script-payload in the variable endpoints.address. So you need to adapt this value in the following HTTP request to the address of the BaSyx ASS server that you are using and that was configured in the connection between Ditto and the BaSyx AAS Server.

With this mapping, it is now possible to configure a new connection from Ditto to a BaSyx AAS registry through the following HTTP request:

curl -X POST -u devops:foobar -H 'Content-Type: application/json' --data-binary '{
    "targetActorSelection": "/system/sharding/connection",
    "headers": {
      "aggregate": false
    },
    "piggybackCommand": {
      "type": "connectivity.commands:createConnection",
      "connection": {
        "id": "basyxregistry-http-connection",
        "connectionType": "http-push",
        "connectionStatus": "open",
        "uri": "<basyx-registry-instance-url>:4000",
        "failoverEnabled": true,
        "mappingDefinitions": {
          "mappingforShell": {
            "mappingEngine": "JavaScript",
            "options": {
              "outgoingScript": "function mapFromDittoProtocolMsg(namespace, name, group, channel, criterion, action, path, dittoHeaders, value, status, extra) {\n  let headers = dittoHeaders;\n  let textPayload = JSON.stringify({\n    endpoints: [\n        {\n            address: '"'<basyx-server-instance-url>:4001/aasServer/shells/'"' + namespace + '"'/aas'"',\n            type: '"'http'"'\n        }\n    ],\n    modelType: {\n        name: '"'AssetAdministrationShellDescriptor'"'\n    },\n    identification: {\n        idType: '"'Custom'"',\n        id: namespace\n},\n    idShort: namespace,\n      asset: {\n          identification: {\n              idType: '"'Custom'"',\n              id: namespace + '"'-asset'"'\n          },\n          idShort: namespace + '"'-asset'"',\n          kind: '"'Instance'"',\n          dataSpecification: [],\n          modelType: {\n              name: '"'Asset'"'\n          },\n          embeddedDataSpecifications: []\n      },\n      submodels: []\n  });\n  let bytePayload = null;\n  let contentType = '"'application/json'"';\n  return Ditto.buildExternalMsg(headers, textPayload, bytePayload, contentType);}"
            }
          }
        },
        "sources": [],
        "targets": [
          {
            "address": "PUT:/registry/api/v1/registry/{{ thing:namespace }}",
            "headerMapping": {
              "content-type": "{{ header:content-type }}"
            },
            "authorizationContext": ["nginx:ditto"],
            "topics": [
              "_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),eq(resource:path,'"'/'"'))"
            ],
            "payloadMapping": [
              "mappingforShell"
            ]
          }
        ]
      }
    }
  }' <ditto-instance-url>/devops/piggyback/connectivity

Listing 7: Request to add a new Connection to a Ditto instance

We list the JavaScript mapper in piggybackCommand.connection.mappingDefinitions.mappingForShell.options.outgoingScript and reference it as mappingForShell in piggybackCommand.connection.targets[0].payloadMapping. The address of the BaSyx AAS registry is configured in the parameter piggybackCommand.connection.uri.

As filter, to make sure that our mapper function only triggers after the creation of new Thing, we use:

"_/_/things/twin/events?filter=and(in(topic:action,'"'created'"'),eq(resource:path,'"'/'"'))"

Since the registry uses the AAS server endpoint as a base to also get access to all submodels and submodel elements from the same AAS, it is enough to register the AAS endpoint.

Test the Connection

We now configured all required connections in Ditto and can test our setup. All configured mappers trigger through changes to a Thing, so we begin by creating a Thing.

We again refer to the used Ditto instance through the placeholder <ditto-instance-url>, which you need to adapt to the URL of your Ditto instance.

Creating a Thing in Eclipse Ditto

Setup a common policy

To define authorization information to be used by the Things, we first create a policy with the policy-id machine:my-policy.

POLICY_ID=machine:my-policy

curl -i -X PUT -u ditto:ditto -H 'Content-Type: application/json' --data '{
  "entries": {
    "DEFAULT": {
      "subjects": {
        "{{ request:subjectId }}": {
           "type": "Ditto user authenticated via nginx"
        }
      },
      "resources": {
        "thing:/": {
          "grant": ["READ", "WRITE"],
          "revoke": []
        },
        "policy:/": {
          "grant": ["READ", "WRITE"],
          "revoke": []
        },
        "message:/": {
          "grant": ["READ", "WRITE"],
          "revoke": []
        }
      }
    }
  }
}' <ditto-instance-url>/api/2/policies/$POLICY_ID

Listing 8: Demo Policy Definition

You will get a 201 Created response, if the policy creation concluded successfuly. In the subsequent steps, we use the policy-id machine:my-policy to refer to the created policy.

Create a Thing

The next step is to create an actual Thing. We use the namespace and name machine:my-policy and policy-id machine:my-policy here:

NAMESPACE=machine
NAME=sensor
DEVICE_ID=$NAMESPACE:$NAME

curl -i -X PUT -u ditto:ditto -H 'Content-Type: application/json' --data '{
  "policyId": "'$POLICY_ID'"
}' <ditto-instance-url>/api/2/things/$DEVICE_ID

Listing 9: Request to add the Demo Policy to a Ditto instance ($POLICY_ID refers to Listing 8)

Again, a successful creation returns a 201 Created response.

We earlier configured two connections to trigger a mapper on the create event of a Thing. This should push a new AAS to the AAS server and a reference to that AAS in the AAS registry.

You can check whether the execution of the scripts was successful by requesting the shell at the AAS server:

curl -X GET <basyx-server-instance-url>:4001/aasServer/shells

which should return the following result

[{"modelType":{"name":"AssetAdministrationShell"},"idShort":"machine","identification":{"idType":"Custom","id":"machine"},"dataSpecification":[],"embeddedDataSpecifications":[],"submodels":[{"keys":[{"type":"AssetAdministrationShell","local":true,"value":"machine","idType":"Custom"},{"type":"Submodel","local":true,"value":"sensor_temperature","idType":"Custom"}]}],"asset":{"keys":[{"type":"Asset","local":true,"value":"machine-asset","idType":"Custom"}],"identification":{"idType":"Custom","id":"machine-asset"},"idShort":"machine-asset","kind":"Instance","dataSpecification":[],"modelType":{"name":"Asset"},"embeddedDataSpecifications":[]},"views":[],"conceptDictionary":[]}]

In addition, the request to the AAS registry:

curl -X GET <basyx-registry-instance-url>:4000/registry/api/v1/registry

should return:

[{"modelType":{"name":"AssetAdministrationShellDescriptor"},"endpoints":[{"address":"<basyx-server-instance-url>:4001/aasServer/shells/machine/aas","type":"http"}],"identification":{"idType":"Custom","id":"machine"},"idShort":"machine","asset":{"identification":{"idType":"Custom","id":"machine-asset"},"idShort":"machine-asset","kind":"Instance","dataSpecification":[],"modelType":{"name":"Asset"},"embeddedDataSpecifications":[]},"submodels":[]}]

At this point, the newly created Thing has no features, properties, or attributes yet. So let us populate that Thing.

Create a feature for the Thing

Next, we create a feature for the Thing to contain a property with the data of a temperature sensor.

FEATURE_ID=temperature

curl -X PUT -u ditto:ditto -H 'Content-Type: application/json' --data-binary '{
  "properties": {
    "value": null
  }
}' <ditto-instance-url>/api/2/things/$DEVICE_ID/features/$FEATURE_ID

Listing 10: Request to add a feature to the demo Thing (variables refer to previous Listings)

The feature creation triggers the mapper (mappingforSubmodel) to create a corresponding Submodel in the previously created AAS.

To check if this was successful, we request the expected submodel:

curl -X GET <basyx-server-instance-url>:4001/aasServer/shells/$NAMESPACE/aas/submodels/${NAME}_${FEATURE_ID}/submodel

which should result in the following response:

{"parent":{"keys":[{"idType":"Custom","type":"AssetAdministrationShell","value":"machine","local":true}]},"identification":{"idType":"Custom","id":"sensor_temperature"},"idShort":"sensor_temperature","kind":"Instance","dataSpecification":[],"modelType":{"name":"Submodel"},"embeddedDataSpecifications":[],"submodelElements":[]}

Updating a Thing

After we have successfully created a Thing, we can check if the update of a property works as well by executing:

curl -i -X PUT -u ditto:ditto -H "content-type: application/json" --data-binary '46' <ditto-instance-url>/api/2/things/$DEVICE_ID/features/$FEATURE_ID/properties/value

Again, we check if our change was successful:

curl -u ditto:ditto -w '\n' <ditto-instance-url>/api/2/things/$DEVICE_ID

and expect:

{"thingId":"machine:sensor","policyId":"machine:my-policy","features":{"temperature":{"properties":{"value":46}}}}

If the property creation was successful, then the mapping mappingforSubmodelElement should trigger. To verify that the Submodel was updated, call:

curl -X GET <basyx-server-instance-url>:4001/aasServer/shells/$NAMESPACE/aas/submodels/${NAME}_${FEATURE_ID}/submodel/submodelElements/properties_value

This should lead to the response:

{"parent":{"keys":[{"idType":"Custom","type":"Submodel","value":"sensor_temperature","local":true}]},"idShort":"properties_value","kind":"Instance","valueType":"int","modelType":{"name":"Property"},"value":46}

Here, we see that we are able to access the sensor data of the device through the AAS Submodel API via Eclipse BaSyx.

As an alternative to plain Json responses, you can use one of the UI-tools provided by the AAS community, like the AAS Web UI.

Figure 4: BaSyx AAS Web UI

Summary

In this post, we present our approach for making Ditto Things available in an AAS. We defined a mapping concept between Things and AAS. To apply the mapping concept, we created connections with mappers from Ditto to a BaSyx AAS server and a BaSyx AAS registry. Afterwards, we tested the connections with an example Thing and data from a sensor.

Our example of integrating Ditto Things into an AAS environment shows, how the capbilities of Ditto, such as custom mappers, filters etc, render it a useful tool to integrate device states into various environments. We discussed the integration into AAS but believe a similar approach could be applied in other domains as well.

Milena Jäntgen, Sven Erik Jeroschewski and Max Grzanna contributed to this post.

Announcing Eclipse Ditto Release 3.5.0

Fri, 26 Jan 2024 00:00:00 +0000

The Eclipse Ditto team wished you a happy new year and is excited to announce availability of Ditto 3.5.0.

In 3.5.0 a lot of UI improvements are contained and several smaller but very useful features were added.
Thanks a lot to the contributors who contributed to this release, this is really appreciated.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.5.0 are:

Eclipse Ditto 3.5.0 focuses on the following areas:

Search in the history of a single thing using an RQL filter
Configure per namespace the fields to index in Ditto’s search index
Configure defined search count queries to be exposed as Prometheus metrics by Ditto periodically
Providing new placeholder functionality to the time placeholder, being able to add and subtract to/from the current time and to truncate the time to a given unit
Enhance WoT (Web of Things) JSON skeleton creation to be able to fail with an exception on invalid WoT models
Provide negative numbers when querying for the historical events of an entity (thing, policy, connection) in order to e.g. get “latest 10” events
UI enhancements:
- Show policy imports in Ditto explorer UI
- Enhance UI Operations functionality to be able to perform devops/piggyback commands
- Allow editors in UI to toggle full screen mode
- Display attributes in UI inside a JSON editor in order to correctly display structured JSON payloads
- Enhance “Incoming Thing Updates” section by displaying “Action” and “Path” in the table and adding a dropdown to select the amount of details to show per event
- Add client side filter option for filtering Incoming Thing Updates and Connection logs

The following non-functional work is also included:

Configured docker-compose to by default retain only the last 50m of log messages per Ditto service
Migrated SLF4J to version 2.x and logback to version 1.4.x
Benchmark tool improvements and fixes
Improve cluster stability when running in Kubernetes, e.g. on updates or k8s node-shutdowns

The following notable fixes are included:

Fix enriching Thing creation events with the inlined _policy
Fixed that Ditto’s own calculated “health” was not exposed to the /alive endpoint scraped by Kubernetes to check for aliveness of single services
Fixed that no cache was used when updating the search index when an “imported” policy was modified

Please have a look at the 3.5.0 release notes for a more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team

Announcing Eclipse Ditto Release 3.4.0

Tue, 17 Oct 2023 00:00:00 +0000

The Eclipse Ditto teams is proud to announce the availability of Eclipse Ditto 3.4.0.

Version 3.4.0 mainly concentrates on exchanging the use of the Akka toolkit (due to a change in licensing) with its fork Apache Pekko which remains Apache 2.0 licensed.
Apart from that, several improvements are also included which can be found in the changelog.

Adoption

Companies are willing to show their adoption of Eclipse Ditto publicly: https://iot.eclipse.org/adopters/?#iot.ditto

When you use Eclipse Ditto it would be great to support the project by putting your logo there.

Changelog

The main improvements and additions of Ditto 3.4.0 are:

Eclipse Ditto 3.4.0 focuses on the following areas:

Supporting HTTP POST for performing searches with a very long query
Addition of a new placeholder to use in connections to use payload of the thing JSON e.g. in headers or addresses
New placeholder functions for joining multiple elements into a single string and doing URL-encoding and -decoding
Configure MQTT message expiry interval for published messages via a header
Reduce patch/merge thing commands to modify only the actually changed values with a new option
UI enhancements:
- Adding sending messages to Things
- Made UI (at least navigation bar) responsive for small screen sizes
- Increase size of JSON editors in “edit” mode

The following non-functional work is also included:

Swapping the Akka toolkit (because of its switch of license to BSL License after Akka v2.6.x) with its fork Apache Pekko which remains Apache 2.0 licensed.
Support for using AWS DocumentDB as a replacement for MongoDB
Improve logging by adding the W3C Trace Context traceparent header as MDC field to logs
Adjust handling of special MQTT headers in MQTT 5
Optimize docker files
Migration of Ditto UI to TypeScript
There now is an official Eclipse Ditto Benchmark which shows how Ditto is able to scale horizontally and provides some tuning tips
Addition of a benchmark tooling to run own Ditto benchmarks

The following notable fixes are included:

Fixed that failed retrieval of a policy (e.g. after policy change) leads to search index being “emptied out”
Fixed that putting metadata when updating a single scalar value did not work
UI fix, fixing that patching a thing will null values did not reflect that change in the UI

Please have a look at the 3.4.0 release notes for a more detailed information on the release.

Artifacts

The new Java artifacts have been published at the Eclipse Maven repository as well as Maven central.

The Ditto JavaScript client release was published on npmjs.com:

The Docker images have been pushed to Docker Hub:

The Ditto Helm chart has been published to Docker Hub:

eclipse/ditto

–
The Eclipse Ditto team