User Guide

For developers building applications on top of ZeroDDS. Eight-section condensed handbook.

What is ZeroDDS

Pure-Rust implementation of the OMG Data Distribution Service. Native RTPS 2.5, wire-interoperable with Cyclone DDS, OpenDDS, Fast DDS and RTI Connext. Comes with bridges to MQTT, AMQP, CoAP, gRPC, CORBA, ROS-2, WebSocket and bindings for nine languages.

Install

Pick the channel that matches your platform. All Linux binaries are minisign-signed against a public key shipped in the source repository; macOS binaries are Apple-codesigned and notarized.

Linux — Debian / Ubuntu / derivatives

curl -fsSL https://packages.zerodds.org/zerodds.gpg \
  | sudo tee /usr/share/keyrings/zerodds.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/zerodds.gpg] \
  https://packages.zerodds.org/deb bookworm main" \
  | sudo tee /etc/apt/sources.list.d/zerodds.list
sudo apt update && sudo apt install zerodds

Linux — Fedora / RHEL / derivatives

sudo dnf config-manager --add-repo \
  https://packages.zerodds.org/rpm/zerodds.repo
sudo dnf install zerodds

macOS — Homebrew

brew install zero-objects/homebrew-zerodds/zerodds

Linux — Arch / Manjaro (AUR)

yay -S zerodds-bin    # pre-built binary package
# or:
yay -S zerodds        # build from source

Linux — Gentoo

sudo eselect repository add zerodds git \
  https://github.com/zero-objects/gentoo-overlay
sudo emaint sync -r zerodds
sudo emerge net-libs/zerodds

Windows — Scoop

scoop bucket add zerodds https://github.com/zero-objects/scoop-zerodds
scoop install zerodds

Cross-platform — Docker

# GitHub Container Registry (multi-arch: linux/amd64 + linux/arm64)
docker pull ghcr.io/zero-objects/zerodds-ws-bridged:1.0.0-rc.3
docker pull ghcr.io/zero-objects/zerodds-mqtt-bridged:1.0.0-rc.3
# (or fishermen21/zerodds-<daemon> on Docker Hub)

Cross-platform — Cargo (Rust toolchain)

cargo add zerodds-dcps zerodds-rtps zerodds-discovery
# or build from source:
git clone https://github.com/zero-objects/zero-dds
cd zero-dds && cargo build --release

Distro & native installer roadmap

Channel	Stage	Status
crates.io (`cargo install` / `cargo add`)	1	✅ live (rc.3)
GitHub Releases (8 cross-platform binaries + AppImage)	1	✅ built on tag push, minisign-signed
Docker Hub `fishermen21/zerodds-<daemon>`	1	✅ multi-arch `linux/amd64` + `linux/arm64`, 8 daemons
ghcr.io `zero-objects/zerodds-<daemon>`	1	✅ via GITHUB_TOKEN, multi-arch
macOS codesign + notarize	1	✅ Developer ID Application + Installer certs, `sign-macos.sh` wired in release.yml
Homebrew tap `zero-objects/homebrew-zerodds`	1	✅ live, auto-PR on release
Scoop bucket `zero-objects/scoop-zerodds`	1	✅ live, auto-PR on release
Self-hosted APT repo (`packages.zerodds.org/deb`)	1	✅ TLS, GPG-signed
Self-hosted RPM repo (`packages.zerodds.org/rpm`)	1	✅ TLS, GPG-signed
Pull-deploy on packages.zerodds.org	1	✅ cron `*/5` sync from GitHub Releases, no inbound access from CI
Arch User Repository (`zerodds-bin` + `zerodds`)	1	✅ initial push done, auto-update job in release.yml
Gentoo overlay (`zero-objects/gentoo-overlay`)	1	✅ overlay repo published with ebuild
Ubuntu PPA (Launchpad)	2	after the RC series stabilises
Fedora COPR	2	after the RC series stabilises
Chocolatey community feed	2	after the RC series stabilises
Windows Authenticode signing + MSIX (Microsoft Store)	3	⏸ skipped during the RC series (Authenticode certificate cost)
Debian official, Fedora official, Homebrew core, NixOS	4	long-lead; targeted post 1.0 stable

First Pub/Sub

Publisher:

use zerodds_dcps::*;

