Cerulean Sounder API

Communications Interface: The Cerulean Sounder S500 features 3 hardware connection options. Ethernet (100Mb/sec), USB (12Mb/sec), and 3.3V Serial (115kbaud). After each power up, all interfaces are polled. The first one to send a valid packet is selected as the host, and the remaining interfaces are disabled.

API Compatibility: S500 communication uses a binary packet format compatible with the Blue Robotics Ping-Protocol. It supports most of the Blue Robotics Ping1 packet types, and maintains compatibility with the Blue Robotics Ping Viewer.

Documentation: The generic packet format is documented below, as are the specific payloads. These packet types are recommended for new applications targeting the S500 sounder.

Apology: The terms "altitude," "distance," and "depth" are used somewhat interchangeably here. They all mean the sensed distance from the device to some object, which is usually the bottom.

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

msg length = payload_length - 2 (could be 0)

ascii_text

3

char[]

msg

any ascii text string

msg length = payload length

general_request

6

u16

id

request client to respond with packet id type

-

Request Info Response Packets

These are the responses that the device will send to the host in response to a general_request packet (id = 6, see above). Alternatively, host may send any one of these packet ids with no payload and device will respond with same id and the payload indicated here.

Name ID Data Type Name Description

fw_version

1200

u8

device_type

1 = echosounder

-

-

u8

device_model

108 = S500

-

-

u16

version_major

firmware version major.minor

-

-

u16

version_minor

firmware version major.minor

speed_of_sound

1203

u32

sos_mm_per_sec

current speed of sound setting in mm/sec

range

1204

u32

start_mn

normally 0

-

-

u32

length_mm

start_mm + length_mm is max range

ping_rate_msec

1206

u16

msec_per_ping

minimum time between successive pings - actual time between pings can be longer depending on range

gain_index

1207

u32

gain_index

current gain index setting

altitude

1211

u32

altitude_mm

calculated distance from device to bottom or other target (average of last 20 pings)

-

-

u8

confidence

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

processor_mdegC

113

u32

mdegC

device CPU temperature degrees C * 1000

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

length of the return

end_mm = start_mm + length_mm

i16

gain_index

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

MAX_GAIN_INDEX is 14 for S500

i16

msec_per_ping

set to -1 to start a single ping. Otherwise sets minimum time from start of one ping to start of the next

100msec - 1000msec is valid range for S500. Ping rate may not be achieved depending on range.

u16

ping_duration_usec

normally should be 0 for auto duration

1000 usec is max limit

u16

report_id

id of desired response packet to be sent after each ping

see Ping Response Packets below

u16

num_results_requested

applies only to report_id profile2_t

set to 0 to report profile results in native resolution

u8

chirp

set to 1 for chirp, 0 for monotone ping

u8

decimation

set to 0 for auto range resolution

Other valid values and corresponding range resolution are 4 (3mm), 12 (9mm), 32 (24mm).

Ping Response Packets

These packet types can be returned after each ping by specifying their packet id in the set_ping_params above.

altitude id reports a simple distance measurement.

profile2_t and profile6_t report a measure of signal strength at all depths within the ping range. This could be used to present a "waterfall" type display similar to a commercial marine depth sounder or fish finder. The Blue Robotics Ping Viewer is an example of such a display.

The native number of results reported is 1024 for monotone pings. For chirp pings, the range resolution is set by the "decimation" field in the set_ping_params command. If decimation is set to 0, the device will vary decimation depending on range. The smallest decimation will be used that does not exceed 6000 reported data elements.

For profile2_t, the number of results reported (and therefore the distance resolution of the profile data) can be specified in the "num_results_requested" field of the set_ping_params command above. This is done by interpolating the native results as described above, and reporting a fixed number of results.

Keep in mind the bandwidth of the communication channel in use when considering which profile report to use.. For example, profile6_t can generate a lot of data, and is probably best used with the ethernet interface.

Packet ID Name ID Data Type Field Name Description Notes

altitude

1211

u32

altitude_mm

calculated distance from device to bottom or other target (average of last 20 pings)

Same as Request Info Response above

u8

confidence

measure of confidence of altitude measure 0 (no idea) to 100 (quite sure)
Packet ID Name ID Data Type Field Name Description Notes

profile2_t

1303

u32

ping_number

sequentially assigned from 1 at power up

in auto-range mode, some numbers will be skipped due to test pings not reported

u32

start_mm

u32

length_mm

u32

timestamp_msec

u32

gain_index

float

analog_gain

u32

this_ping_distance_mm

u32

smoothed_distance_mm

u8

this_ping_confidence

u8

smoothed_confidence

u16

ping_duration_usec

u16

num_results

u8

results[num_results]
Packet ID Name Packet ID Data Type Field Name Description Notes

profile6_t

1308

u32

ping_number

sequentially assigned from 1 at power up

in auto-range mode, some numbers will be skipped due to test pings not reported

-

-

u32

start_mm

-

-

-

-

u32

length_mm

-

-

-

-

u32

start_ping_hz

-

start and end hz will be the same for non-chirp pings

-

-

u32

end_ping_hz

-

-

-

-

u32

adc_sample_hz

-

-

-

-

u32

timestamp_msec

-

-

-

-

u32

spare2

-

-

-

-

float

ping_duration_sec

-

-

-

-

float

analog_gain

-

-

-

-

float

max_pwr_db

highest power value in the profile in dB

power values are relative, not calibrated to specific SPL.

-

-

float

min_pwr_db

smallest power in returned profile in dB

smallest value here is 90 dB less than max_pwr_db

-

-

float

this_ping_depth_m

depth measurement for this ping

-

-

-

float

smooth_depth_m

smoothed calculated depth

result of smoothing algorithm based on previous 20 pings

-

-

float

fspare2

-

-

-

-

u8

this_ping _confidence

confidence of the depth measurement for this ping

0 (no idea) to 100 (pretty sure)

-

-

u8

gain_index

-

-

-

-

u8

decimation

-

-

-

-

u8

smoothed depth confidence

confidence of the smoothed depth measure

0 (no idea) to 100 (pretty sure)

-

-

u16

num_results

-

will be 1024 for monotone pings, and variable up to 6000 for chirp pings

-

-

u16

pwr_db[num_results]

power results scaled from min_pwr (0) to max_pwr (0xffff)

pwr_db = pwr_db[i] * (max_pwr_db - min_pwr_db) / 0xffff;