Operator-side Assistance (downlink)

What

Operator-side Assistance produces prediction, state estimation, filtering, warnings, or visualisations from declared inputs. Remote information comes through Operator-side State Reconstruction; local command history can also drive assistance without any new remote observation.

It does not apply delay or update the authoritative robot. Base reconstructed feedback reaches presentation independently. A technique that replaces or hides that feedback must define how its presentation implementation uses the assistance output.

Why

The same delayed feedback can support different operator-side techniques. A baseline can show only the delayed video, while another condition can add a command timeline, a predicted path, or an uncertainty envelope. Keeping that choice in one module lets a study vary the assistance technique while holding the vehicle, task, observation streams, and communication conditions fixed.

How

The Kernel queues explicitly reconstructed results before calling ProcessPackage, then calls UpdateAssistance once per tick. A technique consumes only the reconstructed contracts it needs. It may publish output from local dependencies even when no reconstruction result arrived.

• Input. Required reconstructed information and declared dependencies, such as command history, vehicle configuration, route information, communication delay, or a reconstructed map.
• Output. Study-defined assistance packages on declared streams. Base feedback need not be forwarded.
• Timing. Assistance runs after reconstruction and before presentation in the same kernel cycle.

Boundary

Contract

Implementations inherit the package queue and publish through PackageProduced. The base class rejects input whose payload is not a ReconstructedFeedbackContract, calls ProcessPackage for reconstructed results, and then calls UpdateAssistance.

using System;
using System.Collections.Generic;
using Unite.Core;
using UnityEngine;

namespace Unite.Kernel
{
    /// <summary>
    /// Optional operator-side attachment point after operator-side state
    /// reconstruction and before feedback presentation. Reconstruction also
    /// feeds presentation directly; assistance need not forward base feedback.
    /// </summary>
    public abstract class DownlinkOperatorSideAssistanceModule
        : TeleroboticsModule, IPackageSource, IPackageConsumer
    {
        private readonly Queue<Package> pendingPackages = new Queue<Package>();

        public event Action<Package> PackageProduced;

        internal sealed override int ExecutionOrder => 900;

        public void ReceivePackage(Package package)
        {
            if (package == null || !(package.Payload is ReconstructedFeedbackContract))
            {
                Debug.LogError(
                    $"{GetType().Name} requires a reconstructed feedback package.", this);
                return;
            }

            pendingPackages.Enqueue(package);
        }

        internal sealed override void Step(double timestampSeconds)
        {
            while (pendingPackages.Count > 0)
            {
                ProcessPackage(pendingPackages.Dequeue(), timestampSeconds);
            }

            UpdateAssistance(timestampSeconds);
        }

        /// <summary>
        /// Publishes one feedback package to the downstream presentation stage.
        /// </summary>
        protected void PublishPackage(Package package)
        {
            if (package == null)
            {
                Debug.LogError($"{GetType().Name} tried to publish a null package.", this);
                return;
            }

            PackageProduced?.Invoke(package);
        }

        /// <summary>
        /// Processes one reconstructed result when needed by the technique.
        /// Output supplements the independent reconstruction-to-presentation
        /// path. Replacing or hiding base feedback requires a study-defined
        /// presentation contract; omitting output does not suppress that path.
        /// </summary>
        protected abstract void ProcessPackage(
            Package package,
            double timestampSeconds);

        /// <summary>
        /// Allows assistance implementations to publish locally computed output
        /// from declared dependencies even when no downlink package was released
        /// during this tick.
        /// </summary>
        protected virtual void UpdateAssistance(double timestampSeconds)
        {
        }
    }
}

• Call PublishPackage for assistance output; there is no need to forward the base feedback.
• Publish a new Package when the assistance output is supplementary or transformed.
• Preserve the source observation metadata for derived outputs and use a declared assistance stream. Producing no output does not hide independently reconstructed feedback.
• Do not modify the vehicle or the authoritative remote state from this module.

Examples

The four conditions keep communication, vehicle, task, and observation settings fixed while changing the presentation assistance.

public abstract class EveryMoveAssistanceBase : DownlinkOperatorSideAssistanceModule
{
    protected override void ProcessPackage(
        Package package,
        double timestamp)
    {
        // No assistance output; reconstruction supplies the base video.
    }
}

[EveryMoveCondition("condition-baseline")]
public sealed partial class NoAssistance
    : EveryMoveAssistanceBase
{
}

[EveryMoveCondition("condition-network")]
public sealed partial class CommandTimelineAssistance
    : CommandTimelineAssistanceBase
{
    // The shared base converts mapped commands into
    // NetworkTimelinePackage feedback.
}

[EveryMoveCondition("condition-path")]
public sealed partial class IdealTrajectoryAssistance
    : TrajectoryAssistanceBase
{
    protected override object BuildOverlayPayload(
        ReconstructedMotionState state,
        PredictedPose[] centre)
    {
        PredictedPose[] left = Offset(
            centre, -vehicleConfiguration.wheelbase * .5f);
        PredictedPose[] right = Offset(
            centre, vehicleConfiguration.wheelbase * .5f);
        return new PathAssistancePackage(centre, left, right);
    }
}

[EveryMoveCondition("condition-envelope")]
public sealed partial class WorstCaseEnvelopeAssistance
    : TrajectoryAssistanceBase
{
    protected override object BuildOverlayPayload(
        ReconstructedMotionState state,
        PredictedPose[] centre)
    {
        float uncertainty = Mathf.Clamp01(
            vehicleConfiguration.wheelSlipFactor *
                vehicleConfiguration.terrainRoughness +
            vehicleConfiguration.motorResponseVariation +
            vehicleConfiguration.wheelRadiusVariation +
            vehicleConfiguration.encoderNoise +
            vehicleConfiguration.vibrationIntensity);
        float offset = vehicleConfiguration.wheelbase * .5f;

        PredictedPose[] left = Integrate(
            state, 1f - uncertainty, 1f, -offset);
        PredictedPose[] right = Integrate(
            state, 1f, 1f - uncertainty, offset);
        return new EnvelopeAssistancePackage(
            centre, left, right,
            Integrate(state, 1f - uncertainty * .5f, 1f, 0f),
            Integrate(state, 1f, 1f - uncertainty * .5f, 0f));
    }
}

Config

1. Implement DownlinkOperatorSideAssistanceModule in the study's Runtime assembly.
2. Attach one selected implementation to the TeleroboticsAgent; the module connects to the configured downlink feedback path.
3. Declare and wire only the dependencies the technique needs. The demo's trajectory assistance uses the uplink queue, vehicle configuration, communication configuration, and the copied motion state published by reconstruction, aligned to the reconstructed video exposure.
4. Configure the selected assistance component in the Inspector for the study condition.