Retina DDS for Rust

DDS programming models

DDS core

DCPS defines how data is addressed, published, retained, and observed.

Models built on DDS

Retina · data and state

Rust feature APIs and algorithms

let topic = participant.topic::<Temperature>("temperature");
let writer = participant.create_writer(&topic)?;
let reader = participant.create_reader(&topic)?;

use retina_core::FixedCdrType;

dds_type! { struct Temperature { value: f32 } }

let mut storage = [0_u8; Temperature::MAX_SERIALIZED_SIZE];
writer.write_fixed(&sample, &mut storage)?;

writer.write_instance(&state, b"robot-17")?;
let sample = reader.take_instance(b"robot-17")?;

let qos = QosProfile::builder()
    .reliable()
    .partition("control/*")
    .build();

let qos = QosProfile::builder()
    .keep_last(8)
    .max_samples(64)
    .build();

reader.filter_by(|value: &Temperature| {
    value.degrees_celsius > 80.0
})?;
reader.clear_content_filter()?;

let qos = QosProfile::builder()
    .durability(DurabilityKind::TransientLocal)
    .keep_last(8)
    .build();

let qos = QosProfile::builder()
    .deadline(Duration::from_millis(10))
    .ownership(OwnershipKind::Exclusive, 100)
    .destination_order(DestinationOrderKind::BySourceTimestamp)
    .build();

publisher.begin_coherent_changes()?;
trajectory_writer.write(&trajectory)?;
limits_writer.write(&limits)?;
publisher.end_coherent_changes()?;

let qos = QosProfile::builder()
    .reliable()
    .keep_last(32)
    .max_samples(128)
    .deadline(Duration::from_millis(10))
    .partition("control/*")
    .build();

Retina · network and runtime

Rust delivery mechanisms

let local = RuntimeParticipant::<Temperature>::build(
    identity, "temperature/out", "temperature/in", qos)?;
let matched = local.discover(
    &discovery, &transport, timeout)?;

let mut session = TypedReliableSession::new(
    &transport, &mut matched, config);
session.write(&sample)?;
let received = session.take_until(deadline)?;

let (header, submessages) = parse_rtps_message(&packet)?;
for submessage in submessages {
    handle(header, submessage?);
}

writer.write(&sample)?;
// The same call serves local SHM and remote UDP readers.

let config = StaticPeerConfig::new(local, remote, header);
let transport = UdpStaticPeer::bind(config)?;
transport.send_submessage(bytes, &mut packet)?;

// security and policy were constructed from the deployment credentials.
let progress = security.poll_and_admit(
    now, authorization_time, &mut participant, &policy)?;
// Inspect progress and endpoint readiness before sending user data.

TypedReliableSession::new(transport, matched_participant, config)
session.write(value) -> Result<u64>
session.take_until(deadline) -> Result<T>
session.finish_until(deadline) -> Result<()>
session.metrics() -> ReliableMetrics

API contracts

Ownership, lifetimes, and results

Participant and endpoints

retina_core::Participant shares participant state through reference-counted ownership and a mutex. Endpoint leases keep that state alive. Dropping an endpoint unregisters it; close(self) -> Result<()> consumes the endpoint and lets the caller observe cleanup errors.

Value access

DataReader<T>::take() returns Result<Option<TypedSample<T>>>. An error, an empty history, and a returned sample are different outcomes. read leaves the selected entry in history; take removes it. Neither return value is a loan into arbitrary application memory.

Caller storage

DataWriter<T>::write_fixed requires T: FixedCdrType and borrows a mutable byte slice for serialization during the call. write instead obtains owned serialized bytes. Both return Result<bool>; inspect the boolean as well as the error. Neither is a remote execution receipt.

Serialized loans

The lower-level SerializedDataReader::take_loaned(&mut participant) returns Result<Option<LoanedSerializedSample<'participant>>>. Its lifetime borrows the participant. Dropping a taken loan releases retained or SHM ownership; deserialization is a separate operation.

Zero-copy and allocation-free describe a particular operation and storage configuration, not the entire library. Creating entities, introducing a new instance key, retaining history, and growing serialization storage have their own costs. A shared-memory loan is different from returning an owned value. The history algorithm reference explains the key-index tradeoffs.

Execution and transport

Who makes communication progress?

retina_core::Participant supplies local DDS entities. retina_runtime::RuntimeParticipant<T> supplies a runtime participant that can discover peers through a supplied transport. Its discover operation consumes the local participant and returns a MatchedRuntimeParticipant<T> on success.

retina_runtime::TypedReliableSession borrows the transport and mutably borrows that matched participant. write(&value) returns a sequence in ReliableResult<u64>; take_until(deadline) returns ReliableResult<T>; finish_until(deadline) returns ReliableResult<()>. These calls drive the session; construction does not spawn an independent worker. Its reusable serialization buffer can grow when larger samples arrive.

Automatic SHM/UDP selection requires a runtime that supports both, compatible same-host attachment, and matched reader capabilities. A shared domain ID is not sufficient. Native SHM loans carry slot descriptors; complete RTPS-over-SHM carries wire records. Both must honor DDS admission and ownership, but they do different work. See the delivery paths.

Dependencies

Choose the modules your application uses

Core DDS

retina-core supplies the entity model; retina-runtime and transport crates supply network services.

Security

retina-security supplies security mechanisms, retina-security-openssl the OpenSSL provider, and retina-security-runtime the composed participant service.

Teleoperation

retina-teleop supplies command and robot policy. retina-teleop-security binds that policy to authenticated DDS endpoint installations and application approval.

Core DDS can operate without either optional module. Security can protect ordinary DDS data without Teleoperation. Teleoperation policy can be used without Security, but then it does not establish an authenticated remote operator. Linking a module does not activate a security policy or grant control. ROS remains a separate adapter, not a prerequisite for these APIs. These are code dependency names, not a claim that every binary package has been qualified for every target.

Teleoperation contract

Robot control sessions and command permits

Import RobotControlSession, RobotCommandPermit, and RobotWindowCommand<Payload> from retina_teleop. RobotControlSession::new(profile, lease_config) returns Option<Self>; invalid lease configuration returns None. The profile type is retina_runtime::product_config::ProductConfig. The session is not cloneable. Operations below require &mut self and return Result values.

Construction creates an empty session; it does not grant a lease. The owner holds operator authority, permit deadlines, and the last accepted sequence. It owns no socket, encryption key, sensor, or actuator. Serialize calls to this one owner across UDP and SHM ingress.

apply(request, now)

Returns an authority change. Inspect its result and lease: a successful function return can still report a denied authority request. Renewal preserves existing permit deadlines; successful handover, revocation, and expiry discard grants.

issue(nonce, observation, observed_at, now)

Returns a permit or a specific rejection. Supply a fresh unpredictable challenge and a robot observation timestamp. The robot stores the deadline locally; the permit contains no controller deadline.

admit(permit, sequence, now)

Returns success only for the exact live permit and a newer sequence while the operator lease remains live. Failure does not consume the sequence. This is admission, not delivery acknowledgement or actuator completion.

advance(now)

Checks idle expiry and returns an optional expired lease inside the operation result. Call it during idle service turns as well as handling commands. Active operations repeat the checks, so late timer dispatch cannot extend authority.

retire()

Permanently stops the owner. It has no reset operation and returns no success value. Restart creates a fresh owner with fresh challenges, not restored permits.

Time and rejection results

The product configuration supplies teleop_command_window_ms, teleop_observation_max_age_ms, teleop_window_refresh_ms, and teleop_max_active_windows. Configure these together rather than adding per-call timeout literals. These tuning defaults are not clinical safety limits.

Every now and observed_at is a monotonic timestamp in nanoseconds from the same robot elapsed-time clock. No controller clock comparison is used. The effective deadline is the earlier of the command window and observation-age limit; arrival at the deadline is rejected. Lease duration is configured separately. Clock regression retires the session.

RobotControlSessionError distinguishes Retired, ClockRegressed, NoControlLease, and Window(CommandWindowError). Window errors distinguish unknown or expired permits, repeated or out-of-order sequences, unavailable observations, refresh spacing, capacity, and arithmetic limits. Treat these as policy results, not interchangeable network timeouts.

Binding the session to DDS Security

retina_teleop_security::SecuredRobotControlSession::new(security, authorization, profile, lease) returns Result<Self, SecuredRobotControlSessionError>. Its security argument borrows ParticipantAuthenticationDiscovery. This owner requires an approved operator bound to an installed DDS Writer. Pass the current security service and operator authorization to each apply, issue, admit, and advance call. Explicit handover additionally requires the target operator's approval. Losing or replacing the current binding retires the owner; an invalid target does not replace a still-valid binding.

Authenticate the complete command through its bound endpoint before admission. The wrapper checks the binding; it does not decrypt arbitrary input or turn an operator ID into authorization. Application approval is separate from DDS topic permissions. The application still supplies qualified clocks, sensor provenance, randomness, scheduling, and the safe actuator response. See the deadline algorithm and its cost.