let factory = DomainParticipantFactory::instance();
let participant = factory.create_participant_offline(0, DomainParticipantQos::default());
let topic = participant
    .create_topic::<RawBytes>("Greetings", TopicQos::default())
    .expect("create_topic");
let writer = participant
    .create_publisher(PublisherQos::default())
    .create_datawriter::<RawBytes>(&topic, DataWriterQos::default())
    .expect("create_datawriter");

writer.write(&RawBytes::new(b"Hello, DDS!".to_vec())).expect("write");

▶ Runnable example: hello-publisher

The subscriber pattern is symmetric. The full 15-chapter walk-through with cross-language ports lives in examples/tutorials/dds-chat.

QoS Cheatsheet

Policy	One-line
`Reliability`	`Reliable` retransmits lost samples; `BestEffort` drops them.
`Durability`	`Volatile` (no replay); `TransientLocal` (writer cache replay); `Transient`; `Persistent`.
`History`	`KeepLast(n)` per instance vs. `KeepAll`.
`Deadline`	Maximum interval between samples per instance; missed deadlines fire a status.
`Lifespan`	How long a sample remains valid after publication.
`Liveliness`	`Automatic` (DCPS-managed) vs. `Manual` (application asserts).
`Ownership`	`Shared` (multi-writer) vs. `Exclusive` (highest-strength wins).
`ResourceLimits`	Max samples / max instances / max samples per instance caps.
`DestinationOrder`	`ByReceptionTimestamp` vs. `BySourceTimestamp`.
`ContentFilter`	SQL-like filter on the subscriber side.

Bridges

Pick the bridge for your protocol:

Bridge	Use case
`zerodds-ws-bridged`	WebSocket clients, browser SPAs.
`zerodds-mqtt-bridged`	IoT MQTT broker integration.
`zerodds-coap-bridged`	Constrained-device CoAP.
`zerodds-amqp-bridged`	RabbitMQ / ActiveMQ enterprise queueing.
`zerodds-grpc-bridged`	gRPC service-mesh integration with auto-generated services per topic.
`zerodds-corba-bridged`	Legacy CORBA mainframes (financial-industry drop-in).
`zerodds-ros2-shim`	ROS-2 RMW plugin (REP-2007 / 2008 / 2009).

Security

Two layers:

DDS-Security 1.2 — OMG plugins enabled via Participant QoS. Auth + AccessControl + Crypto + Logging + DataTagging.
bridge-security — TLS 1.3 (rustls), bearer / JWT-RS256 / mTLS / SASL-PLAIN, ACL with wildcard + group matching, SIGHUP cert rotation.

Troubleshooting

Discovery silent — check that multicast is enabled on your network. Use zerodds-admin discovery snapshot to capture SPDP/SEDP traffic.
Sample lost — verify Reliability=Reliable on both writer and reader. BestEffort drops on congestion.
Wire-incompat with another DDS — capture both sides with tcpdump -i any -X port 7400 and diff.
Cross-language struct mismatch — regenerate code with idlc from a single canonical IDL.
TLS handshake fails — check ALPN protocol matches; mTLS requires the client cert chain rooted in the server's CA.

Spec Mapping

Which OMG spec covers which feature:

Pub/Sub API — DDS-DCPS 1.4 §2.2.
Wire format — DDSI-RTPS 2.5 + DDS-XTypes 1.3 (XCDR1/XCDR2).
Type system — DDS-XTypes 1.3 + IDL 4.2.
Security — DDS-Security 1.2.
QoS XML — DDS-XML 1.0.
Constrained devices — DDS-XRCE 1.0.
RPC — DDS-RPC 1.0.

Full handbook on GitHub →

User Guide

Für Entwickler:innen, die Anwendungen auf ZeroDDS aufbauen. Kompaktes Handbuch in acht Abschnitten.

Was ist ZeroDDS

Pure-Rust-Implementierung des OMG Data Distribution Service. Natives RTPS 2.5, wire-interoperabel mit Cyclone DDS, OpenDDS, Fast DDS und RTI Connext. Mit Bridges zu MQTT, AMQP, CoAP, gRPC, CORBA, ROS-2, WebSocket und Bindings für neun Sprachen.

Installation

Wähle den Kanal, der zu deiner Plattform passt. Alle Linux-Binaries sind mit minisign gegen einen öffentlichen Schlüssel im Source-Repository signiert; macOS-Binaries sind Apple-codesigned und notarisiert.

