Apollo Avatar Winch Control

Andi Lamprecht ·2026-05-11· 2 min read· Accepted

Avatar Winch Control

Context

During ground testing, we found that we could not test the connection between the mavlink-shim and the winch without performing a delivery (impossible during ground testing).

Therefore, it would be beneficial for testing purposes to be able to exercise the winch with a greater degree of control than currently available.

However, we would not want these commands available to the operator outside of testing.
The operator should only be able to command the UAV to abandon_line, since the rest of the winch control is automatically handled by Uncrew.

Decision

We will create a single new RPC in the Avatar’s PilotCommand service to expose this functionality.
The functionality of this RPC can be disabled in production via configuration (ex. feature flag, environment variable).

API

service PilotCommandService {
    ...
    rpc DebugWinchCommand(DebugWinchCommandRequest) returns (DebugWinchCommandResponse);
}

message DebugWinchCommandRequest {
    types.v1.UavID uav_id = 1;
    oneof action {
        WinchRelax relax = 2;
        WinchRelativeLengthControl relative_length_control= 3;
        WinchRateControl rate_control = 4;
        WinchLock lock = 5;
        WinchDeliver deliver = 6;
        WinchHold hold = 7;
        WinchRetract retract = 8;
        WinchLoadLine load_line = 9;
        WinchAbandonLine abandon_line = 10;
        WinchLoadPayload load_payload = 11;
    }
}

message DebugWinchCommandResponse {
    PilotCommandResult result = 1;
}

Alternatives Considered

Debug Service

We also considered creating a separate PilotCommandDebug service.
This service would be able to be disabled in production via configuration (ex. feature flag, environment variable).
Other debug RPCs could also live in this service.
It was decided that this would be too much added complexity for (what is right now) a single RPC.
In the future if we determine more debug RPCs are necessary, we can reevaluate the need for a separate service.