Programming API

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.

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 in many applications is "the bottom."

Packet Format

Byte

Data Type

Name

Description

0 to 1

char[2]

start_of_packet

2 byte ASCII string "BR" marks start of packet

2 to 3

u16

payload_length

number of bytes in payload

4 to 5

u16

packet_id

corresponds to ID field in packet payload definitions below

6

u8

reserved

set to 0

7

u8

reserved

set to 0

8 to n

u8[]

payload

payload message. Format varies with packet id per payload definitions below

(n+1) to (n+2)

u16

checksum

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

Packet Payload Definitions

General

Name
ID
Data Type
Name
Description

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*

ascii_text

3

char[]

msg

any ascii text string*

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 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

u8

device_model

u16

version_major

u16

version_minor

speed_of_sound

1203

u32

sos_mm_per_sec

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

range

1204

u32

start_mm

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. Can be longer depending on range

gain_index

1207

u32

gain_index

current gain index setting

altitude

1211

u32

altitude_mm

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

u8

quality

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

processor_degC

1213

u32

centi_degC

device CPU temperature degrees C * 100

Commands

Name
ID
Data Type
Name
Description

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 returned profile. so end of range = start_mm + length_mm. Set to 0 for auto range.

i16

gain_index

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

i16

msec_per_ping

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

u16

pulse_len_usec

0 for auto mode. currently ignored and auto duration always used

u16

report_id

the ID of the packet type that you would like in response. Options are: distance2 (1223), profile6 (1308), or zero. Zero disables pinging.

u16

reserved

Set to 0.

u8

chirp

set to 1 for chirp, 0 for monotone ping

u8

decimation

set to 0 for auto range resolution in chirp mode.

Ping Response Packets

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

distance2 reports a simple distance measurement.

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 Cerulean SonarView app uses profile6_t to do just that.

The native number of results reported for the profile6_t is 1024 for monotone pings. For chirp pings, the range resolution is affected 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.

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 USB or Ethernet interface.

Name
ID
Data Type
Name
Description

distance2

1223

u32

this ping distance mm

most recent ping

u32

averaged distance mm

average over last 20 pings

u16

reserved

u8

this ping confidence

0 to 100

u8

confidence of averaged distance

0 to 100

u32

timestamp

msec

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

pulse_duration_sec

float

analog_gain

float

max_pwr_db

float

min_pwr_db

float

this_ping_depth_m

depth in meters as calculated from the most recent ping

float

smooth_depth_m

smoothed calculated depth

float

fspare2

0

u8

this ping depth measurement confidence

depth measurement confidence (0-100) based on most recent ping

u8

gain_index

u8

decimation

u8

smoothed depth measurement confidence (0-100)

0

u16

num_results

u16

pwr_results[]

power results scaled from min_pwr to max_pwr. num_results entries

Last updated