Downlink Communication

What

Downlink Communication is the mirror of Uplink Communication. Same machine, opposite direction. In brief:

• It is the feedback path's transport stage, and part of an all-or-nothing module group. Everything the robot side captures passes through it on the way back to the operator.
• It holds a list of channels — one per feedback stream, identified by its stream id, each with its own scheduled queue. In the demo those streams are the robot's pose and its camera view.
• A communication condition is a small object that decides, per package, how long it waits and whether it is sent at all. It is optional, and configured per channel. No condition means immediate delivery.
• The Kernel ships no delay, jitter, loss or bandwidth models. A condition is written by the study.
• A condition either suppresses a package or returns one transmission delay.
• The Kernel only stores and releases scheduled packages. It does not implement latest-wins, coalescing or retransmission.

The module itself, DownlinkCommunicationKernel, is sealed. You never subclass it. What a study writes, if anything, is a condition.

Why

Feedback delay is not the same experience as command delay, and a study that manipulates one is not manipulating the other.

• Uplink delay postpones the robot's response. The operator acts, and nothing happens for a while.
• Downlink delay postpones the evidence that the robot responded. It already moved; the operator cannot see it yet.

Only their sum is the round trip. Giving the feedback path its own transport module makes that split explicit and reportable, instead of collapsing both halves into a single "latency" figure.

It also lets a study degrade feedback streams unevenly. Video and telemetry rarely share a link budget in a real system, and here they do not have to share a condition either.

How

Each feedback package follows its stream id into one configured channel. The channel applies its optional condition, queues the package, and releases it when due.

Routing by stream id

Packages arrive by event, not by tick. Remote Observation & State Capture calls ReceivePackage the moment it publishes a feedback package.

The module trims the package's StreamId and looks it up in its channel dictionary. Three things end the journey there, each logging an error: a null package, a blank StreamId, or a stream id with no matching channel — the last logging "has no channel for feedback stream". The lookup is ordinal, so matching is exact and case-sensitive.

Who does what: the path a package takes

Only one step of the path belongs to the study. The rest is the same for every package on every channel:

The default: no condition, immediate delivery

A channel with an empty Condition field is not a broken channel. It is the undegraded case, and it is what a baseline uses.

With no condition, the channel schedules the package with a delay of zero. It still goes through the same queue as every other package, so ordering behaves identically — it simply comes out again immediately, inside the same call that put it in.

How long, or whether: the two outcomes

When a channel does have a condition, it is asked one question per package, and there are exactly two possible answers. A condition either suppresses the package or returns one transmission delay.

bool TryGetTransmissionDelay(
    Package package,
    double ingressTimestampSeconds,
    out double delaySeconds);

The condition schedules at most one delivery per package. Invalid delays (NaN, infinite, or negative) are rejected; after a package enters the queue, the condition cannot duplicate or reorder it.

When a package is released

Two things drain the queue:

• Step releases every package that is due on each channel.
• ReceivePackage also drains immediately, in the same call that scheduled the package.

A zero-delay channel can deliver immediately. Otherwise, due packages are released at the next fixed tick and fan out to Operator-side State Reconstruction and, when configured, Operator-side Assistance (downlink). The realised delay can therefore be rounded up by at most one tick — 20 ms at 50 Hz.

Order of release

Packages release in ascending scheduled-release-time order, with arrival time breaking ties. A variable-delay condition can therefore reorder a stream; preserving order is a property of the chosen condition, not a guarantee of the queue. Pose and video also use independent queues, so their released samples may represent different remote times.

Operator-side State Reconstruction preserves each released representation's sampling metadata. A study that needs synchronized pose and video must align those streams explicitly.

Boundary

Contract

This stage declares no payload contract of its own. A Package goes in and the very same Package comes out, later.

What it declares is the extension point, CommunicationCondition, shared verbatim with the uplink. A condition must implement TryGetTransmissionDelay, which is handed the channel ingress timestamp so a condition modelling service capacity or queueing has what it needs. It should also override Reset() when it keeps state or randomness:

[Serializable]
public abstract class CommunicationCondition
{
    // Return false to suppress the package. Return true and set delaySeconds
    // to schedule exactly one transmission. A package cannot produce
    // multiple deliveries through this contract.
    public abstract bool TryGetTransmissionDelay(
        Package package,
        double ingressTimestampSeconds,
        out double delaySeconds);

    // Called when the channel initialises. Stateful conditions clear their
    // state here so every trial starts identically.
    public virtual void Reset()
    {
    }
}

A condition is a plain [Serializable] class — not a MonoBehaviour, not a ScriptableObject. It is stored inside the channel by [SerializeReference], which is what lets the Inspector offer every subclass in a dropdown.

The Package envelope is documented in full on the Operator-side Assistance (uplink) page. StreamId is the routing key; Payload is the field to treat carefully. A condition that pattern-matches on a concrete payload type stops being reusable across streams and across the uplink. Asking every payload the same question through an interface does not. A study-defined bandwidth condition can ask an interface for the size it needs without hard-coding a concrete payload type.

Examples

These examples follow the four conditions in the paper's Every Move You Make reconstruction. All four use the same TurtleBot, input mapping, vehicle, task, environment, and feedback channels. They differ only in Operator-side Assistance (downlink): Baseline, Network, Path, or Envelope.

Downlink Communication itself stays the same in every condition: separate robot-pose and robot-view channels, each using EveryMoveFixedDelayCondition with the current demo's configured 1,280 ms downlink delay. robot-state is not part of the paper-facing feedback path.

The paper reports a fixed 2.56 s round trip and leaves its directional split under-specified. The current demo uses 1,280 ms in each direction, so the total delay matches while the split remains an explicit demo choice.

[Serializable]
public sealed class EveryMoveFixedDelayCondition : CommunicationCondition
{
    [SerializeField] private EveryMoveCommunicationConfiguration configuration;
    [SerializeField, Min(0f)] private float fallbackDelayMilliseconds = 2560f;
    [SerializeField] private bool useConfiguredDownlinkDelay;
    [SerializeField] private float channelDelayOverrideMilliseconds = -1f;

    public override bool TryGetTransmissionDelay(
        Package package,
        double ingressTimestampSeconds,
        out double delaySeconds)
    {
        float delay = fallbackDelayMilliseconds;

        if (channelDelayOverrideMilliseconds >= 0f)
        {
            delay = channelDelayOverrideMilliseconds;
        }
        else if (configuration)
        {
            delay = useConfiguredDownlinkDelay
                ? configuration.downlinkDelayMilliseconds
                : configuration.uplinkDelayMilliseconds;
        }

        delaySeconds = delay / 1000d;
        return true;
    }
}

[Serializable]
public sealed class JitterDelayCondition : CommunicationCondition
{
    [SerializeField, Min(0f)] private float baseDelayMilliseconds = 200f;
    [SerializeField, Min(0f)] private float jitterMilliseconds = 60f;
    [SerializeField] private int seed = 20260817;

    private System.Random random;

    // Called when the channel initialises, so every trial replays the same
    // draws from the same seed.
    public override void Reset()
    {
        random = new System.Random(seed);
    }

    public override bool TryGetTransmissionDelay(
        Package package,
        double ingressTimestampSeconds,
        out double delaySeconds)
    {
        random ??= new System.Random(seed);

        // Uniform in [-jitter, +jitter] around the base delay, floored at zero
        // because a negative delay is rejected by the channel.
        double offset = (random.NextDouble() * 2d - 1d) * jitterMilliseconds;
        delaySeconds =
            Math.Max(0d, (baseDelayMilliseconds + offset) / 1000d);
        return true;
    }
}

// Monotonic variant: jitter, but never out of order.
double releaseSeconds = ingressTimestampSeconds + jitteredDelaySeconds;
releaseSeconds = Math.Max(releaseSeconds, lastReleaseSeconds);
lastReleaseSeconds = releaseSeconds;
delaySeconds = releaseSeconds - ingressTimestampSeconds;

