Python SDK
awr_sandbox is the single-file Python SDK of the sandbox interface (version 1.1.0, interface /api/sandbox/v1). It does not depend on this
repository's awr package and can be copied and used on its own; it handles queueing, proof of work, renewal, resume after power saving and
decoding of realtime binary frames.
Installation
Python 3.9 to 3.13 are supported; the dependencies are httpx, websockets and msgpack:
pip install "httpx>=0.24" "websockets>=12" "msgpack>=1.0"
curl -O https://anet4d.agentnetwork.org.cn/sdk/awr_sandbox.py
Inside the repository the file is tools/sdk/awr_sandbox.py, and the .venv created by make setup already contains the dependencies (see
Quick start).
Minimal example
from awr_sandbox import Sandbox
sb = Sandbox("https://anet4d.agentnetwork.org.cn", timeout_s=30)
with sb.create("synthcity", "t5_area_guard") as s: # queues when full; solves the proof of work when required
print(s.state()["state"])
s.clock("speed", rate=5) # returns the granted rate when limited
for msg in s.stream(["sandbox/session"], seconds=3):
print(msg.topic, msg.data)
The session ends when the with block is left; before that the SDK exports a configuration snapshot and keeps it on the Session object.
Object model
Object |
Obtained from |
Role |
|---|---|---|
|
Constructor |
Connects to one deployment; reads |
|
|
One sandbox session; a context manager |
|
Attributes |
Resource collections with |
|
Attributes |
Environment and external allocator |
|
|
A drone lease; a context manager that releases on exit |
|
Items of |
One realtime message |
Call reference
Capability |
Call |
Endpoints |
|---|---|---|
Worlds, templates, overview, public capacity |
|
SB-00 to SB-02, SB-71 |
Create (proof of work, queue long polling and claim) |
|
SB-03 to SB-06, SB-08 |
Reattach an existing session |
|
SB-08 |
State and waiting for readiness |
|
SB-08 |
Renew, end |
|
SB-10, SB-09 |
Snapshot, restore, template, world switch |
|
SB-11 to SB-14 |
Clock |
|
SB-15 |
Fetch missed events |
|
SB-16 |
Fleet |
|
SB-28 to SB-38 |
Targets |
|
SB-40 to SB-46 |
Nests |
|
SB-47 to SB-51 |
Tasks |
|
SB-52 to SB-56, SB-59 |
Environment |
|
SB-60 to SB-63 |
External allocator |
|
SB-57, SB-58 |
Airframe catalog |
|
SB-21 to SB-23 |
Commands and leases |
|
SB-35 to SB-37 |
Velocity control |
|
WebSocket |
Realtime stream |
|
SB-64 |
Power-save parking and resume |
|
SB-69, SB-70 |
Internal-tier session |
|
SB-04 |
Endpoint numbers map to paths in Open interface. Session.command() uses the WebSocket call when a realtime connection is open and
POST .../commands otherwise, retrying idempotently with the same call ID.
Error handling
All errors are AwrError(code, name, message, detail, remedy, status, retry_after_s), and str(e) reads "<code> <NAME>: <message>".
When the session has ended, the subclass SandboxGone is raised, with the last exported configuration snapshot in its snapshot attribute.
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) # for example 525 NEST_INCOMPATIBLE {'why': 'slots', 'slots': 6}
On rate limiting (429, reason code 111) and temporary unavailability the SDK retries automatically after
retry_after_s(fromretry_after_msorRetry-After), with jitter scaled to the wait.A REST-only session that stays idle for long is parked for having no connection; when the next call that needs sim-core receives 409 with reason code 515, the SDK resumes the session once automatically.
Queueing, renewal and power saving
Queueing. When
create()receives 202 it queues and waits with long polls of up to 25 s each; the callbackon_queue(kind, view)receives the position and estimated wait. Because each long poll may take 25 s, settimeout_sabove 25 s (for example 30). Withqueue=False, creation fails immediately when full.Renewal. With
auto_keepalive=Truea background thread renews shortly before the lifetime ends and swaps in the reissued token. Renewal does not issue calls to keep the session running and does not wake a parked session.Power saving. A session without a realtime connection and without any session call for 120 s (60 s when the sandbox queue is not empty; see
idle_ttl_sinGET /sessions/{sid}) is parked. To keep the simulation advancing during long inactive periods, keep onestream()connection open, or callSession.state()at an interval shorter thanidle_ttl_s. The next session request after parking resumes automatically (and may queue when full).Principal hint.
principal_hintis stored in~/.config/awr_sandbox/principal(0600); it is used only for idempotency and quota aggregation and is not a credential.
Manual control example
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 east (World ENU)
time.sleep(0.04) # 25 Hz
s.velocity_stop(vid)
s.command(vid, "land")
Velocity control is protected by the server-side soft fence: the velocity component towards a target's sensitivity range is clamped to 0 and
the warning KEEPOUT_CLAMPED is returned (see Sandbox).
Example programs
The repository's tools/sdk/examples/ contains the following examples, all using only the public interface; the address is the first
command-line argument or the environment variable AWR_SANDBOX_URL, defaulting to http://127.0.0.1:8002:
Example |
Content |
|---|---|
|
Create a sandbox, read the session state, request a rate, subscribe to the session state for 5 s, export a snapshot, end |
|
Add a P600, take off, acquire a lease and fly east for 5 s with velocity commands, stop, release, land |
|
Discover every data product per airframe and sensor, and fetch one sample over REST and one over WebSocket |
|
Place a person, send a drone to watch it, and wait for the |
|
Given an area and the required GSD, print altitude, strips, drone count and the completion time curve |
|
Read the allocation snapshot, assign work items greedily to the nearest idle drone, submit an external plan |
|
End-to-end acceptance script for area guard and relay |
python tools/sdk/examples/01_quickstart.py https://anet4d.agentnetwork.org.cn