"""控制指令发送抽象（语义接口，对应 C++ ICommandTransport + 网关门面）。

C++ 版的 ICommandTransport 是字节流传输抽象（Send(bytes)），MAVLink 编码
在网关内完成；Python 版采用 MAVSDK 语义映射后，"传输"被抽象为设定点级
指令发送。本 Protocol 仅声明门面接口，供胶水层依赖注入与 mock 测试。

异常约定：实现不得向外抛传输层异常，失败一律返回 False（网关已捕获）。
"""

from typing import Optional, Protocol, runtime_checkable

from .types import ControlOutput


@runtime_checkable
class CommandSender(Protocol):
    async def start(self) -> bool:
        """进入 offboard 模式。失败返回 False。"""
        ...

    async def send_velocity_heading(self, output: ControlOutput,
                                    time_boot_ms: Optional[int] = None) -> bool:
        """发送速度+航向意图（ControlMode.VELOCITY_HEADING）。失败返回 False。"""
        ...

    async def send_brake_hover(self, time_boot_ms: Optional[int] = None) -> bool:
        """发送零速刹车/悬停意图（ControlMode.BRAKE_HOVER）。失败返回 False。"""
        ...

    async def stop(self) -> None:
        """退出 offboard 模式（结束时调用）。"""
        ...