Uplink Communication

What

Uplink Communication sits between the operator side of the loop and the robot side. In brief:

• It is a required module: a study always has exactly one, and every command the stages upstream produce passes through it.
• It holds a list of channels — one per command stream, identified by its stream id, each with its own scheduled queue.
• A communication condition is an object that decides, per package, how long it waits and whether it is sent at all. It is optional, and configured per channel — so one stream can be degraded while another is left alone. 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 is sealed — not abstract, not generic. You never subclass it. What a study writes, if anything, is a condition.

Why

This module is the uplink half of DR1, configurable communication conditions, the first design requirement in UNITE's scoping review. The review found delay imposed on control commands, on video, on telemetry and on force feedback. It was fixed in some studies, followed a time-varying function in others, and was sampled from a distribution in others again, sometimes alongside impairments like packet loss. The mechanism was almost never described well enough to copy.

DR1 concludes that a reported delay magnitude alone is not enough to reconstruct the condition that produced it. The requirement is therefore not "support delay" but to make five things explicit and configurable: the stream affected, the direction, the delay magnitude, its temporal behaviour, and any additional impairment. Channels supply the first, having a module on each path supplies the second, and the condition supplies the rest.

The direction is easy to underrate. Maag et al. compared 200/0, 0/200 and 100/100 ms uplink/downlink splits and found the same total delay produced different results depending on how it was allocated. A round-trip figure cannot express that, so uplink and downlink are configured separately here instead of sharing one latency setting.

The module is required; the condition is not. Commands travel the same path whether or not a study degrades them, so a baseline arm is an empty Condition field rather than different code. Between two arms of a study, the only difference is the factor being manipulated.

How

The whole model is one line — package → channel for its stream → optional condition → scheduled queue → release — and only the condition belongs to the study. The rest is the same for every package on every channel.

Routing by stream id

Packages arrive by event, not by tick. Whatever stage sits upstream — Operator-side Assistance (uplink) if the study uses one, otherwise Command Mapping & Encoding — calls ReceivePackage the moment it publishes. The module trims the package's StreamId and looks it up in its channel dictionary; a null package, a blank stream id, or one with no matching channel each log an error and go no further.

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

An empty Condition field is the undegraded baseline. The package still uses the channel queue, but its zero delay allows immediate release.

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; it cannot duplicate, reorder, or later revise a package already handed to the queue.

When a package is released

The queue releases due packages during the module step; a zero-delay package can also release immediately when it enters. The module adds no intentional latency, but release is checked at the next fixed tick, so the realised delay can be rounded up by at most one tick. The constant-delay example shows this.

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.

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. 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.

One validity rule applies to whatever the condition returns. A delaySeconds that is NaN, infinite or negative is rejected: the channel logs an error and drops the package rather than queueing it. So a condition that computes a delay arithmetically should clamp its own result — the jitter example floors its draw at zero for exactly this reason.

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 downlink. Asking every payload the same question through an interface does not — see the bandwidth example, where the condition needs a size and only the payload can supply one.

Examples

Three worked conditions: a constant delay, a variable delay, and a constrained bandwidth link.

Each tab gives the condition, then the release schedule it produces. Those schedules can be re-derived from the code, given the inputs each table states and three facts about the machinery:

• The agent samples the clock once per tick, so every package entering a channel during one FixedUpdate shares the same ingressTimestampSeconds.
• A release time is absolute: the channel queues the package at ingress + delaySeconds.
• The queue releases while releaseTime ≤ now, checked on every tick and again immediately when a package is scheduled.

The examples assume the demo's 50 Hz loop producing one command per tick on wheel-velocity-command, with ticks landing on 0.000 s, 0.020 s, 0.040 s and so on. That last part is an idealisation for readable numbers — real timestamps come from Time.realtimeSinceStartupAsDouble and are wall-clock — but nothing about the behaviour depends on it.

[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 = 50000f;

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

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

    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;
    }
}

One study, several streams

A condition is configured per channel, so a study is not choosing one degradation for the whole apparatus. It can degrade the stream its question is about and leave the others alone, so that any effect is attributable to that stream:

The demo publishes wheel-velocity-command. A study can add other stream ids when it needs them. Each channel holds its own condition instance with its own state and its own random stream, so nothing on one stream can reach another. Combined with the downlink module, which is configured separately, that is how the directional allocation in the second study pattern is expressed — one budget, divided explicitly, with everything else held still.

Config

Uplink 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 UplinkCommunicationModule to the same GameObject as TeleroboticsAgent. Every selected module must live on that one GameObject.
2. Assign it to the agent's Uplink Communication field. This field is required, alongside Input Provider, Command Mapping & Encoding and the Vehicle/Robot Model.
3. Add one channel per command stream. The Channels list starts empty and at least one entry is required. Type the stream id to match exactly what Command Mapping & Encoding publishes on its Output Stream Id field — in the demo, wheel-velocity-command.
4. Choose a condition, 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: