Network Interface Specification

To create a custom API, you need to implement a client for the simulator's network interface. The interface is based on ZeroMQ, a high-performance asynchronous messaging library.

Conventions

All numeric fields in binary messages are encoded in little-endian byte order, unless explicitly stated otherwise.

Images

The image stream uses the PUB/SUB pattern over TCP on port :5555. Each message is a multipart message with three parts:

Field	Type
AUV ID	uint8
Front camera (JPEG-encoded)	uint8[]
Bottom camera (JPEG-encoded)	uint8[]

Example Python Client

import cv2 as cv
import numpy as np
import zmq

AUV_ID = 0

ctx = zmq.Context()

socket = ctx.socket(zmq.SUB)
socket.connect("tcp://localhost:5555")
socket.subscribe(bytes([AUV_ID]))  # filter for AUV with ID=0

_auv_id, msg_front, msg_bottom = socket.recv_multipart(0)

data_front = np.frombuffer(msg_front, np.uint8)
data_bottom = np.frombuffer(msg_bottom, np.uint8)

img_front = cv.imdecode(data_front, cv.IMREAD_COLOR)
img_bottom = cv.imdecode(data_bottom, cv.IMREAD_COLOR)

Thrusters

The thruster control channel uses the PUSH/PULL pattern over TCP on port :5556. The message structure is as follows:

Field	Type
Left thruster power	int8
Right thruster power	int8
Side thruster power	int8
Vertical thruster power	int8

Each value must be in the range [-100, 100]. Use -127 to skip a parameter (i.e., do not update it).

Example Python Client

import struct
import zmq

AUV_ID = 0

LEFT = 75
RIGHT = -50
SIDE = 0
VERTICAL = -127  # Do not update

ctx = zmq.Context()

socket = ctx.socket(zmq.PUSH)
socket.connect("tcp://localhost:5556")

data = struct.pack("Bbbbb", AUV_ID, LEFT, RIGHT, SIDE, VERTICAL)
socket.send(data)

Telemetry

Telemetry is published using the PUB/SUB pattern over TCP on port :5557. Each message is multipart and contains two parts:

Field	Type
AUV ID	uint8
Telemetry	See below

The telemetry payload is encoded as follows:

Field	Type
X	float32
Y	float32
Z	float32
Yaw	float32
Pitch	float32
Roll	float32

Example Python Client

import struct
import zmq

AUV_ID = 0

ctx = zmq.Context()

socket = ctx.socket(zmq.SUB)
socket.connect("tcp://localhost:5557")
socket.subscribe(bytes([AUV_ID]))  # Filter for AUV with ID=0

_auv_id, data = socket.recv_multipart(0)
x, y, z, yaw, pitch, roll = struct.unpack("<ffffff", data)