OceanSim Client

The oceansim_client.client module provides the low-level TCP transport used by higher-level APIs. It manages sockets, request IDs, background receiving, pending responses, timeout handling, and protocol errors.

Classes

class OceanSimClient(host='localhost', port=9876, timeout=5.0)

TCP client for OceanSim’s protocol.

Parameters:

host (str) – simulator hostname.
port (int) – simulator TCP port.
timeout (float) – default response timeout in seconds.

PROTOCOL_VERSION: Current protocol version. The value is 2.

is_connected: True when the TCP socket is connected.

launch_godot(exe_path=None): Start a packaged simulator executable before connecting.

connect(retry=True, max_retries=10, retry_interval=1.0)

Open the TCP socket and start the background receive loop.

Returns:: True on success, False on connection failure.

disconnect(): Close the socket and terminate a launched Godot process if present.

send(msg)

Send a raw JSON message with a trailing newline.

Parameters:: msg (dict) – protocol request object.
Returns:: True if the message was sent.

send_command(action, data=None, timeout=None)

Build a command request, inject protocol_version and request_id, send it, and wait for a matching state, response, or error envelope.

Raises:

OceanSimConnectionError – when the simulator is disconnected.
OceanSimTimeoutError – when no response arrives before timeout.
OceanSimProtocolError – when the simulator returns an error envelope.

send_sim_control(action, timeout=None, **kwargs): Send a sim_control request such as reset, pause, resume, or set_time_scale.

send_batch(requests, timeout=None)

Normalize each child request with protocol version and request ID, then send a top-level batch request.

Parameters:: requests (list) – command or sim-control dictionaries.
Returns:: response envelope whose data contains count and responses.

request_state(): Convenience wrapper for send_command("get_state"). Returns the response data dictionary.

get_latest_state(): Return the latest cached state without sending a new request.

Exceptions

exception OceanSimError: Base SDK failure.

exception OceanSimConnectionError: Raised when a command cannot be sent because the simulator is absent or disconnected.

exception OceanSimTimeoutError: Raised when the simulator does not answer before the selected timeout.

exception OceanSimProtocolError: Raised when the simulator returns an error envelope, empty response, or mismatched request ID.

Example

from oceansim_client import OceanSimClient

with OceanSimClient(timeout=5.0) as client:
    state = client.request_state()
    batch = client.send_batch([
        {"type": "command", "action": "get_sensors"},
        {"type": "command", "action": "set_force", "data": {"force": [0, 80, 0]}},
    ])