from uas.action.action_type import ActionType # ══════════════════════════════════════════════════════════════════ # ActionType 参数定义表 # 每个参数字段： # type : Python 类型名称字符串 # description : 参数说明 # default : 默认值（None 表示必填，无默认值） # required : 是否必填 # enum : 可选枚举值列表（可选字段） # unit : 单位（可选字段） # range : 取值范围 [min, max]（可选字段） # ══════════════════════════════════════════════════════════════════ ACTION_PARAMS: dict[ActionType, dict] = { # ══════════════════════════════════════════ # 控制类 # ══════════════════════════════════════════ ActionType.PAUSE: { "reason": { "type": "str", "description": "暂停原因描述，用于日志记录与态势上报", "default": "manual_pause", "required": False, "enum": ["manual_pause", "low_battery", "signal_lost", "obstacle_detected", "weather_warning", "await_authorization"], }, "hold_position": { "type": "bool", "description": "暂停时是否原地悬停保持位置（True=悬停，False=保持当前运动状态）", "default": True, "required": False, }, "max_hold_duration": { "type": "float", "description": "最大暂停等待时长，超时后自动执行超时策略", "default": 300.0, "required": False, "unit": "秒", "range": [1.0, 3600.0], }, "timeout_action": { "type": "str", "description": "超过最大等待时长后的自动处置动作", "default": "return_to_home", "required": False, "enum": ["return_to_home", "land", "abort", "resume"], }, }, ActionType.RESUME: { "resume_mode": { "type": "str", "description": "恢复执行模式", "default": "continue_from_pause", "required": False, "enum": ["continue_from_pause", "restart_segment", "restart_mission"], }, "speed_ramp_up_duration": { "type": "float", "description": "恢复后速度渐增时长，避免突变", "default": 3.0, "required": False, "unit": "秒", "range": [0.0, 30.0], }, "verify_system_before_resume": { "type": "bool", "description": "恢复前是否执行快速系统验证", "default": True, "required": False, }, }, ActionType.STOP: { "stop_mode": { "type": "str", "description": "停止模式", "default": "graceful", "required": True, "enum": ["graceful", "immediate", "safe_land"], }, "save_mission_state": { "type": "bool", "description": "停止前是否保存当前任务状态，以便后续恢复", "default": True, "required": False, }, "notify_ground_station": { "type": "bool", "description": "停止时是否向地面站发送通知", "default": True, "required": False, }, "final_action": { "type": "str", "description": "任务停止后的最终动作", "default": "hover", "required": False, "enum": ["hover", "land", "return_to_home", "none"], }, }, ActionType.ABORT: { "abort_reason": { "type": "str", "description": "中止原因", "default": None, "required": True, "enum": ["system_failure", "threat_detected", "mission_compromised", "operator_command", "fuel_critical", "communication_lost"], }, "rollback_to_checkpoint": { "type": "bool", "description": "是否回滚到上一个安全检查点", "default": True, "required": False, }, "checkpoint_id": { "type": "str", "description": "指定回滚的检查点ID，为空则回滚到最近检查点", "default": None, "required": False, }, "emergency_return": { "type": "bool", "description": "是否立即执行紧急返航", "default": True, "required": False, }, "broadcast_abort_signal": { "type": "bool", "description": "是否向编队内其他平台广播中止信号", "default": False, "required": False, }, "data_purge": { "type": "bool", "description": "中止时是否清除敏感任务数据（防止被截获）", "default": False, "required": False, }, }, ActionType.RESET: { "reset_scope": { "type": "str", "description": "重置范围", "default": "mission", "required": True, "enum": ["mission", "navigation", "sensors", "communication", "full_system"], }, "preserve_logs": { "type": "bool", "description": "重置时是否保留日志数据", "default": True, "required": False, }, "reinitialize_sensors": { "type": "bool", "description": "重置时是否重新初始化传感器", "default": True, "required": False, }, "reset_waypoint_index": { "type": "int", "description": "重置后从第几个航点开始执行，-1 表示从头开始", "default": -1, "required": False, "range": [-1, 9999], }, }, ActionType.STANDBY: { "standby_duration": { "type": "float", "description": "待机时长，0 表示无限期待机直到收到恢复指令", "default": 0.0, "required": False, "unit": "秒", "range": [0.0, 86400.0], }, "power_mode": { "type": "str", "description": "待机功耗模式", "default": "low_power", "required": False, "enum": ["low_power", "normal", "keep_sensors_active"], }, "keep_comms_active": { "type": "bool", "description": "待机期间是否保持通信链路在线", "default": True, "required": False, }, "wakeup_trigger": { "type": "str", "description": "唤醒触发条件", "default": "command", "required": False, "enum": ["command", "timer", "event", "threat_detected"], }, "maintain_altitude": { "type": "bool", "description": "待机期间是否保持当前高度悬停", "default": True, "required": False, }, }, # ══════════════════════════════════════════ # 感知类 # ══════════════════════════════════════════ ActionType.CAPTURE_PHOTO: { "camera_id": { "type": "str", "description": "摄像机设备ID", "default": "cam_main", "required": True, "enum": ["cam_main", "cam_ir", "cam_wide", "cam_zoom", "cam_belly"], }, "resolution": { "type": "str", "description": "拍摄分辨率", "default": "4K", "required": False, "enum": ["720P", "1080P", "2K", "4K", "8K", "max"], }, "count": { "type": "int", "description": "连拍张数", "default": 1, "required": False, "range": [1, 100], }, "interval": { "type": "float", "description": "连拍间隔时长", "default": 1.0, "required": False, "unit": "秒", "range": [0.1, 60.0], }, "image_format": { "type": "str", "description": "图像存储格式", "default": "jpeg", "required": False, "enum": ["jpeg", "png", "raw", "tiff"], }, "zoom_level": { "type": "float", "description": "光学变焦倍数", "default": 1.0, "required": False, "range": [1.0, 30.0], }, "gimbal_pitch": { "type": "float", "description": "云台俯仰角，负值为向下", "default": -90.0, "required": False, "unit": "度", "range": [-90.0, 30.0], }, "gimbal_yaw": { "type": "float", "description": "云台偏航角（相对机头方向）", "default": 0.0, "required": False, "unit": "度", "range": [-180.0, 180.0], }, "auto_exposure": { "type": "bool", "description": "是否启用自动曝光", "default": True, "required": False, }, "geotagging": { "type": "bool", "description": "是否在图像中嵌入 GPS 地理坐标信息", "default": True, "required": False, }, "storage_path": { "type": "str", "description": "图像存储路径", "default": "/data/photos/", "required": False, }, }, ActionType.CAPTURE_VIDEO: { "camera_id": { "type": "str", "description": "摄像机设备ID", "default": "cam_main", "required": True, "enum": ["cam_main", "cam_ir", "cam_wide", "cam_zoom", "cam_belly"], }, "duration": { "type": "float", "description": "录制时长，0 表示持续录制直到收到停止指令", "default": 0.0, "required": False, "unit": "秒", "range": [0.0, 86400.0], }, "resolution": { "type": "str", "description": "视频分辨率", "default": "1080P", "required": False, "enum": ["720P", "1080P", "2K", "4K"], }, "fps": { "type": "int", "description": "帧率", "default": 30, "required": False, "unit": "fps", "enum": [24, 30, 60, 120], }, "video_format": { "type": "str", "description": "视频编码格式", "default": "h264", "required": False, "enum": ["h264", "h265", "mjpeg"], }, "gimbal_pitch": { "type": "float", "description": "云台俯仰角", "default": -45.0, "required": False, "unit": "度", "range": [-90.0, 30.0], }, "stabilization": { "type": "bool", "description": "是否启用电子防抖", "default": True, "required": False, }, "stream_live": { "type": "bool", "description": "是否同步推送实时视频流至地面站", "default": True, "required": False, }, "stream_url": { "type": "str", "description": "实时流推送地址（RTSP/RTMP）", "default": None, "required": False, }, "storage_path": { "type": "str", "description": "视频本地存储路径", "default": "/data/videos/", "required": False, }, "max_file_size_mb": { "type": "int", "description": "单个视频文件最大体积，超出后自动分段", "default": 4096, "required": False, "unit": "MB", "range": [64, 65536], }, }, ActionType.RECOGNIZE_TARGET: { "target_type": { "type": "str", "description": "目标类别", "default": "any", "required": True, "enum": ["person", "vehicle", "aircraft", "vessel", "weapon", "building", "radar", "uav", "any"], }, "sensor_id": { "type": "str", "description": "用于识别的传感器ID", "default": "cam_main", "required": False, "enum": ["cam_main", "cam_ir", "cam_wide", "cam_zoom", "sar", "lidar"], }, "confidence_threshold": { "type": "float", "description": "目标识别置信度阈值，低于该值不上报", "default": 0.85, "required": False, "range": [0.0, 1.0], }, "max_targets": { "type": "int", "description": "单次识别最大目标数量", "default": 10, "required": False, "range": [1, 100], }, "report_mode": { "type": "str", "description": "识别结果上报模式", "default": "realtime", "required": False, "enum": ["realtime", "on_detect", "batch", "silent"], }, "use_ai_model": { "type": "str", "description": "使用的 AI 识别模型名称", "default": "yolo_v8_military", "required": False, }, "roi": { "type": "dict", "description": "感兴趣区域（图像坐标归一化），格式 {x, y, w, h}", "default": None, "required": False, }, "enable_classification": { "type": "bool", "description": "是否对识别目标进行细粒度分类（如车辆型号）", "default": False, "required": False, }, }, ActionType.SCAN_ENVIRONMENT: { "scan_mode": { "type": "str", "description": "扫描模式", "default": "360_horizontal", "required": True, "enum": ["360_horizontal", "360_full", "sector", "forward", "downward"], }, "sensor_types": { "type": "list", "description": "参与扫描的传感器列表", "default": ["cam_main", "cam_ir"], "required": False, "enum": ["cam_main", "cam_ir", "lidar", "radar", "sar", "multispectral", "hyperspectral"], }, "scan_range": { "type": "float", "description": "扫描有效距离", "default": 1000.0, "required": False, "unit": "米", "range": [10.0, 50000.0], }, "sector_start_angle": { "type": "float", "description": "扇形扫描起始角度（scan_mode=sector 时有效）", "default": -60.0, "required": False, "unit": "度", "range": [-180.0, 180.0], }, "sector_end_angle": { "type": "float", "description": "扇形扫描终止角度（scan_mode=sector 时有效）", "default": 60.0, "required": False, "unit": "度", "range": [-180.0, 180.0], }, "scan_duration": { "type": "float", "description": "单次扫描持续时长，0 表示持续扫描", "default": 0.0, "required": False, "unit": "秒", "range": [0.0, 3600.0], }, "resolution": { "type": "str", "description": "扫描分辨率等级", "default": "medium", "required": False, "enum": ["low", "medium", "high", "ultra"], }, "report_interval": { "type": "float", "description": "扫描结果上报间隔", "default": 5.0, "required": False, "unit": "秒", "range": [0.5, 60.0], }, "anomaly_alert": { "type": "bool", "description": "发现异常目标时是否自动告警", "default": True, "required": False, }, }, ActionType.DETECT_OBSTACLE: { "detection_range": { "type": "float", "description": "障碍物探测距离", "default": 30.0, "required": False, "unit": "米", "range": [1.0, 500.0], }, "sensor_id": { "type": "str", "description": "障碍物探测传感器", "default": "lidar", "required": False, "enum": ["lidar", "radar", "ultrasonic", "stereo_cam", "tof", "fusion"], }, "sensitivity": { "type": "str", "description": "探测灵敏度等级", "default": "medium", "required": False, "enum": ["low", "medium", "high"], }, "avoidance_action": { "type": "str", "description": "检测到障碍物后的自动规避动作", "default": "stop_and_hover", "required": False, "enum": ["stop_and_hover", "reroute", "ascend", "alert_only", "none"], }, "min_safe_distance": { "type": "float", "description": "触发规避的最小安全距离", "default": 5.0, "required": False, "unit": "米", "range": [0.5, 100.0], }, "detection_directions": { "type": "list", "description": "探测方向列表", "default": ["forward", "downward"], "required": False, "enum": ["forward", "backward", "left", "right", "upward", "downward", "all"], }, "continuous": { "type": "bool", "description": "是否持续探测（True=持续，False=单次）", "default": True, "required": False, }, "report_to_gcs": { "type": "bool", "description": "是否将障碍物信息上报地面站", "default": True, "required": False, }, }, ActionType.TRACK_TARGET: { "target_id": { "type": "str", "description": "被跟踪目标的唯一标识符", "default": None, "required": True, }, "tracking_mode": { "type": "str", "description": "跟踪模式", "default": "visual_lock", "required": True, "enum": ["visual_lock", "ir_lock", "radar_lock", "gps_follow", "multi_sensor_fusion"], }, "sensor_id": { "type": "str", "description": "主跟踪传感器", "default": "cam_main", "required": False, "enum": ["cam_main", "cam_ir", "cam_zoom", "radar", "lidar"], }, "follow_distance": { "type": "float", "description": "跟踪保持距离", "default": 100.0, "required": False, "unit": "米", "range": [5.0, 5000.0], }, "follow_altitude_offset": { "type": "float", "description": "相对目标的高度偏移量", "default": 50.0, "required": False, "unit": "米", "range": [-100.0, 500.0], }, "max_tracking_duration": { "type": "float", "description": "最大跟踪时长，0 表示持续跟踪", "default": 0.0, "required": False, "unit": "秒", "range": [0.0, 86400.0], }, "lost_target_action": { "type": "str", "description": "目标丢失后的处置动作", "default": "hover_and_search", "required": False, "enum": ["hover_and_search", "return_to_last_position", "abort_tracking", "alert_operator"], }, "record_during_tracking": { "type": "bool", "description": "跟踪期间是否同步录像", "default": True, "required": False, }, "gimbal_lock": { "type": "bool", "description": "是否锁定云台始终对准目标", "default": True, "required": False, }, }, # ══════════════════════════════════════════ # 系统类 # ══════════════════════════════════════════ ActionType.SYSTEM_RESTART: { "subsystem_id": { "type": "str", "description": "重启的子系统标识，all 表示整机重启", "default": "all", "required": True, "enum": ["all", "flight_controller", "payload", "navigation", "communication", "ai_processor", "gimbal"], }, "reboot_delay": { "type": "float", "description": "执行重启前的等待时延", "default": 5.0, "required": False, "unit": "秒", "range": [0.0, 60.0], }, "safe_land_before_restart": { "type": "bool", "description": "整机重启前是否先执行安全降落", "default": True, "required": False, }, "notify_before_restart": { "type": "bool", "description": "重启前是否向地面站发送通知", "default": True, "required": False, }, "auto_resume_after_restart": { "type": "bool", "description": "重启完成后是否自动恢复任务", "default": False, "required": False, }, }, ActionType.SYSTEM_SHUTDOWN: { "shutdown_mode": { "type": "str", "description": "关机模式", "default": "graceful", "required": True, "enum": ["graceful", "immediate", "safe_land_then_shutdown"], }, "shutdown_delay": { "type": "float", "description": "执行关机前的等待时延", "default": 10.0, "required": False, "unit": "秒", "range": [0.0, 120.0], }, "save_state_before_shutdown": { "type": "bool", "description": "关机前是否保存系统状态快照", "default": True, "required": False, }, "upload_logs_before_shutdown": { "type": "bool", "description": "关机前是否上传飞行日志至地面站", "default": True, "required": False, }, }, ActionType.SYSTEM_DIAGNOSE: { "diagnosis_scope": { "type": "list", "description": "诊断范围列表", "default": ["all"], "required": False, "enum": ["all", "flight_controller", "sensors", "battery", "communication", "navigation", "payload", "motors"], }, "report_level": { "type": "str", "description": "诊断报告详细程度", "default": "standard", "required": False, "enum": ["minimal", "standard", "verbose"], }, "auto_fix": { "type": "bool", "description": "发现可修复问题时是否自动修复", "default": False, "required": False, }, "report_destination": { "type": "str", "description": "诊断报告发送目标", "default": "ground_station", "required": False, "enum": ["ground_station", "local_log", "both"], }, "timeout": { "type": "float", "description": "诊断超时时间", "default": 30.0, "required": False, "unit": "秒", "range": [5.0, 300.0], }, "abort_mission_on_critical": { "type": "bool", "description": "发现严重故障时是否自动中止任务", "default": True, "required": False, }, }, ActionType.SYSTEM_CALIBRATE: { "device_id": { "type": "str", "description": "待校准设备标识", "default": None, "required": True, "enum": ["imu", "compass", "barometer", "camera_gimbal", "lidar", "radar", "ir_sensor", "gps", "all_sensors"], }, "calibration_type": { "type": "str", "description": "校准类型", "default": "standard", "required": False, "enum": ["standard", "quick", "factory_reset", "field_calibration"], }, "require_stationary": { "type": "bool", "description": "校准期间是否要求平台静止", "default": True, "required": False, }, "calibration_environment": { "type": "str", "description": "校准环境条件", "default": "auto_detect", "required": False, "enum": ["auto_detect", "indoor", "outdoor", "magnetic_clean"], }, "timeout": { "type": "float", "description": "校准超时时间", "default": 60.0, "required": False, "unit": "秒", "range": [10.0, 600.0], }, "abort_on_failure": { "type": "bool", "description": "校准失败时是否中止任务", "default": True, "required": False, }, }, ActionType.SYSTEM_UPDATE_CONFIG: { "config_key": { "type": "str", "description": "配置项键名（支持点分路径，如 flight.max_speed）", "default": None, "required": True, }, "config_value": { "type": "any", "description": "配置项新值", "default": None, "required": True, }, "config_scope": { "type": "str", "description": "配置作用范围", "default": "mission", "required": False, "enum": ["mission", "session", "persistent"], }, "validate_before_apply": { "type": "bool", "description": "应用前是否校验配置合法性", "default": True, "required": False, }, "rollback_on_error": { "type": "bool", "description": "配置应用失败时是否自动回滚", "default": True, "required": False, }, "notify_ground_station": { "type": "bool", "description": "配置变更后是否通知地面站", "default": True, "required": False, }, }, ActionType.SYSTEM_SELF_CHECK: { "check_scope": { "type": "list", "description": "自检范围", "default": ["critical"], "required": False, "enum": ["critical", "sensors", "actuators", "communication", "navigation", "payload", "battery", "all"], }, "check_level": { "type": "str", "description": "自检深度等级", "default": "standard", "required": False, "enum": ["quick", "standard", "deep"], }, "block_mission_on_failure": { "type": "bool", "description": "自检未通过时是否阻止任务继续执行", "default": True, "required": False, }, "timeout": { "type": "float", "description": "自检超时时间", "default": 20.0, "required": False, "unit": "秒", "range": [5.0, 120.0], }, "report_destination": { "type": "str", "description": "自检结果发送目标", "default": "ground_station", "required": False, "enum": ["ground_station", "local_log", "both"], }, }, # ══════════════════════════════════════════ # 网络类 # ══════════════════════════════════════════ ActionType.NETWORK_CONNECT: { "target_node_id": { "type": "str", "description": "目标节点标识（地面站/中继/云端）", "default": "ground_station_primary", "required": True, }, "protocol": { "type": "str", "description": "通信协议", "default": "mavlink", "required": False, "enum": ["mavlink", "rtsp", "mqtt", "websocket", "custom_military"], }, "frequency_mhz": { "type": "float", "description": "通信频率", "default": 900.0, "required": False, "unit": "MHz", "range": [100.0, 6000.0], }, "encryption": { "type": "str", "description": "加密方式", "default": "aes256", "required": False, "enum": ["none", "aes128", "aes256", "military_grade"], }, "timeout": { "type": "float", "description": "连接超时时间", "default": 10.0, "required": False, "unit": "秒", "range": [1.0, 60.0], }, "retry_count": { "type": "int", "description": "连接失败后重试次数", "default": 3, "required": False, "range": [0, 10], }, "fallback_node_id": { "type": "str", "description": "主节点连接失败时的备用节点ID", "default": None, "required": False, }, "bandwidth_limit_kbps": { "type": "int", "description": "带宽限制，0 表示不限制", "default": 0, "required": False, "unit": "Kbps", "range": [0, 1000000], }, }, ActionType.NETWORK_DISCONNECT: { "connection_id": { "type": "str", "description": "要断开的连接标识符，all 表示断开所有连接", "default": "all", "required": True, }, "graceful": { "type": "bool", "description": "是否优雅断开（等待数据传输完成后再断开）", "default": True, "required": False, }, "send_disconnect_notice": { "type": "bool", "description": "断开前是否向对端发送断开通知", "default": True, "required": False, }, "flush_buffer_before_disconnect": { "type": "bool", "description": "断开前是否清空发送缓冲区", "default": True, "required": False, }, }, ActionType.NETWORK_SEND_DATA: { "target_node_id": { "type": "str", "description": "数据接收节点标识", "default": "ground_station_primary", "required": True, }, "data_type": { "type": "str", "description": "发送数据类型", "default": "telemetry", "required": True, "enum": ["telemetry", "image", "video_stream", "log", "sensor_data", "mission_report", "alert", "custom"], }, "data_payload": { "type": "dict", "description": "数据内容（data_type=custom 时使用）", "default": None, "required": False, }, "priority": { "type": "str", "description": "数据传输优先级", "default": "normal", "required": False, "enum": ["low", "normal", "high", "critical"], }, "compression": { "type": "str", "description": "数据压缩方式", "default": "auto", "required": False, "enum": ["none", "gzip", "lz4", "auto"], }, "confirm_receipt": { "type": "bool", "description": "是否要求接收方确认收到", "default": True, "required": False, }, "retry_on_failure": { "type": "bool", "description": "发送失败时是否自动重试", "default": True, "required": False, }, "max_retries": { "type": "int", "description": "最大重试次数", "default": 3, "required": False, "range": [0, 10], }, "encrypt_payload": { "type": "bool", "description": "是否对数据内容加密", "default": True, "required": False, }, }, ActionType.NETWORK_SYNC: { "sync_scope": { "type": "list", "description": "同步数据范围", "default": ["mission_data"], "required": True, "enum": ["mission_data", "flight_logs", "sensor_data", "images", "videos", "config", "all"], }, "sync_mode": { "type": "str", "description": "同步模式", "default": "incremental", "required": False, "enum": ["incremental", "full", "delta"], }, "target_node_id": { "type": "str", "description": "同步目标节点", "default": "ground_station_primary", "required": False, }, "bandwidth_limit_kbps": { "type": "int", "description": "同步带宽限制，0 表示不限制", "default": 0, "required": False, "unit": "Kbps", "range": [0, 1000000], }, "timeout": { "type": "float", "description": "同步超时时间", "default": 120.0, "required": False, "unit": "秒", "range": [10.0, 3600.0], }, "verify_integrity": { "type": "bool", "description": "同步完成后是否校验数据完整性", "default": True, "required": False, }, "delete_after_sync": { "type": "bool", "description": "同步成功后是否删除本地副本（释放存储）", "default": False, "required": False, }, "compress_before_sync": { "type": "bool", "description": "同步前是否压缩数据", "default": True, "required": False, }, }, # ══════════════════════════════════════════ # 运动类 # ══════════════════════════════════════════ ActionType.MOTION_MOVE: { "target_position": { "type": "dict", "description": "目标位置坐标，格式 {lat, lon, alt}（WGS-84）", "default": None, "required": True, }, "speed": { "type": "float", "description": "移动速度", "default": 10.0, "required": False, "unit": "m/s", "range": [0.1, 100.0], }, "altitude_mode": { "type": "str", "description": "高度模式", "default": "absolute", "required": False, "enum": ["absolute", "relative_to_ground", "terrain_following"], }, "heading_mode": { "type": "str", "description": "飞行朝向控制模式", "default": "auto", "required": False, "enum": ["auto", "fixed", "toward_target", "free"], }, "fixed_heading": { "type": "float", "description": "固定航向角（heading_mode=fixed 时有效）", "default": 0.0, "required": False, "unit": "度", "range": [0.0, 360.0], }, "acceptance_radius": { "type": "float", "description": "到达判定半径，进入该范围视为到达目标", "default": 2.0, "required": False, "unit": "米", "range": [0.1, 100.0], }, "avoid_obstacles": { "type": "bool", "description": "移动过程中是否启用障碍物规避", "default": True, "required": False, }, "path_type": { "type": "str", "description": "路径规划类型", "default": "straight_line", "required": False, "enum": ["straight_line", "optimal", "terrain_hugging", "stealth"], }, "max_acceleration": { "type": "float", "description": "最大加速度", "default": 3.0, "required": False, "unit": "m/s²", "range": [0.1, 20.0], }, }, ActionType.MOTION_ROTATE: { "target_yaw": { "type": "float", "description": "目标偏航角（相对北方，顺时针为正）", "default": None, "required": True, "unit": "度", "range": [0.0, 360.0], }, "rotation_speed": { "type": "float", "description": "旋转角速度", "default": 30.0, "required": False, "unit": "度/秒", "range": [1.0, 360.0], }, "rotation_direction": { "type": "str", "description": "旋转方向", "default": "auto", "required": False, "enum": ["clockwise", "counter_clockwise", "auto"], }, "relative_rotation": { "type": "bool", "description": "是否为相对旋转（True=相对当前朝向，False=绝对角度）", "default": False, "required": False, }, "maintain_position": { "type": "bool", "description": "旋转过程中是否保持当前位置不变", "default": True, "required": False, }, "gimbal_follow": { "type": "bool", "description": "旋转时云台是否跟随机体朝向", "default": False, "required": False, }, }, ActionType.MOTION_HOVER: { "duration": { "type": "float", "description": "悬停时长，0 表示持续悬停直到收到下一指令", "default": 0.0, "required": False, "unit": "秒", "range": [0.0, 86400.0], }, "position_hold_accuracy": { "type": "float", "description": "位置保持精度（允许的最大漂移半径）", "default": 1.0, "required": False, "unit": "米", "range": [0.1, 20.0], }, "altitude_hold_accuracy": { "type": "float", "description": "高度保持精度", "default": 0.5, "required": False, "unit": "米", "range": [0.1, 10.0], }, "heading_lock": { "type": "bool", "description": "悬停时是否锁定朝向", "default": True, "required": False, }, "locked_heading": { "type": "float", "description": "锁定的朝向角（heading_lock=True 时有效，None=保持当前朝向）", "default": None, "required": False, "unit": "度", "range": [0.0, 360.0], }, "wind_compensation": { "type": "bool", "description": "是否启用风力补偿以维持位置", "default": True, "required": False, }, "auto_exit_on_battery": { "type": "float", "description": "电量低于该阈值时自动退出悬停并返航", "default": 0.2, "required": False, "range": [0.05, 0.5], }, }, ActionType.MOTION_LAND: { "landing_point": { "type": "dict", "description": "降落目标坐标 {lat, lon}，None 表示原地降落", "default": None, "required": False, }, "descent_speed": { "type": "float", "description": "下降速度", "default": 1.5, "required": False, "unit": "m/s", "range": [0.1, 5.0], }, "final_approach_speed": { "type": "float", "description": "最终进近阶段（距地 2 米内）速度", "default": 0.5, "required": False, "unit": "m/s", "range": [0.1, 2.0], }, "landing_mode": { "type": "str", "description": "降落模式", "default": "precision", "required": False, "enum": ["precision", "normal", "emergency", "auto_detect_surface"], }, "verify_landing_zone": { "type": "bool", "description": "降落前是否扫描确认降落区安全", "default": True, "required": False, }, "disarm_after_landing": { "type": "bool", "description": "降落完成后是否自动解除电机锁定", "default": True, "required": False, }, "abort_altitude": { "type": "float", "description": "若降落区异常，在此高度以上可中止降落并复飞", "default": 5.0, "required": False, "unit": "米", "range": [1.0, 30.0], }, "notify_on_land": { "type": "bool", "description": "降落完成后是否通知地面站", "default": True, "required": False, }, }, ActionType.MOTION_TAKEOFF: { "target_altitude": { "type": "float", "description": "起飞目标高度（相对起飞点）", "default": 50.0, "required": True, "unit": "米", "range": [1.0, 5000.0], }, "ascent_speed": { "type": "float", "description": "爬升速度", "default": 3.0, "required": False, "unit": "m/s", "range": [0.5, 10.0], }, "heading_after_takeoff": { "type": "float", "description": "起飞后的初始朝向角，None 表示保持当前朝向", "default": None, "required": False, "unit": "度", "range": [0.0, 360.0], }, "pre_takeoff_check": { "type": "bool", "description": "起飞前是否执行自检", "default": True, "required": False, }, "arm_motors": { "type": "bool", "description": "起飞前是否自动解锁电机", "default": True, "required": False, }, "takeoff_mode": { "type": "str", "description": "起飞模式", "default": "normal", "required": False, "enum": ["normal", "vertical_only", "rolling", "catapult"], }, "hover_after_takeoff": { "type": "bool", "description": "到达目标高度后是否先悬停等待下一指令", "default": True, "required": False, }, "notify_on_airborne": { "type": "bool", "description": "离地后是否立即通知地面站", "default": True, "required": False, }, }, } # ══════════════════════════════════════════════ # 工具函数 # ══════════════════════════════════════════════ def get_action_params(action_type) -> dict: """获取指定 ActionType 的参数定义""" return ACTION_PARAMS.get(action_type if isinstance(action_type, ActionType) else ActionType(action_type), {}) def get_required_params(action_type: ActionType) -> dict: """获取指定 ActionType 的必填参数""" return { k: v for k, v in ACTION_PARAMS.get(action_type, {}).items() if v.get("required", False) } def get_default_params(action_type: ActionType) -> dict: """获取指定 ActionType 的默认参数值字典""" return { k: v["default"] for k, v in ACTION_PARAMS.get(action_type, {}).items() if v["default"] is not None } def validate_action_params(action_type: ActionType, params: dict) -> list[str]: """ 校验传入参数是否满足 ActionType 的参数约束。 返回错误信息列表，空列表表示校验通过。 """ errors = [] definition = ACTION_PARAMS.get(action_type, {}) # 检查必填参数 for key, meta in definition.items(): if meta.get("required") and params.get(key) is None: errors.append(f"缺少必填参数: {key} ({meta['description']})") # 检查枚举值 for key, value in params.items(): if key in definition: meta = definition[key] if "enum" in meta and value not in meta["enum"]: errors.append( f"参数 {key}={value!r} 不在允许值列表中: {meta['enum']}" ) if "range" in meta and value is not None: lo, hi = meta["range"] if not (lo <= value <= hi): errors.append( f"参数 {key}={value} 超出范围 [{lo}, {hi}]" ) return errors # ══════════════════════════════════════════════ # 使用示例 # ══════════════════════════════════════════════ if __name__ == "__main__": import json # 打印所有 ActionType 参数定义 output = { at.value: params for at, params in ACTION_PARAMS.items() } print(json.dumps(output, ensure_ascii=False, indent=2)) # 获取必填参数 print("\n--- TRACK_TARGET 必填参数 ---") print(get_required_params(ActionType.TRACK_TARGET)) # 获取默认参数 print("\n--- MOTION_TAKEOFF 默认参数 ---") print(get_default_params(ActionType.MOTION_TAKEOFF)) # 参数校验示例 print("\n--- 参数校验示例 ---") errors = validate_action_params( ActionType.MOTION_MOVE, {"target_position": {"lat": 39.9, "lon": 116.4, "alt": 100}, "speed": 999} ) print("校验错误:", errors)