TCP Protocol

The simulator exposes a newline-delimited JSON TCP protocol. Each request is one JSON object followed by \n. Protocol version 2 adds request IDs, typed response envelopes, status fields, and batch support.

Wire format

{
  "type": "command",
  "protocol_version": 2,
  "request_id": "run-001",
  "action": "get_state"
}

Envelopes

Field	Applies to	Description
type	request/response	command, sim_control, batch, state, response, or error.
protocol_version	request/response	Current value is 2.
request_id	request/response	Optional client-provided correlation ID. Responses preserve it when present.
action	request/response	Command name such as get_state, set_force, or export_dataset.
data	request/response	Action payload or action result.
status / success	response	ok / true or error / false.
sim_time	response	Simulation time included in state and protocol context responses.

Action summary

Action	Type	Purpose
get_state	command	Return AUV state and embedded sensor data.
get_sensors	command	Return active sensor payloads.
step	command	Apply a force or thruster command and return updated state.
set_force	command	Compatibility alias for world-frame force control.
set_force_world, set_force_body	command	Apply a three-axis force in world frame or AUV body frame.
set_body_wrench, set_body_velocity	command	Apply six-degree body-frame control inputs.
set_thrust, set_thrusters	command	Set named thruster values from a profile-level control dictionary.
reset, pause, resume, set_time_scale	sim_control	Control global simulation state.
set_scenario, generate_map, get_map_info, get_terrain_grid	command	Load scenarios and query map data.
spawn_obstacle, remove_obstacle	command	Manage static obstacles.
spawn_agent, move_agent, remove_agent, clear_agents, get_agents	command	Manage dynamic AUV-like agents.
set_nav_path, set_waypoint, set_pred_trajectory, set_waypoints, clear_nav	command	Drive simulator-side navigation overlays.
export_dataset, save_snapshot_json	command	Export run artifacts or a snapshot JSON.

Command details

get_state()

Return the current AUV state. The response type is state, not a generic response, and the payload includes position, velocity, depth, speed, heading_deg, sim_time, and sensors.

Returns:

{type: "state", status: "ok", data: State}

get_sensors()

Return the active sensor dictionary. This is useful when the controller needs fresh sensor payloads without manually unpacking the full state object.

Returns:

state response whose data contains sensors.

step(data)

Apply data.force or data.thrusters, advance the control loop, and return state. This is the preferred online-training request because one round trip provides action execution and observation.

Parameters:

data – {"force": [fx, fy, fz]} or {"thrusters": {...}}.

Returns:

updated state response with sensor payloads.

set_force(data)

Compatibility alias for world-frame force control, where x is lateral/right, y is forward, and z is up.

Parameters:

data – {"force": [fx, fy, fz]}

Returns:

generic response envelope.

set_force_world(data)

Apply {"force": [fx, fy, fz]} in OceanSim world/user coordinates.

set_force_body(data)

Apply {"force": [fx, fy, fz]} in the AUV body frame.

set_body_wrench(data)

Apply {"wrench": [fx, fy, fz, tx, ty, tz]} in the AUV body frame.

set_body_velocity(data)

Apply {"velocity": [u, v, w, p, q, r]} as body-frame linear and angular velocity components.

set_scenario(data)

Load a named scenario and regenerate the map.

Parameters:

data – {"scenario": "NarrowMap", "seed": 0}

Returns:

map metadata returned by the map manager.

get_terrain_grid(data)

Return a 2D occupancy grid for classical planners. The grid uses 1=blocked and 0=free; class_grid may distinguish terrain, static obstacles, and dynamic agents.

Parameters:

data – cell_size, auv_y, include_static_obstacles, include_dynamic_agents, and inflation_radius.

export_dataset(data)

Export point-cloud run artifacts through the simulator. The Python wrapper waits up to 60 seconds because export can be slower than ordinary control commands.

Parameters:

data – {"export_dir": optional, "render_image": bool, "pack_dataset": bool}

Returns:

paths and export status.

Batch requests

Batch requests wrap multiple command or sim-control objects into one TCP request. The simulator returns a response containing count and a responses array. The current batch limit is 64 requests.

{
  "type": "batch",
  "protocol_version": 2,
  "request_id": "batch-001",
  "requests": [
    {"type": "command", "action": "get_state"},
    {"type": "command", "action": "set_force", "data": {"force": [0, 100, 0]}}
  ]
}

Errors

Error code	Meaning
unknown_type	The request type is not supported.
unknown_action	The request action is not recognized for its type.
invalid_message	The request is malformed or the action payload failed validation.
invalid_action_shape	A vector action has the wrong length or contains non-numeric values.
unknown_agent	The requested runtime agent ID is not registered.
unsupported_control_scheme	The agent exists but does not support the requested control path.
spawn_failed / blocked_pose	Runtime placement failed or the target pose is blocked.
batch_limit	The batch request contains too many child requests.