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