Linux — Debian / Ubuntu / Derivate

curl -fsSL https://packages.zerodds.org/zerodds.gpg \
  | sudo tee /usr/share/keyrings/zerodds.gpg >/dev/null
echo "deb [signed-by=/usr/share/keyrings/zerodds.gpg] \
  https://packages.zerodds.org/deb bookworm main" \
  | sudo tee /etc/apt/sources.list.d/zerodds.list
sudo apt update && sudo apt install zerodds

Linux — Fedora / RHEL / Derivate

sudo dnf config-manager --add-repo \
  https://packages.zerodds.org/rpm/zerodds.repo
sudo dnf install zerodds

macOS — Homebrew

brew install zero-objects/homebrew-zerodds/zerodds

Linux — Arch / Manjaro (AUR)

yay -S zerodds-bin    # vorgebautes Binary-Paket
# oder:
yay -S zerodds        # aus dem Source bauen

Linux — Gentoo

sudo eselect repository add zerodds git \
  https://github.com/zero-objects/gentoo-overlay
sudo emaint sync -r zerodds
sudo emerge net-libs/zerodds

Windows — Scoop

scoop bucket add zerodds https://github.com/zero-objects/scoop-zerodds
scoop install zerodds

Plattformübergreifend — Docker

# GitHub Container Registry (multi-arch: linux/amd64 + linux/arm64)
docker pull ghcr.io/zero-objects/zerodds-ws-bridged:1.0.0-rc.3
docker pull ghcr.io/zero-objects/zerodds-mqtt-bridged:1.0.0-rc.3
# (oder fishermen21/zerodds-<daemon> auf Docker Hub)

Plattformübergreifend — Cargo (Rust-Toolchain)

cargo add zerodds-dcps zerodds-rtps zerodds-discovery
# oder aus dem Source bauen:
git clone https://github.com/zero-objects/zero-dds
cd zero-dds && cargo build --release

Distro- & Native-Installer-Roadmap

Kanal	Stufe	Status
crates.io (`cargo install` / `cargo add`)	1	✅ live (rc.3)
GitHub Releases (8 plattformübergreifende Binaries + AppImage)	1	✅ bei Tag-Push gebaut, minisign-signiert
Docker Hub `fishermen21/zerodds-<daemon>`	1	✅ multi-arch `linux/amd64` + `linux/arm64`, 8 Daemons
ghcr.io `zero-objects/zerodds-<daemon>`	1	✅ via GITHUB_TOKEN, multi-arch
macOS codesign + notarize	1	✅ Developer ID Application + Installer Certs, `sign-macos.sh` in release.yml verdrahtet
Homebrew-Tap `zero-objects/homebrew-zerodds`	1	✅ live, Auto-PR bei Release
Scoop-Bucket `zero-objects/scoop-zerodds`	1	✅ live, Auto-PR bei Release
Self-hosted APT-Repo (`packages.zerodds.org/deb`)	1	✅ TLS, GPG-signiert
Self-hosted RPM-Repo (`packages.zerodds.org/rpm`)	1	✅ TLS, GPG-signiert
Pull-Deploy auf packages.zerodds.org	1	✅ Cron `*/5` Sync aus GitHub Releases, kein eingehender CI-Zugriff
Arch User Repository (`zerodds-bin` + `zerodds`)	1	✅ Initial-Push erledigt, Auto-Update-Job in release.yml
Gentoo-Overlay (`zero-objects/gentoo-overlay`)	1	✅ Overlay-Repo mit Ebuild veröffentlicht
Ubuntu PPA (Launchpad)	2	nach Stabilisierung der RC-Serie
Fedora COPR	2	nach Stabilisierung der RC-Serie
Chocolatey Community Feed	2	nach Stabilisierung der RC-Serie
Windows Authenticode-Signing + MSIX (Microsoft Store)	3	⏸ während der RC-Serie ausgesetzt (Authenticode-Zertifikatskosten)
Debian offiziell, Fedora offiziell, Homebrew core, NixOS	4	lange Vorlaufzeit; angepeilt nach 1.0 stable

Erstes Pub/Sub

Publisher:

use zerodds_dcps::*;

let factory = DomainParticipantFactory::instance();
let participant = factory.create_participant_offline(0, DomainParticipantQos::default());
let topic = participant
    .create_topic::<RawBytes>("Greetings", TopicQos::default())
    .expect("create_topic");
