Python SDK
awr_sandbox 是沙盒接口的单文件 Python SDK(版本 1.1.0,接口 /api/sandbox/v1)。它不依赖本仓库的 awr 包,可以单独复制使用,负责排队、工作量证明、续期、节能后的恢复与实时二进制帧的解码。
安装
支持 Python 3.9 至 3.13,依赖 httpx、websockets 与 msgpack:
pip install "httpx>=0.24" "websockets>=12" "msgpack>=1.0"
curl -O https://anet4d.agentnetwork.org.cn/sdk/awr_sandbox.py
在仓库内运行时,文件位于 tools/sdk/awr_sandbox.py,make setup 创建的 .venv 已包含上述依赖(见 快速开始)。
最小示例
from awr_sandbox import Sandbox
sb = Sandbox("https://anet4d.agentnetwork.org.cn", timeout_s=30)
with sb.create("synthcity", "t5_area_guard") as s: # 满员时自动排队;需要时自动求解工作量证明
print(s.state()["state"])
s.clock("speed", rate=5) # 受限时返回授予值
for msg in s.stream(["sandbox/session"], seconds=3):
print(msg.topic, msg.data)
离开 with 块时会话结束;结束前 SDK 导出一次配置快照,保存在 Session 对象上。
对象模型
对象 |
获取方式 |
职责 |
|---|---|---|
|
构造 |
连接一个部署;构造时读取 |
|
|
一个沙盒会话;上下文管理器 |
|
属性 |
资源集合,统一提供 |
|
属性 |
环境与外部分配器 |
|
|
无人机租约;上下文管理器,退出时释放 |
|
|
一条实时消息 |
调用一览
能力 |
调用 |
端点 |
|---|---|---|
世界、模板、概况、公开容量 |
|
SB-00 至 SB-02、SB-71 |
创建(工作量证明、排队长轮询与认领) |
|
SB-03 至 SB-06、SB-08 |
接回已有会话 |
|
SB-08 |
状态与等待就绪 |
|
SB-08 |
续期、结束 |
|
SB-10、SB-09 |
快照、恢复、模板、切换底图 |
|
SB-11 至 SB-14 |
时钟 |
|
SB-15 |
事件补拉 |
|
SB-16 |
机队 |
|
SB-28 至 SB-38 |
识别物 |
|
SB-40 至 SB-46 |
机巢 |
|
SB-47 至 SB-51 |
任务 |
|
SB-52 至 SB-56、SB-59 |
环境 |
|
SB-60 至 SB-63 |
外部分配器 |
|
SB-57、SB-58 |
机型目录 |
|
SB-21 至 SB-23 |
命令与租约 |
|
SB-35 至 SB-37 |
速度控制 |
|
WebSocket |
实时流 |
|
SB-64 |
节能驻留与恢复 |
|
SB-69、SB-70 |
内部档会话 |
|
SB-04 |
端点编号与路径的对应见 开放接口。Session.command() 在有实时连接时经 WebSocket call 发送,否则经 POST .../commands,同一调用编号幂等重试。
错误处理
所有错误统一为 AwrError(code, name, message, detail, remedy, status, retry_after_s),str(e) 的形式为 "<code> <NAME>: <message>"。会话已结束时抛出子类 SandboxGone,其 snapshot 属性为最近一次导出的配置快照。
from awr_sandbox import AwrError, Sandbox, SandboxGone
try:
s.vehicles.add("p600_mid360", nest_id="nest-a")
except AwrError as e:
print(e.code, e.name, e.detail, e.remedy) # 例如 525 NEST_INCOMPATIBLE {'why': 'slots', 'slots': 6}
限流(429,原因码 111)与服务暂不可用时,SDK 按
retry_after_s(取自retry_after_ms或Retry-After)自动重试,抖动随等待缩放。只用 REST、长时间不调用的会话会因无连接空闲而被驻留;下一次需要 sim-core 的调用收到 409 与原因码 515 时,SDK 自动恢复一次。
排队、续期与节能
排队。
create()收到 202 时进入排队,以单次最长 25 s 的长轮询等待;on_queue(kind, view)回调接收位次与预计等待。由于长轮询的单次时长为 25 s,请把timeout_s设为大于 25 s 的值(例如 30)。queue=False时满员立即失败。续期。
auto_keepalive=True时后台线程在寿命将尽时续期并换发令牌。续期不会为保持运行而发出调用,也不会唤醒驻留中的会话。节能。 没有实时连接、且在 120 s(沙盒队列非空时 60 s,见
GET /sessions/{sid}的idle_ttl_s)内没有任何会话内调用的会话会被驻留。需要会话在长时间无操作时继续推进仿真,请保持一个stream()实时连接,或以短于idle_ttl_s的间隔调用一次Session.state()。驻留后的下一次会话请求会自动恢复(满员时可能排队)。主体提示。
principal_hint保存在~/.config/awr_sandbox/principal(0600),只用于幂等与配额聚合,不是凭据。
手动控制示例
with sb.create("synthcity", "t6_manual") as s:
v = s.vehicles.add("p600_mid360", home_enu_m=[0.0, 0.0, None], label="manual")
vid = v["id"]
s.command(vid, "arm")
s.command(vid, "takeoff", alt_m=30.0)
with s.acquire(vid, priority="normal"):
t_end = time.monotonic() + 5.0
while time.monotonic() < t_end:
s.velocity(vid, 3.0, 0.0, 0.0) # 向东 3 m/s(World ENU)
time.sleep(0.04) # 25 Hz
s.velocity_stop(vid)
s.command(vid, "land")
速度控制受服务端软围栏保护:朝识别物敏感范围方向的速度分量被钳为 0,并返回警告 KEEPOUT_CLAMPED(见 沙盒)。
示例程序
仓库的 tools/sdk/examples/ 包含以下示例,均只使用公开接口;地址取第一个命令行参数或环境变量 AWR_SANDBOX_URL,缺省为 http://127.0.0.1:8002:
示例 |
内容 |
|---|---|
|
创建沙盒、读会话状态、申请倍速、订阅会话状态 5 s、导出快照、结束 |
|
添加一架 P600、起飞、申请租约后以速度指令向东飞 5 s、停止、释放租约、降落 |
|
逐机型、逐传感器发现全部数据产品,并经 REST 与 WebSocket 各取一个样本 |
|
放置一个人,派一架机定点盯看,等待 |
|
给出区域与所需 GSD,打印航高、条带、架数与完工时间曲线 |
|
读取分配快照,按"最近的空闲机"贪心分配工作项,提交外部计划 |
|
区域值守与接力的端到端验收脚本 |
python tools/sdk/examples/01_quickstart.py https://anet4d.agentnetwork.org.cn