Cerulean Sounder API

The Cerulean Sounder uses a binary packet format compatible with the Blue Robotics Ping-Protocol.

Packet Format

Data Type Name Description

char[2]

start_of_packet

2 byte ASCII string "BR" marks start of packet

u16

payload_length

number of bytes in payload

u16

packet_id

corresponds to ID field in packet payload definitions below

u8

reserved

set to 0

u8

reserved

set to 0

u8[]

payload

payload_length bytes - format varies with packet id per payload definitions below

u16

checksum

sum of all the bytes in the packet. Truncated to 16 bits

Packet Payload Definitions

General

Name ID Data Type Name Description Notes

nop

0

-

none

clients may ignore. Sometimes useful to keep things awake

-

ack

1

u16

id

id being acked

-

nack

2

u16

id

id being nacked

-

-

-

char[]

msg

optional ascii text message describing error

STR_LEN

ascii_text

3

char[]

msg

any ascii text string

STR_LEN

general_request

6

u16

id

request client to respond with packet id type

-

STR_LEN: Length of the string determined based on payload_length in packet header.

Request Info Packets

Name ID Data Type Name Description Notes

fw_version

1200

u8

device_type

-

REQUESTS

-

-

u8

device_model

-

REQUESTS

-

-

u16

version_major

-

REQUESTS

-

-

u16

version_minor

-

REQUESTS

speed_of_sound

1203

u32

sos_mn_per_sec

current speed of sound setting in mm/sec default is 1500 m/sec

REQUESTS

range

1204

u32

start_mn

normally 0

REQUESTS

-

-

u32

length_mm

start_mm + length_mm is max range

REQUESTS

ping_rate_msec

1206

u16

msec_per_ping

minimum time between successive pings. Can be longer depending on range

REQUESTS

gain_index

1207

u32

gain_index

current gain index setting

REQUESTS

altitude

1211

u32

altitude_mm

result of most recent calculated distance from device to bottom (or other target)

REQUESTS

-

-

u8

quality

measure of confidence of altitude measure 0 (no idea) to 100 (quite sure)

REQUESTS

processor_mdegC

113

u32

mdegC

device CPU temperature degrees C * 1000

REQUESTS

REQUESTS: Host may send packet id with no payload and device will respond with same id with payload. Alternatively, host may send a general_request packet with this packet id as payload, and device will respond with this packet id and its payload.

Commands

Name ID Data Type Name Description Notes

set_speed_of_sound

1002

u32

sos_mm_per_sec

default value is 15000000 mm/sec (1500 meters/sec)

-

set_ping_params

1015

u32

start_mm

start of ping range, normally 0

-

-

-

u32

length_mm

end of ping range

-

-

-

i16

gain_index

set to -1 for auto gain, otherwise 0-MAX_GAIN_INDEX sets gain for manual gain

-

-

-

i16

msec_per_ping

set to -1 to start a single ping. Otherwise sets minimum ping interval

-

-

-

u16

ping_duration_usec

normally should be 0 for auto duration

-

-

-

u16

report_id

-

-

-

-

u08

chirp

set to 1 for chirp, 0 for monotone ping

-

-

-

u08

decimation

set to 0 for auto range resolution

-

-

-

u08

window_type

set to 1 (Hamming window)

-

Ping Response Packets

Name ID Data Type Name Description Notes

profile6_t

1308

u32

ping_number

sequentially assigned from 0 at power up

-

-

-

u32

start_mm

-

-

-

-

u32

length_mm

-

-

-

-

u32

start_ping_hz

-

-

-

-

u32

end_ping_hz

-

-

-

-

u32

adc_sample_hz

-

-

-

-

u32

timestamp_msec

-

-

-

-

u32

spare2

-

-

-

-

float

ping_duration_sec

-

-

-

-

float

analog_gain

-

-

-

-

float

max_pwr

db value if is_db

-

-

-

float

min_pwr

ditto

-

-

-

float

step_db

-

-

-

-

float

smooth_depth_m

smoothed calculated depth

-

-

-

float

fspare2

-

-

-

-

u8

is_db

if true, results are scaled linearly in db, else linearly in pwr

-

-

-

u8

gain_index

-

-

-

-

u8

decimation

-

-

-

-

u8

reserved

-

-

-

-

u16

num_results

-

-

-

-

u16

pwr_results[]

power results scaled from min_pwr to max_pwr. num_results entries

-