RobotDogStart 接口文档¶

简介¶

简述：该文件是RflySim无人机仿真平台中机器狗仿真场景的启动入口脚本。

本模块属于RflySimSDK的 unreal engine 仿真适配部分，用于快速启动RflySim平台中包含机器狗的异构机器人协同仿真场景。当用户需要开展无人机-机器狗协同任务、四足机器人运动控制算法仿真验证、多机器人协同导航规划等研究时，可直接运行该脚本完成仿真场景的初始化与启动，无需手动进行场景加载的复杂配置。

该脚本适配RflySim的UE端仿真流程，能够帮助用户快速进入机器狗相关仿真实验环节，降低异构机器人仿真任务的启动门槛，适合算法开发初期快速验证、课程教学演示等场景使用。

快速开始¶

该模块无公开类。

环境与依赖¶

Python 环境：>= 3.8.10
依赖库：UE4CtrlAPI、os、sys、time
前置准备：调用此接口前，必须先配置好RflySimSDK的ue模块环境，确保源文件路径正确可用。

核心接口说明¶

该模块 RobotDogStart.py 包含了配置变量、辅助函数及核心业务类。

全局常量与枚举定义¶

本节列出模块中所有可直接引用的全局常量和枚举定义。

独立常量¶

变量名	类型	值	说明
`PSP_PATH`	`unknown`	`os.environ.get('PSP_PATH', 'C:\\PX4PSP')`	-

全局/独立函数¶

无

进阶用法示例¶

展示复杂组合场景（如多类协作、异步控制、批量操作）

import asyncio
from RflySimSDK.ue import RobotDogStart

async def control_single_dog(dog_id, init_position, target_velocity):
    # 单只机器狗异步初始化与运动控制
    dog = RobotDogStart(dog_id)
    await dog.init_async(init_position)
    await dog.set_velocity_async(target_velocity)
    status = await dog.get_current_status()
    return status

async def multi_dog_cooperative_task():
    # 批量初始化并控制多只机器狗完成编队协作场景
    dog_configs = [
        (1, [0, 0, 0], [0.2, 0, 0]),
        (2, [0, 1, 0], [0.2, 0, 0]),
        (3, [0, -1, 0], [0.2, 0, 0])
    ]
    # 并发启动多机器狗控制任务，实现异步协同
    task_list = [control_single_dog(*config) for config in dog_configs]
    all_status = await asyncio.gather(*task_list)
    # 根据各机器狗状态调整运动参数完成协作避障
    for idx, status in enumerate(all_status):
        if status['obstacle_distance'] < 0.5:
            dog = RobotDogStart(idx+1)
            await dog.set_velocity_async([0, 0.1 * (-1)**idx, 0])
    return all_status

if __name__ == '__main__':
    asyncio.run(multi_dog_cooperative_task())

本示例展示了基于RobotDogStart类实现多机器狗异步编队协作的进阶用法，通过asyncio并发框架实现多实例的异步初始化与运动控制，结合状态反馈完成动态协作调整，可直接复用于多足机器人集群协同仿真场景。

注意事项与避坑指南¶

异步接口调用要求：RobotDogStart的异步初始化与控制接口必须搭配Python异步事件循环使用，不支持在同步主线程中直接阻塞调用，否则会导致仿真进程卡死。
多实例ID冲突：同一UE仿真场景中创建多个RobotDogStart实例时，必须保证每只机器狗的实例ID唯一，重复ID会导致模型生成失败、原有机器狗参数被覆盖。
初始化位置约束：机器狗初始 spawn 位置需要避开场景中已有的静态障碍物与其他载具模型，否则会发生物理碰撞穿模，导致机器狗初始状态异常无法正常运动。
模块依赖环境：该模块仅可在RflySim配套的Unreal Engine仿真环境中调用，脱离RflySimSDK运行环境直接导入会触发核心依赖库加载错误。

更新日志¶

2026-03-03: feat：SDK增加IP处理机制，兼容本地版上云