Links

Appendix A: Programming API

API Compatibility: Omniscan communication uses the same binary packet format (described below) as the Cerulean S500 Sounder, the Insight 240 Forward Looking Sonar and the Blue Robotics Ping and Ping360 sonars.

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

These are the Omniscan-specific packet payload formats. Note on os_ping_params: send once to start or stop pinging.

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)
os_ping_params
2197
u32
start_mm
start of ping range, set to 0
u32
length_mm
length of the returned profile. so end of range = start_mm + length_mm.
u32
msec_per_ping
normally set to 0 for best ping rate. set value to limit ping rate
float
reserved
set to 0
float
reserved
set to 0
float
pulse_len_percent
% of total ping time for current range. 0.002 typical
float
filter_duration_percent
0.0015 typical
i16
gain_index
set to -1 for auto gain, otherwise 0-7 sets gain
u16
number of signal data points in resulting profile
200-1200. 600 typical
u8
enable
1 or 0 to enable or disable pinging
u8
reserved
set to 0

Ping Response Packets

For os_mono_profile, note that the amplitude of the results are in dB. This is just to keep high dynamic range in the u16 sized data elements. Normally these are converted back to linear power or signal levels.
Name
ID
Data Type
Name
Description
os_mono_profile
2198
u32
ping_number
sequentially assigned from 0 at power up
u32
start_mm
u32
length_mm
u32
timestamp_ms
msec since power up at time of ping
u32
ping_hz
450000
u16
gain_index
0-7
u16
num_results
length of pwr_results array
u16
sos_dmps
speed of sound, decimeters/sec
u8
channel_number
0
u8
reserved
0
float
pulse_duration_sec
float
analog_gain
float
max_pwr_db
float
min_pwr_db
float
transducer_heading_deg
float
vehicle_heading_deg
u16
pwr_results[]
power results scaled from min_pwr_db to max_pwr_db