diff --git a/mkdocs.yml b/mkdocs.yml index 5fe63c12..7beab25c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -9,6 +9,8 @@ nav: - Message Definitions: - common: pingmessage-common.md - omniscan450: pingmessage-omniscan450.md + - surveyor240: pingmessage-surveyor240.md + - s500: pingmessage-s500.md - ping1d: pingmessage-ping1d.md - ping360: pingmessage-ping360.md site_dir: ping-protocol diff --git a/src/definitions/omniscan450.json b/src/definitions/omniscan450.json index 7633befa..7b50aaea 100644 --- a/src/definitions/omniscan450.json +++ b/src/definitions/omniscan450.json @@ -18,47 +18,84 @@ "payload": [ { "name": "start_mm", - "type": "u32" + "type": "u32", + "description": "Start of ping range, set to 0.", + "units": "mm", + "default": 0 }, { "name": "length_mm", - "type": "u32" + "type": "u32", + "description": "Length of the returned profile, end of range = start_mm + length_mm.", + "units": "mm", + "default": 5000 }, { "name": "msec_per_ping", - "type": "u32" + "type": "u32", + "description": "Set value to limit ping rate, normally set to 0 for best ping rate.", + "units": "msec", + "default": 0 }, { "name": "reserved_1", - "type": "float" + "type": "float", + "description": "Set to 0", + "default": 0 }, { "name": "reserved_2", - "type": "float" + "type": "float", + "description": "Set to 0", + "default": 0 }, { "name": "pulse_len_percent", - "type": "float" + "type": "float", + "description": "% of total ping time for current range, 0.002 typical.", + "default": 0.002 }, { "name": "filter_duration_percent", - "type": "float" + "type": "float", + "description": "0.0015 typical.", + "default": 0.0015 }, { "name": "gain_index", - "type": "i16" + "type": "i16", + "description": "Set to -1 for auto gain, otherwise 0-7 sets gain.", + "default": -1 }, { "name": "num_results", - "type": "u16" + "type": "u16", + "description": "Number of signal data points in resulting profile (200-1200), 600 typical.", + "default": 600 }, { "name": "enable", - "type": "u8" + "type": "u8", + "description": "1 or 0 to enable or disable pinging.", + "default": "True" }, { "name": "reserved_3", - "type": "u8" + "type": "u8", + "description": "Set to 0", + "default": 0 + }, + { + "name": "reserved_4", + "type": "u8", + "description": "Set to 0", + "default": 0 + }, + { + "name": "reserved_5", + "type": "u8", + "description": "Set to 0", + "default": 0 } ] } diff --git a/src/definitions/s500.json b/src/definitions/s500.json new file mode 100644 index 00000000..46b7df4a --- /dev/null +++ b/src/definitions/s500.json @@ -0,0 +1,337 @@ +{ + "messages": { + "control": { + "set_ping_params": { + "description": "Set parameters", + "id": 1015, + "payload": [ + { + "default": 0, + "description": "Start of ping range, normally set to 0.", + "name": "start_mm", + "type": "u32", + "units": "mm" + }, + { + "default": 5000, + "description": "Length of the returned profile. End of range = start_mm + length_mm. Set to 0 for auto_range.", + "name": "length_mm", + "type": "u32", + "units": "mm" + }, + { + "default": -1, + "description": "Set to -1 for auto gain, otherwise 0-13 sets gain for manual gain.", + "name": "gain_index", + "type": "i16" + }, + { + "default": -1, + "description": "Set to -1 to start a single ping. Otherwise sets minimum ping interval.", + "name": "msec_per_ping", + "type": "i16", + "units": "msec" + }, + { + "default": 0, + "description": "0 for auto mode. Currently ignored and auto duration is always used.", + "name": "pulse_len_usec", + "type": "u16" + }, + { + "default": 0, + "description": "The ID of the packet type that you would like in response. Options are distance2 (1223), profile6 (1308), or zero. Zero disables pinging.", + "name": "report_id", + "type": "u16" + }, + { + "default": 0, + "description": "Set to 0", + "name": "reserved", + "type": "u16" + }, + { + "default": 0, + "description": "Set to 1 for chirp, 0 for monotone ping.", + "name": "chirp", + "type": "u8" + }, + { + "default": 0, + "description": "Set to 0 for auto range resolution in chirp mode", + "name": "decimation", + "type": "u8" + } + ] + }, + "set_speed_of_sound": { + "description": "Set the speed of sound", + "id": 1002, + "payload": [ + { + "description": "The speed of sound in the measurement medium, ~1,500,000 mm/s for water.", + "name": "sos_mm_per_sec", + "type": "u32", + "units": "mm/s" + } + ] + } + }, + "get": { + "altitude": { + "id": 1211, + "payload": [ + { + "description": "Result of most recent calculated distance from device to bottom (or other target).", + "name": "altitude_mm", + "type": "u32", + "units": "mm" + }, + { + "description": "Measure of confidence of altitude measure, 0 (No idea) to 100 (Quite sure).", + "name": "quality", + "type": "u8" + } + ] + }, + "distance2": { + "description": "Reports a simple distance measurement.", + "id": 1223, + "payload": [ + { + "description": "Distance of most recent ping", + "name": "ping_distance_mm", + "type": "u32", + "units": "mm" + }, + { + "description": "Average distance over last 20 pings", + "name": "averaged_distance_mm", + "type": "u32", + "units": "mm" + }, + { + "name": "reserved", + "type": "u16" + }, + { + "description": "0 to 100", + "name": "ping_confidence", + "type": "u8" + }, + { + "description": "0 to 100", + "name": "average_distance_confidence", + "type": "u8" + }, + { + "name": "timestamp", + "type": "u32", + "units": "msec" + } + ] + }, + "fw_version": { + "id": 1200, + "payload": [ + { + "name": "device_type", + "type": "u8" + }, + { + "name": "device_model", + "type": "u8" + }, + { + "name": "version_major", + "type": "u16" + }, + { + "name": "version_minor", + "type": "u16" + } + ] + }, + "gain_index": { + "id": 1207, + "payload": [ + { + "description": "Current gain index setting", + "name": "gain_index", + "type": "u32" + } + ] + }, + "ping_rate_msec": { + "id": 1206, + "payload": [ + { + "description": "Minimum time between successive pings. Can be longer depending on range.", + "name": "msec_per_ping", + "type": "u16", + "units": "msec" + } + ] + }, + "processor_degC": { + "id": 1213, + "payload": [ + { + "description": "Device CPU temperature, result = degrees C * 100", + "name": "centi_degC", + "type": "u32", + "units": "centi-degrees C" + } + ] + }, + "profile6_t": { + "description": "Reports 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.", + "id": 1308, + "payload": [ + { + "description": "Sequentially assigned from 0 at power up.", + "name": "ping_number", + "type": "u32" + }, + { + "description": "Start of ping range", + "name": "start_mm", + "type": "u32", + "units": "mm" + }, + { + "description": "Length of the returned profile. End of range = start_mm + length_mm.", + "name": "length_mm", + "type": "u32", + "units": "mm" + }, + { + "description": "Initial frequency of ping.", + "name": "start_ping_hz", + "type": "u32", + "units": "hz" + }, + { + "description": "Final frequency of ping.", + "name": "end_ping_hz", + "type": "u32", + "units": "hz" + }, + { + "description": "Sampling rate of adc", + "name": "adc_sample_hz", + "type": "u32", + "units": "hz" + }, + { + "name": "timestamp_msec", + "type": "u32", + "units": "msec" + }, + { + "name": "spare2", + "type": "u32" + }, + { + "description": "Pulse duration in seconds.", + "name": "pulse_duration_sec", + "type": "float", + "units": "sec" + }, + { + "name": "analog_gain", + "type": "float" + }, + { + "description": "Maximum power level in dB.", + "name": "max_pwr_db", + "type": "float", + "units": "dB" + }, + { + "description": "Minimum power level in dB.", + "name": "min_pwr_db", + "type": "float", + "units": "dB" + }, + { + "description": "Depth in meters as calculated from most recent ping.", + "name": "this_ping_depth_m", + "type": "float", + "units": "m" + }, + { + "description": "Smoothed calculated depth in meters.", + "name": "smooth_depth_m", + "type": "float", + "units": "m" + }, + { + "description": "0", + "name": "fspare2", + "type": "float" + }, + { + "description": "Depth measurement confidence (0-100) based on most recent ping.", + "name": "ping_depth_measurement_confidence", + "type": "u8" + }, + { + "name": "gain_index", + "type": "u8" + }, + { + "name": "decimation", + "type": "u8" + }, + { + "description": "0 (0-100)", + "name": "smoothed_depth_measurement_confidence", + "type": "u8" + }, + { + "name": "num_results", + "type": "u16" + }, + { + "description": "Power results scaled from min_pwr to max_pwr. num_results entries.", + "name": "pwr_results", + "type": "vector", + "vector": { + "datatype": "u16", + "size": "dynamic" + } + } + ] + }, + "range": { + "id": 1204, + "payload": [ + { + "description": "Normally 0.", + "name": "start_mm", + "type": "u32", + "units": "mm" + }, + { + "description": "start_mm + length_mm is max range.", + "name": "length_mm", + "type": "u32", + "units": "mm" + } + ] + }, + "speed_of_sound": { + "id": 1203, + "payload": [ + { + "description": "Current speed of sound setting in mm/sec, default is 1500 m/sec.", + "name": "sos_mm_per_sec", + "type": "u32", + "units": "mm/sec" + } + ] + } + } + } +} diff --git a/src/definitions/surveyor240.json b/src/definitions/surveyor240.json new file mode 100644 index 00000000..e27c5145 --- /dev/null +++ b/src/definitions/surveyor240.json @@ -0,0 +1,426 @@ +{ + "messages": { + "control": { + "set_net_info": { + "description": "The first octet of the IP address is placed in the least significant byte of the u32. For example, the IP address 192.168.2.2 would be packed into a u32 like this: u32 ip = (192) | (168 << 8) | (2 << 16) | (2 << 24);", + "id": 17, + "payload": [ + { + "description": "IP address of NTP server.", + "name": "ntp_ip_address", + "type": "u32" + }, + { + "description": "Subnet of NTP server.", + "name": "subnet_mask", + "type": "u32" + }, + { + "description": "Gateway IP address of NTP server. Only necessary if NTP server is in different subnet than device and needs to be accessed through a gateway. Otherwise can be left as 0", + "name": "gateway_ip", + "type": "u32" + } + ] + }, + "set_ping_parameters": { + "description": "Used to control the operation of Surveyor", + "id": 3023, + "payload": [ + { + "default": 0, + "description": "Start range in mm at which echo data is recorded. Ignored in auto range mode. Will be forced to 5% of end range as a minimum.", + "name": "start_mm", + "type": "i32", + "units": "mm" + }, + { + "default": 5000, + "description": "End range in mm over which echo data is recorded. Set to 0 for Surveyor to automatically track the bottom and adjust range dynamically.", + "name": "end_mm", + "type": "i32", + "units": "mm" + }, + { + "default": 1500, + "description": "Speed of sound", + "name": "sos_mps", + "type": "float", + "units": "m/s" + }, + { + "default": -1, + "description": "Set to -1 for auto gain (recommended). Valid manual gain ranges are from 0 to 100", + "name": "gain_index", + "type": "i16" + }, + { + "default": 100, + "description": "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.", + "name": "msec_per_ping", + "type": "i16", + "units": "ms/ping" + }, + { + "default": 0, + "description": "Set to 0", + "name": "deprecated", + "type": "u16" + }, + { + "default": 0, + "description": "must be set to 0", + "name": "diagnostic_injected_signal", + "type": "u8" + }, + { + "default": "False", + "description": "true to start/continue pinging, false to stop", + "name": "ping_enable", + "type": "bool" + }, + { + "default": "False", + "description": "Used by SonarView, but not necessary. If enabled log files will be much larger.", + "name": "enable_channel_data", + "type": "bool" + }, + { + "default": "False", + "description": "Must be set to false", + "name": "reserved_for_raw_data", + "type": "bool" + }, + { + "default": "False", + "description": "Angle and time of flight data is preferred for future SonarView enhancements.", + "name": "enable_yz_point_data", + "type": "bool" + }, + { + "default": "False", + "description": "Enable angle and time of flight information for each detected point", + "name": "enable_atof_data", + "type": "bool" + }, + { + "default": 240000, + "description": "Set to 240000. Used for internal production testing only", + "name": "target_ping_hz", + "type": "i32" + }, + { + "default": 400, + "description": "Sets range resolution in number of range steps. Must be between 200 and 800 (inclusive)", + "name": "n_range_steps", + "type": "u16" + }, + { + "default": 0, + "name": "reserved", + "type": "u16" + }, + { + "default": 1.5, + "description": "Pulse length in number of range steps. Recommended value is 1.5", + "name": "pulse_len_steps", + "type": "float" + } + ] + }, + "utc_response": { + "id": 15, + "payload": [ + { + "name": "utc_msec", + "type": "u64" + }, + { + "name": "accuracy_msec", + "type": "u32" + } + ] + } + }, + "general": { + "utc_request": { + "id": 14 + } + }, + "get": { + "atof_point_data": { + "description": "A response packet Surveyor sends to the host application containing angle and time of flight for each detected point.", + "id": 3012, + "payload": [ + { + "description": "Time at start of ping, msec since power on.", + "name": "pwr_up_msec", + "type": "u32", + "units": "msec" + }, + { + "description": "Time at start of ping, utc msec (1970 epoc). Will be 0 if not avaliable.", + "name": "utc_msec", + "type": "u64", + "units": "msec" + }, + { + "description": "Time from start of ping to last range bin.", + "name": "listening_sec", + "type": "float", + "units": "sec" + }, + { + "description": "Speed of sound (mps) used in angle calculations.", + "name": "sos_mps", + "type": "float", + "units": "float" + }, + { + "description": "Assigned sequentially from power on.", + "name": "ping_number", + "type": "u32" + }, + { + "description": "Frequency of the ping signal (Hz).", + "name": "ping_hz", + "type": "u32", + "units": "Hz" + }, + { + "description": "Pulse length in seconds.", + "name": "pulse_sec", + "type": "float", + "units": "sec" + }, + { + "description": "reserved", + "name": "flags", + "type": "u32" + }, + { + "description": "Number of points reported in the points field", + "name": "num_points", + "type": "u16" + }, + { + "name": "reserved", + "type": "u16" + }, + { + "name": "atof_point_data", + "type": "vector", + "vector": { + "datatype": "atof_t", + "size": "dynamic" + } + } + ] + }, + "attitude_report": { + "description": "A response packet Surveyor sends to the host application containing information about the attitude (pitch and roll) of the device based on it's internal sensors.", + "id": 504, + "payload": [ + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_x", + "type": "float" + }, + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_y", + "type": "float" + }, + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_z", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "reserved_1", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "reserved_2", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "reserved_3", + "type": "float" + }, + { + "description": "utc msec (1970 epoc). Will be 0 if not avaliable", + "name": "utc_msec", + "type": "u64", + "units": "msec" + }, + { + "description": "msec since power up", + "name": "pwr_up_msec", + "type": "u32", + "units": "msec" + } + ] + }, + "water_stats": { + "description": "A response packet Surveyor sends to the host application containing information about the temperature and pressure of the water.", + "id": 118, + "payload": [ + { + "name": "temperature", + "type": "float", + "units": "deg C" + }, + { + "name": "pressure", + "type": "float", + "units": "Bar" + } + ] + }, + "yz_point_data": { + "description": "A response packet that Surveyor sends to the host application containing the detected depth points.", + "id": 3011, + "payload": [ + { + "description": "msec since power up", + "name": "timestamp_msec", + "type": "u32", + "units": "msec" + }, + { + "description": "Assigned sequentially from power on.", + "name": "ping_number", + "type": "u32" + }, + { + "description": "Speed of sound", + "name": "sos_mps", + "type": "float", + "units": "m/s" + }, + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_x", + "type": "float" + }, + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_y", + "type": "float" + }, + { + "description": "World up vector (x, y, z) in the device coordinate system (x forward, y port, z up)", + "name": "up_vec_z", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "mag_vec_x", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "mag_vec_y", + "type": "float" + }, + { + "description": "reserved for future magnetic field vector", + "name": "mag_vec_z", + "type": "float" + }, + { + "name": "reserved_0", + "type": "u32" + }, + { + "name": "reserved_1", + "type": "u32" + }, + { + "name": "reserved_2", + "type": "u32" + }, + { + "name": "reserved_3", + "type": "u32" + }, + { + "name": "reserved_4", + "type": "u32" + }, + { + "name": "reserved_5", + "type": "u32" + }, + { + "name": "reserved_6", + "type": "u32" + }, + { + "name": "reserved_7", + "type": "u32" + }, + { + "name": "reserved_8", + "type": "u32" + }, + { + "name": "reserved_9", + "type": "u32" + }, + { + "description": "-1000 if sensor not installed", + "name": "water_degC", + "type": "float", + "units": "deg C" + }, + { + "description": "Water pressure in bar. -1000 if sensor not installed", + "name": "water_bar", + "type": "float", + "units": "bar" + }, + { + "description": "Reserved for heave in meters.", + "name": "heave_m", + "type": "float", + "units": "meters" + }, + { + "description": "Range at the beginning of the analyzed signals for this ping.", + "name": "start_m", + "type": "float", + "units": "meters" + }, + { + "description": "Range at the end of the analyzed signals for this ping.", + "name": "end_m", + "type": "float", + "units": "meters" + }, + { + "name": "unused", + "type": "u16" + }, + { + "description": "Number of points reported in the points field", + "name": "num_points", + "type": "u16" + }, + { + "description": "Y and Z value pairs for each detected point. Y is athwartships offset in meters, positive to the port side. Z is depth, positive up so all z values will be negative.", + "name": "yz_point_data", + "type": "vector", + "vector": { + "datatype": "float", + "size": "dynamic" + } + } + ] + } + } + } +} \ No newline at end of file diff --git a/src/generate-markdown.py b/src/generate-markdown.py index 09817ac7..f6d15c43 100755 --- a/src/generate-markdown.py +++ b/src/generate-markdown.py @@ -25,7 +25,9 @@ "ping1d", "ping360", "omniscan450", - "ping1dtsr"] + "ping1dtsr", + "surveyor240", + "s500"] for definition in definitions: definitionFile = "%s/%s.json" % (definitionPath, definition)