Omniscan3d messages

general

10 JSON_WRAPPER

Type	Name	Description	Units
char[]	string	Length is derived from payload_length in the header.

control

3024 os3d_set_ping_params

Payload Definition

Type	Name	Description	Units
float	start_m	start range in meters at which echo data is recorded. Ignored in auto range mode. Will be forced to 5% of end range as a minimum.	m
float	end_m	end range in meters over which echo data is recorded. Set to 0 for Omniscan 3D to automatically track the bottom and adjust range dynamically.	m
float	sos_mps	speed of sound, meters per second	m/s
i16	gain_index	Set to -1 for auto gain (recommended). Valid manual gain ranges are from 0 to 10
i16	msec_per_ping	pings per second = 1000 / msec_per_ping. So 100 msec_per_ping means 10 pings per second. Actual ping rate can be limited by range and speed of sound, so the value specified defines an upper limit on ping rate.	ms/ping
u16	reserved	set to 0
u16	diagnostic injected signal	must be set to 0
bool	ping_enable	true to start/continue pinging, false to stop
bool	enable_channel_data	Used by SonarView, but not necessary. If enabled log files will be much larger.
bool	reserved_for_raw_data	Must be set to false
bool	reserved	set to false
bool	enable_atof_data	enable angle + time of flight information for each detected point should be true
i32	target_ping_hz	set to 450000. Used internally for production testing only.
u16	n_range_steps	sets range resolution in number of range steps. Must be between 200 and 1000 (inclusive), 1000 is recommended.
u16	reserved	set to 0
float	pulse_len_steps	Pulse length in number of range steps. Recommended value is 1.5

get

504 attitude_report

Type	Name	Description	Units
vec3	up_vec	world up vector (x,y,z) in the device coordinate system (x forward, y port, z up).
vec3	reserved	reserved for future magnetic field vector
u64	utc_msec	utc msec (1970 epoc). Will be 0 if not available.	ms
u32	pwr_up_msec	msec since power up	ms
u8	channel_number	assigned sequentially from 0. typically 0 for a single channel system and 0 or 1 for port/stb setup.

This data pertains to the IMU in the RX16 module. Note the 'dot' on one corner of the face of the RX16 module. The zero pitch and roll orientation is with the transducer face pointing downward with the 'dot' toward the forward/starboard corner. Roll is positive as starboard side rolls downward and port side up. Pitch is positive when the forward axis is rotated downwards.

To compute pitch and roll from the up_vec:

Pitch = asin(-up_vec.x);

Roll = atan2(up_vec.y, up_vec.z);

We may support a calibrated magnetic vector in the future, but currently a heading signal from another source is required.

3104 os3d_point_set

Type	Name	Description	Units
u32	ping_number	assigned sequentially from power on
float	sos_mps	speed of sound (meters per second) used in angle calculations
i16	num_points	number of points reported in the points field
u16	unused	0
u32	unused	0
u64	utc_msec	ime at start of ping, UTC milliseconds (1970 epoch). Will be 0 if not available.	ms
u32	pwr_up_msec	time at start of ping from power on	ms
u8	version	1. There was a previous version (0), see note below
u8	device number	must be < number of devices (so it will be 0 for a single device)
u8	unused	0
u8	reserved	0
float	pwr_threshold_high	Points with pwr higher than this are quite strong. This was the level used in all version 0 point sets. Seemed to be overly conservative.
float	pwr_threshold_med	This is a reasonable cutoff level for most applications.
float	pwr_threshold_low	This is a more liberal power level. If point_data is filtered with this threshold
u32	reserved[9]	reserved for future (9 words)
atof_t	point_data[num_points]	see above for atof_t definition

version: This is Version 1 of this packet format. Earlier there was a Version 0, which was applicable in some earlier beta units. These earlier files can be handled by SonarView and can be converted in SonarView as long as channel data was recorded.

power thresholds: The set of detected points is generously populated in the sense that some of these points are stronger than others and some may not be helpful. Three power thresholds are provided with which the points can be filtered if a more conservative selection of point detections is desired.

struct atof_point_t
{
    float angle; // radians;
    float tof;   // time of flight in seconds
    float pwr;   // power level of the beam at this point
    u8 pt_type;  // 0 = unclassified, 1 = bottom_points, 2 = water column points
    u8 reserved[3] = {0,0,0};
} PACKED_STRUCT;

pt_type: At the time of this writing, all points emitted by the device will be of type 'unclassified.' In the future, we may implement further classification within the device.

Interpreting Angle

Zero angle is perpendicular to the face of the RX16 receive module. With the 'dot' end of the RX16 facing the forward direction, and the transducer side down, positive angles are to the starboard side.

Note that the angles given in the data were computed with the speed of sound also given in the data. To adjust the angle in post processing for a different speed of sound, use the Snell's Law relation.

sin(angle1) / sos1 = sin(angle2) / sos2

3010 end_ping_info

Payload Definition

Type	Name	Description	Units
u32	reserved	deprecated, may be repurposed in future
float	range_start_m	range where sampling begins	m
float	range_end_m	range where sampling ends	m
vec3	up-vec	see description in ATTITUDE_REPORT
u32	ping_number	assigned sequentially from power on
float	water_degC	-1000 if no sensor present
float	water_bar	-1000 if no sensor present
float	heave_m	0, not yet implemented
vec3	mag_vec	reserved for future implementation
float	ping_hz_realized	acutal ping hz (may differ from requested)
i32	gain_index	gain index used for this ping
u16	pulse_usec	length of the pulse used in this ping in usec
u16	n_range_bins	number of range bins processed for this ping
u16	samples_per_range_bin	number of adc samples in each range bin
u8	device_number	must be < number of devices, so 0 for single device
u8	unused	0
u32	pwr_up_msec	msec since pwr up at start of ping
u64	utc_msec	utc msec at start of ping