[Serializable]
public sealed class BandwidthLimitedCondition : CommunicationCondition
{
    [SerializeField, Min(1f)] private float linkRateBitsPerSecond = 1000000f;

    // Used only for payloads that do not report a size of their own.
    [SerializeField, Min(1f)] private float fallbackPacketBits = 200000f;

    // Shed rather than queue once the backlog exceeds this.
    [SerializeField, Min(0f)] private float maximumQueueingMilliseconds = 250f;

    private double nextFreeSeconds;

    public override void Reset()
    {
        nextFreeSeconds = 0d;
    }

    public override bool TryGetTransmissionDelay(
        Package package,
        double ingressTimestampSeconds,
        out double delaySeconds)
    {
        // Ask the payload how big it declares itself to be. This is a question,
        // not a type check: any payload implementing the interface works, so the
        // condition stays reusable across streams and both directions.
        double bits = package.Payload is IDeclaredSizePayload sized
            ? sized.DeclaredBits
            : fallbackPacketBits;

        double serialisationSeconds = bits / linkRateBitsPerSecond;

        // The link is busy until nextFreeSeconds; this package starts then,
        // or now if the link is already idle.
        double startSeconds =
            Math.Max(ingressTimestampSeconds, nextFreeSeconds);
        double queueingSeconds = startSeconds - ingressTimestampSeconds;

        if (queueingSeconds > maximumQueueingMilliseconds / 1000d)
        {
            // Backlog too deep: suppress instead of queueing further.
            delaySeconds = 0d;
            return false;
        }

        nextFreeSeconds = startSeconds + serialisationSeconds;
        delaySeconds = nextFreeSeconds - ingressTimestampSeconds;
        return true;
    }
}

// A payload that reports its own transport size. Study-side: the Kernel
// encodes nothing to bytes, so this is the study's sizing model.
public interface IDeclaredSizePayload
{
    double DeclaredBits { get; }
}

// The demo's existing frame payload, with one interface and one property added.
public sealed class ViewFramePackage : IDisposable, IDeclaredSizePayload
{
    public RenderTexture Frame { get; }   // ... existing members unchanged

    // Resolution is measured from the frame that was actually captured;
    // bits per pixel is the study's declared figure, standing in for
    // whatever codec the study is claiming to model.
    public const double DeclaredBitsPerPixel = 8d;

    public double DeclaredBits =>
        (double)Frame.width * Frame.height * DeclaredBitsPerPixel;
}

Different conditions on uplink and downlink

The two communication modules are configured separately, so an experiment can degrade each direction differently — or degrade one and leave the other clean.

The shipped TurtleBot configuration uses separate channel instances and keeps the two directions independently configurable:

Each channel has its own condition instance. In the shipped demo, all three configured channels use the same fixed-delay class, but uplink reads the configured uplink delay and the two downlink channels read the configured downlink delay. robot-state is captured locally but has no current demo consumer and is not added to Downlink Communication.

A study can assign different condition classes to different channels, but that is an extension of the shipped configuration rather than an additional TurtleBot demo behavior.

Which is also the trap. Two channels that should contend for one link budget will not, because a condition can only ever see its own channel. A study that needs a genuinely shared link has to write a condition whose instances share state deliberately — through a common ScriptableObject, say — and report that it did.

Config

Downlink Communication is a Unity component, so it's configured like the rest of a study: in the Inspector, not in code.

1. Add the module to the agent. Add DownlinkCommunicationKernel to the same GameObject as TeleroboticsAgent. Every selected module must live on that one GameObject.
2. Assign it to the agent's Downlink Communication field. This field is optional in isolation but not in practice — see the all-or-nothing warning below.
3. Add one channel per feedback stream. The Channels list starts empty and at least one entry is required. Type each stream id to match exactly what Remote Observation & State Capture publishes — in the demo, robot-pose and robot-view.
4. Choose a condition per channel, or leave it empty. The Condition field is a [SerializeReference] slot, so the Inspector lists every CommunicationCondition subclass in your project — the Kernel contributes none. Leaving it empty is a valid, deliberate configuration: that channel delivers immediately.

Each entry in the Channels list has exactly two fields: