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.

NameIDData TypeNameDescription

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

Last updated