let writer = participant
    .create_publisher(PublisherQos::default())
    .create_datawriter::<RawBytes>(&topic, DataWriterQos::default())
    .expect("create_datawriter");

writer.write(&RawBytes::new(b"Hello, DDS!".to_vec())).expect("write");

▶ Runnable example: hello-publisher

Das Subscriber-Muster ist symmetrisch. Das vollständige 15-Kapitel-Walkthrough mit Cross-Language-Ports liegt in examples/tutorials/dds-chat.

QoS-Spickzettel

Policy	Einzeiler
`Reliability`	`Reliable` sendet verlorene Samples erneut; `BestEffort` verwirft sie.
`Durability`	`Volatile` (kein Replay); `TransientLocal` (Writer-Cache-Replay); `Transient`; `Persistent`.
`History`	`KeepLast(n)` pro Instanz vs. `KeepAll`.
`Deadline`	Maximaler Abstand zwischen Samples pro Instanz; verpasste Deadlines lösen einen Status aus.
`Lifespan`	Wie lange ein Sample nach der Veröffentlichung gültig bleibt.
`Liveliness`	`Automatic` (DCPS-verwaltet) vs. `Manual` (Anwendung bestätigt).
`Ownership`	`Shared` (Multi-Writer) vs. `Exclusive` (höchste Strength gewinnt).
`ResourceLimits`	Caps für max. Samples / max. Instanzen / max. Samples pro Instanz.
`DestinationOrder`	`ByReceptionTimestamp` vs. `BySourceTimestamp`.
`ContentFilter`	SQL-ähnlicher Filter auf der Subscriber-Seite.

Bridges

Wähle die Bridge für dein Protokoll:

Bridge	Anwendungsfall
`zerodds-ws-bridged`	WebSocket-Clients, Browser-SPAs.
`zerodds-mqtt-bridged`	IoT-MQTT-Broker-Integration.
`zerodds-coap-bridged`	CoAP für ressourcenbeschränkte Geräte.
`zerodds-amqp-bridged`	RabbitMQ / ActiveMQ Enterprise-Queueing.
`zerodds-grpc-bridged`	gRPC-Service-Mesh-Integration mit auto-generierten Services pro Topic.
`zerodds-corba-bridged`	Legacy-CORBA-Mainframes (Finanzindustrie-Drop-in).
`zerodds-ros2-shim`	ROS-2-RMW-Plugin (REP-2007 / 2008 / 2009).

Security

Zwei Schichten:

DDS-Security 1.2 — OMG-Plugins, aktiviert über Participant-QoS. Auth + AccessControl + Crypto + Logging + DataTagging.
bridge-security — TLS 1.3 (rustls), Bearer / JWT-RS256 / mTLS / SASL-PLAIN, ACL mit Wildcard- + Gruppen-Matching, SIGHUP-Cert-Rotation.

Fehlersuche

Discovery still — prüfe, ob Multicast in deinem Netz aktiviert ist. Mit zerodds-admin discovery snapshot SPDP/SEDP-Verkehr aufzeichnen.
Sample verloren — Reliability=Reliable auf Writer und Reader prüfen. BestEffort verwirft bei Überlast.
Wire-Inkompatibilität mit anderem DDS — beide Seiten mit tcpdump -i any -X port 7400 aufzeichnen und vergleichen.
Cross-Language-Struct-Mismatch — Code mit idlc aus einer einzigen kanonischen IDL neu generieren.
TLS-Handshake schlägt fehl — prüfen, ob das ALPN-Protokoll passt; mTLS erfordert eine Client-Cert-Kette, die in der CA des Servers wurzelt.

Spec-Mapping

Welche OMG-Spec welches Feature abdeckt:

Pub/Sub-API — DDS-DCPS 1.4 §2.2.
Wire-Format — DDSI-RTPS 2.5 + DDS-XTypes 1.3 (XCDR1/XCDR2).
Typsystem — DDS-XTypes 1.3 + IDL 4.2.
Security — DDS-Security 1.2.
QoS-XML — DDS-XML 1.0.
Ressourcenbeschränkte Geräte — DDS-XRCE 1.0.
RPC — DDS-RPC 1.0.

Vollständiges Handbuch auf GitHub →