/* ---------------------------------------------------------------------- */ /* SonarMessages.h */ /* ---------------------------------------------------------------------- */ /* */ /* Describes the standard sonar messages which can be sent between a */ /* topside and the Surface Interface Unit. Messages always consist of */ /* 2 parts: */ /* 1) A header which contains the message type and length */ /* 2) The actual data */ /* */ /* Note that two communications circuits (sockets) are used. Socket 1600 */ /* is used for commands and socket 1601 is used for data. Commands are */ /* sent from a topside, and the bottom unit may return status on the */ /* command socket. Data is only one way - from the bottom unit to the */ /* topside and returns a header followed by SegyDataType data only. */ /* */ /* The subbottom unit shall have predefined defaults for all parameters, */ /* therefore it is only necessary to send the messages that change the */ /* defaults. Defaults are stored in a file and can be changed using a */ /* text editor. A minimum topside interface can receive data without */ /* sending a single command. */ /* */ /* ---------------------------------------------------------------------- */ /* */ /* (c) Copyright 1998, 1999, 2000 EdgeTech Inc */ /* */ /* This file contains proprietary information, and trade secrets of */ /* EdgeTech, and may not be disclosed or reproduced without the prior */ /* written consent of EdgeTech. */ /* */ /* EdgeTech is not responsible for the consequences of the use or misuse */ /* of this software, even if they result from defects in it. */ /* */ /* ---------------------------------------------------------------------- */ #ifndef __SonarMessages_H__ #define __SonarMessages_H__ /* ---------------------------------------------------------------------- */ /* Includes */ /* ---------------------------------------------------------------------- */ #include "Timestamp.h" #include "PublicMessageOffsets.h" /* ---------------------------------------------------------------------- */ /* Structure defines */ /* ---------------------------------------------------------------------- */ #define FILE_NAME_SIZE (80) #define SONAR_MESSAGE_STRING_LENGTH (256) /* ---------------------------------------------------------------------- */ /* Message Header */ /* ---------------------------------------------------------------------- */ /* All messages are preceeded with a header which indicates the size of */ /* the message to follow in bytes and its type. The header is of type */ /* SonarMessageHeaderType. A version number is included to accomodate */ /* future changes / extensions in the protocol. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Marker for the start of header */ unsigned short int startOfMessage; /* The version of the protocol in use */ unsigned char version; /* Session Identifier */ unsigned char sessionID; /* The message format as per SonarMessageType */ unsigned short int sonarMessage; /* The action to perform as per SonarCommandType */ unsigned char sonarCommand; /* Indicates subsystem (0 is first) for a multi-system device. */ unsigned char subSystem; /* Indicates channel (0 is first) for a multi-channel subsystem. */ unsigned char channel; /* Sequence number of message. A reply to this message will contain */ /* this value. A topside can optionally use this field to track replys */ unsigned char sequence; /* Header space reserved for future use. */ unsigned char reservedHeader[2]; /* Size of message in bytes to follow */ long int byteCount; } SonarMessageHeaderType; /* ---------------------------------------------------------------------- */ /* Header defines */ /* ---------------------------------------------------------------------- */ /* Start of header word */ #define SONAR_MESSAGE_HEADER_START (0x1601) /* The version of the protocol in use */ #define SONAR_PROTOCOL_CURRENT_VERSION (0x04) /* ---------------------------------------------------------------------- */ /* Command Types */ /* ---------------------------------------------------------------------- */ /* Command type(sonarCommand in header). A topside will send SET */ /* commands, which return no values, GET commands, which return the */ /* current parameter set. The bottom unit only sends REPLY messages in */ /* response to a GET or unsolicited data. */ /* ---------------------------------------------------------------------- */ typedef enum { /* Send a value to black box or execute a command */ SONAR_COMMAND_SET = 0, /* Request current value / last value of item. All GETs can be sent */ /* with a byte count of 0. Some GET messages will accept parameters. */ /* See the individual message descriptions for details. */ SONAR_COMMAND_GET, /* Reply to a COMMAND_GET or unsolicited error msgs */ SONAR_COMMAND_REPLY, /* Error replay to a command. The command was not executed. */ /* In this case, the return value is the error (SonarMessageLongType) */ /* as defined by SonarMessageErrorType. */ SONAR_COMMAND_ERROR, /* Similar to a REPLY for the data socket, but is playback data. This */ /* will only occur when storage playback is enabled. */ SONAR_COMMAND_PLAYBACK, } SonarCommandType; /* ---------------------------------------------------------------------- */ /* Error codes that can be returned as SONAR_COMMAND_ERROR */ /* ---------------------------------------------------------------------- */ typedef enum { /* 0: No error */ SONAR_MESSAGE_ERROR_NONE, /* 1: General command failure indicator */ SONAR_MESSAGE_ERROR_FAILED, /* 2: Message size does not match expected size */ SONAR_MESSAGE_ERROR_DATA_SIZE, /* 3: Subsystem number is not present in this system */ SONAR_MESSAGE_ERROR_SUBSYSTEM, /* 4: Channel number is not present in this system */ SONAR_MESSAGE_ERROR_CHANNEL, /* 5: sonarMessage field contains an unknown command */ SONAR_MESSAGE_ERROR_UNKNOWN, /* 6: Pulse file error. Pulse not loaded */ SONAR_MESSAGE_ERROR_PULSE_FILE, /* 7: Session ID error. Command rejected */ SONAR_MESSAGE_ERROR_SESSION_ID, /* 8: Override required: Command rejected */ SONAR_MESSAGE_ERROR_OVERRIDE_REQUIRED, } SonarMessageErrorType; /* ---------------------------------------------------------------------- */ /* Message Types */ /* ---------------------------------------------------------------------- */ /* sonarMessage field indicates the type of data to follow. */ /* ---------------------------------------------------------------------- */ typedef enum { /* -------------------------------------------------------------------- */ /* Overall commands. */ /* For the following messages, the channel and subSystem should be 0. */ /* -------------------------------------------------------------------- */ /* Null message - can be used to test communications */ SONAR_MESSAGE_NONE = MESSAGE_OFFSET_STANDARD, /* Reset to default values (No Data) on set */ /* Note: The subsystem should be 255 to reset the entire system or */ /* the specific subsystem number. The channel must be 0. */ SONAR_MESSAGE_SYSTEM_RESET, /* Get or set the time (TimestampType) */ /* Note that because of the nagle algorithm on sockets, the actual */ /* message can be delayed. To set the time with greater accuracy, say, */ /* within 10 ms, the nagle algorithm should be disabled by the sender. */ /* Or a subsequent message bigger than the maximum network packet size */ /* should be sent following this message (usually about 1600 bytes). */ /* Note: This is a system command, the subsystem and channel numbers */ /* must be 0. */ /* NOTE: The SONAR_MESSAGE_NONE message can be any size desired. */ SONAR_MESSAGE_SYSTEM_TIME, /* Change the time by the delta in milliseconds (SonarMessageLongType) */ /* NOTE that in order to get accurate time sync, a delta must be set via*/ /* this message, and it must be based on the GetTickCount() function. */ /* The normal GetSystemTime() is only accurate to about 50 ms. */ /* Note: This is a system command, the subsystem and channel numbers */ /* must be 0. */ SONAR_MESSAGE_TIME_DELTA, /* Get the software version string (SonarMessageStringType) */ /* Note: This is a system command, the subsystem and channel numbers */ /* must be 0. The version string consists of an alphabetic string */ /* followed by a version number of the form N.M where N and M are both */ /* integers. */ SONAR_MESSAGE_SYSTEM_VERSION, /* Status request / returned from black box (SonarMessageStatusType) */ /* A set can be used to reset status values */ /* Note: This is a system command, the subsystem and channel numbers */ /* must be 0. */ SONAR_MESSAGE_SYSTEM_STATUS = MESSAGE_OFFSET_STATUS, /* Alive messages are echoed back on the same connection. This allows */ /* for the detection of lost connection links. Accepts a long parameter*/ /* (SonarMessageLongType) which is echoed back to the caller and is */ /* typically a sequence number. */ /* Note: This is a system command, the subsystem and channel numbers */ /* must be 0. */ SONAR_MESSAGE_ALIVE, /* Override data lockout caused by suspected system failure in the */ /* sonar system. Once an overrride message is sent, the sonar system */ /* will not stop the data flow because of potential data quality */ /* problems. */ SONAR_MESSAGE_OVERRIDE, /* Run all of the power on self test diagnostics. This will normally */ /* cause an audible chirp on the subbottom (if present) and side scan */ /* low (if present) and other internal diagnostics. This can either */ /* cause OR CLEAR a POST error code. If a post error code is detected */ /* sonar data WILL NOT be returned to the topside unless an override */ /* message is sent. The subsystem and channel should be set to 0 for */ /* this message. The sonarCommand field in the header should be set to */ /* SONAR_COMMAND_GET as this command returns the post status bit field */ /* as the lsb 8 bits of its return value (SonarMessageLongType). See */ /* the SonarMessageStatusType and the serviceNeeded field for a list */ /* of the possible return values. */ SONAR_MESSAGE_RUN_POST_DIAGNOSTICS, /* -------------------------------------------------------------------- */ /* Sonar Return Data */ /* -------------------------------------------------------------------- */ /* Subbottom data returned to topside (SegyDataType) */ /* This is returned from the sonar and is not a command message. */ SONAR_MESSAGE_DATA = MESSAGE_OFFSET_DATA, /* Window for data transmission (SonarMessageWindowType) */ /* Subsystem and channel must be valid. */ SONAR_MESSAGE_DATA_NETWORK_WINDOW, /* Sidescan data returned to topside (SidescanHeaderType) */ /* This is returned from the sonar and is not a command message. */ SONAR_MESSAGE_DATA_SIDESCAN, /* Activate / Deactivate return data type. The data for the subsystem */ /* / channel specified in the header is activated / deactivated */ /* (0 - deactivate : 1 - activate) (SonarMessageLongType) */ /* Subsystem and channel must be valid. */ SONAR_MESSAGE_DATA_ACTIVE, /* -------------------------------------------------------------------- */ /* Compressed header data messages */ /* -------------------------------------------------------------------- */ /* Subbottom data returned to topside (CompactSonarHeaderType) */ /* This is returned from the sonar and is not a command message. */ /* The compression library will unpack this and replace with */ /* a SONAR_MESSAGE_DATA message. */ SONAR_MESSAGE_DATA_COMPACTHEADER, /* Sidescan data returned to topside (CompactSonarHeaderType) */ /* This is returned from the sonar and is not a command message. */ /* The compression library will unpack this and replace with */ /* a SONAR_MESSAGE_DATA_SIDESCAN message */ SONAR_MESSAGE_DATA_SIDESCAN_COMPACTHEADER, /* -------------------------------------------------------------------- */ /* Processing of data */ /* -------------------------------------------------------------------- */ /* Window for processing optimization (SonarMessageWindowType) */ /* Subsystem and channel must be valid. */ SONAR_MESSAGE_PROCESSING_ENHANCE_WINDOW = MESSAGE_OFFSET_PROCESS, /* Samples to ignore due to direct path on AGC, normalization */ /* algorithms (SonarMessageLongType) */ /* Subsystem and channel must be valid. */ SONAR_MESSAGE_PROCESSING_DIRECT_PATH, /* -------------------------------------------------------------------- */ /* Management of pulses */ /* -------------------------------------------------------------------- */ /* Enable/disable ping: 0 => disable, 1=>enable, 2 => single ping only */ /* (SonarMessageLongType) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING = MESSAGE_OFFSET_PULSES, /* 1000.0 * DAC gain to scale outgoing pulse by (SonarMessageLongType) */ /* Subsystem and channel must be valid. */ SONAR_MESSAGE_PING_GAIN, /* A set message takes no parameters. A set message resets the list of */ /* pulse records so that the next get message will return the first */ /* record in the list. */ /* A get message with a (SonarMessageLongType) parameter, returns up to */ /* the specified number of pulse records as an array of */ /* (SonarMessagePingType) values, up to a maximum of 30. */ /* A get message can also be sent with no parameters, in this case it */ /* returns a single (SonarMessagePingType) structure. */ /* The pulse record following the last valid pulse record will have a */ /* NULL pulse name field. */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_LIST, /* Select an outgoing set of pulses, and matched filters. */ /* (SonarMessageStringType) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_SELECT, /* Number of pings pers second required * 1000 */ /* (SonarMessageLongType) */ /* Actual ping rate may be slightly lower (2048 sample granuality) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_RATE, /* Set trigger for internal(0), external(1), coupled(2), or gated(3) */ /* (SonarMessageLongType). Coupled mode causes a system to be triggered*/ /* by another one (eg Sidescan triggered by Subbottom) */ /* See SONAR_MESSAGE_PING_COUPLING_PARAMETERS message. In gated mode */ /* the external trigger is used as a trigger inhibit, and the inhibit */ /* time is based on the coupling parameter delay. */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_TRIGGER, /* Set delay for external trigger in ms (SonarMessageLongType). This */ /* message applies only to the soft trigger. A soft trigger uses the */ /* ethernet to transmit trigger requests to an underwater electronics */ /* bottle and is not present in an FS-SB standard system. See the */ /* SONAR_MESSAGE_PING_COUPLING_PARAMETERS message for a hardwired */ /* trigger delay. */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_DELAY, /* A get message takes a parameter that is 1000 * the ping rate in Hz. */ /* (SonarMessageLongType) and returns a (SonarMessageLongType) with the */ /* maximum number of samples that can be received for that ping rate. */ /* A get message can also be sent with no parameters, in this case it */ /* returns the maximum number of samples for the current ping rate. */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_MAX_SAMPLES, /* Set the ping rate for sidescan systems. Sets the ping rate based */ /* on the range in millimeters. (SonarMessageLongType) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_RANGE, /* Set the coupling parameters for this system when in trigger mode */ /* coupled, and the hardware trigger delay in external trigger modes. */ /* (SonarMessageCouplingParametersType) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_COUPLING_PARAMETERS, /* Get the list of human readable strings and fish IDs. Only a */ /* SONAR_COMMAND_GET message is meaningful. Returns an array of */ /* (SonarMessageFishType) records. The number of records can be */ /* determined by the size of the return message. */ /* This message should be used to get the available EdgeTech fish to */ /* present to the end user. The user should first select the fish */ /* which is attached to the sonar processing system, and should then */ /* select a pulse only from the subset of the selected fish. */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_PING_FISH_LIST, /* -------------------------------------------------------------------- */ /* ADC Control */ /* -------------------------------------------------------------------- */ /* Set gain factor for ADC when AGC disabled (SonarMessageLongType) */ /* Value is * 1000.0 (only 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, */ /* and 2048 supported) */ /* Subsystem and channel must be valid. Ignored on sidescan systems. */ SONAR_MESSAGE_ADC_GAIN = MESSAGE_OFFSET_ADC, /* 0=> disable, 1=> enable (Automatic Gain Control) */ /* (SonarMessageLongType) */ /* Subsystem and channel must be valid. Ignored on sidescan systems. */ SONAR_MESSAGE_ADC_AGC, /* ADC rate in Hz * 1000. This is a read only value and changes with */ /* the pulse selected (SonarMessageLongType) */ /* Note: This is a subsystem command, the channel number must be 0. */ SONAR_MESSAGE_ADC_RATE, } SonarMessageType; /* ---------------------------------------------------------------------- */ /* Message Data Structures */ /* ---------------------------------------------------------------------- */ /* The data component of the messages varies with the sonarMessage as */ /* defined by the structures below. */ /* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */ /* General integer parameter */ /* ---------------------------------------------------------------------- */ typedef struct { long value; /* Value for message */ } SonarMessageLongType; /* ---------------------------------------------------------------------- */ /* General purpose string argument. */ /* ---------------------------------------------------------------------- */ typedef struct { char name[SONAR_MESSAGE_STRING_LENGTH]; /* String parameter */ } SonarMessageStringType; /* ---------------------------------------------------------------------- */ /* SONAR_MESSAGE_STATUS parameters */ /* ---------------------------------------------------------------------- */ typedef struct { /* Incremented each time a ping is dropped. */ unsigned long overflowCount; /* The current error count. */ unsigned long errorCount; /* Error ids of last 10 errors. */ short int lastError[10]; /* Disk space available for sonar data storage in kb. */ unsigned long freeDiskSpace; /* Indicates that data is being received (increments over time). */ unsigned long dataAcquisitionActivityIndicator; /* General service warning message */ /* This is a bit map with one bit for each power on self test status. */ /* A non-zero bit indicates a POST test failure. */ /* Bit 0 : SB Power Amp feedback on channel 0 test failed. */ /* Bit 1 : SB Power Amp feedback on secondary channel (1) test failed. */ /* Bit 2 : Interface Card diagnostic failed. */ /* Bit 3 : 48 Volt Power Check Failed. */ /* Bit 4 : Reserved */ /* Bit 5 : Reserved */ /* Bit 6 : Reserved */ /* Bit 7 : Temperature sensor failure suspected */ unsigned char serviceNeeded; /* Ambient Temperature out of range flags. */ /* Bit 0 : Temperature is out of range. */ unsigned char temperatureFlags; /* Humidity out of range indicator */ /* Bit 0 : Humidity reading outside of expected range */ unsigned char humidityFlags; /* Storage subsystem flags */ /* Bit 0 : Disk storage is enabled (should be set when on). */ /* Bit 1 : Disk primary drive error detected. Operator needs to reset. */ /* Bit 2 : Disk write error on drive - all storage disabled. */ /* Bit 7 : Disk playback is enabled. */ unsigned char storageFlags; /* Ambient Temperature status. */ /* 0 : Temperature is OK */ /* 1 : Temperature is in error - below minimum possible value. */ /* 2 : Temperature is below recommended value. */ /* 3 : Temperature is above recommended value. */ /* 4 : Temperature is too high - PINGING IS DISABLED. */ /* 5 : Temperature is in error - above maximum possible value. */ unsigned char temperatureStatus; /* space saver for more status bytes. */ unsigned char reserved1[1]; /* Internal resets to date. */ unsigned short resetCount; /* Bottle temperature in Degrees C * 1000. */ long int bottleTemperature; /* Ambient temperature in Degrees C * 1000. */ long int ambientTemperature; /* Check of 48 Volt Power in milli-Volts. */ long int power48Volts; /* Humidity sensor reading in % (0 to 100) */ long int humidity; /* Low rate misc io analog values. */ short int lowRateIO[4]; /* Reserved for future expansion. */ long int reserved[8]; } SonarMessageStatusType; /* ---------------------------------------------------------------------- */ /* Ping First / Next data files */ /* ---------------------------------------------------------------------- */ typedef struct { /* Name used to identify this pulse for selection. */ char fileName[FILE_NAME_SIZE]; /* Type of pulse. */ unsigned long pulseType; /* Minimum frequency in Hz */ unsigned long fMin; /* Maximum frequency in Hz */ unsigned long fMax; /* Pulse duration in milliSeconds */ unsigned long time; /* Unique pulse identifier */ unsigned short pulseID; /* Unused field - round to long boundary. */ unsigned short reserved; /* Pulse description - null terminated ASCII string */ char description[SONAR_MESSAGE_STRING_LENGTH]; /* Type of sonar pulse was designed for. */ unsigned long systemType; } SonarMessagePingType; /* ---------------------------------------------------------------------- */ /* List of supported towfish (systemType) and their human readable text. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Type of sonar. Each pulse, as specified in the SonarMessagePingType */ /* message is for a specific type of sonar towfish. This is the unique */ /* identifier for that sonar towfish. */ unsigned long systemType; /* Human readable text description of this system. This string should */ /* be presented to an end user to select a fish type. Only pulses for */ /* a selected fish should be presented to an end user for selection. */ char systemName[20]; } SonarMessageFishType; /* ---------------------------------------------------------------------- */ /* Window for network data */ /* ---------------------------------------------------------------------- */ typedef struct { /* Frame decimation factor */ unsigned short frameDecimation; /* Pixel decimation factor */ unsigned short decimation; /* ADC samples to skip */ unsigned long initialSkip; /* Total samples to return */ /* If this value is set to zero, the maximum amount of data possible */ /* using the current ping rate or range will be sent. */ /* SEG-Y limits the number of samples per packet to an unsigned short. */ /* If large sample sizes are required multiple packets must be used. */ unsigned long totalSamples; /* Packet size in samples */ /* Due to buffer limitations the current system retricts this to under */ /* 512KB. */ unsigned long maxPacketSize; } SonarMessageWindowType; /* ---------------------------------------------------------------------- */ /* Coupling Parameters data structure. */ /* ---------------------------------------------------------------------- */ typedef struct { /* Subsystem number to trigger this subsystem on */ long subSystem; /* Trigger on every Nth event (minimum value of 1). */ long triggerDivisor; /* Trigger delay in micro-seconds for external or coupled modes. */ /* Trigger inhibit time for gated mode. (minimum value of 0) */ long triggerDelay; } SonarMessageCouplingParametersType; /* ---------------------------------------------------------------------- */ /* Compact Sonar Data Header Structure */ /* ---------------------------------------------------------------------- */ typedef struct { /* 0 - 1 : Ping number (increments with ping) */ unsigned short int pingNum; /* 2 - 3 : starting Depth (window offset) in samples */ unsigned short int startDepth; /* 4 - 5 : Maximum absolute value for ADC samples for this packet */ unsigned short ADCMax; /* 6 - 6 : -- defined as 2 -N volts for lsb */ char weightingFactor; /* 7 - 7 : Data format */ /* 0 = 1 short per sample - envelope data */ /* 1 = 2 shorts per sample - stored as real(1), imag(1), */ /* 2 = 1 short per sample - before matched filter (raw) */ /* 3 = 1 short per sample - real part analytic signal */ /* NOTE: For type = 1, the total number of bytes of data to follow is */ /* 4 * samples. For all other types the total bytes is 2 * samples. */ unsigned char dataFormat; /* 8 - 11 : Sample interval in ns of stored data */ unsigned long int sampleInterval; /* 12 - 15 : Millieconds today time stamp */ unsigned long int millisecondsToday; } CompactSonarHeaderType; #endif /* Not __SonarMessages_H__ */ /* ---------------------------------------------------------------------- */ /* end SonarMessages.h */ /* ---------------------------------------------------------------------- */