EdgeTechHandler Class Reference 
===============================

Table of Contents
-----------------
1. [Introduction](#intro)
2. [Constructors](#const)
3. [Public Functions](#pub)
	+ [Connection Services](#conn)
	+ [Enabling Services](#enab)
	+ [Configuration Services](#config)
	+ [Query Services](#query)
	+ [Print Services](#print)
	+ [Data Transmission Services](#data)




Introduction {#intro}
------------

The `EdgeTechHandler` class is the main usage class required for 
interface to the edgetech fsdw system. It directly interacts through 
tcp sockets with the `sonar.exe` program running subsea. It can query
and change settings vital to running the system. This document is a 
functional reference and guide to using this C++ class.

By default this class was programmed to manipulate a three channel 
system. This is controlled by the `ET_SUBSYSTEMS` macro. In many 
function references you will see the `subsysId_t` type called for 
input. Options are:

    SUBSYSID_SB
    SUBSYSID_SSHF
    SUBSYSID_SSLF

All functions discussed in this document are public, further descriptions 
for private methods are found in the source code. 
 
Constructors {#const}
------------

#### EdgeTechHandler::EdgeTechHandler()

    EdgeTechHandler::EdgeTechHandler(char * etSockIP, 
       	int sonarCmdSockPort, int sonarDataSockPort, 
		FILE * logfds)

This is the default constructor.
  
Variables:

+ `etSockIP`: Textual address for resolution IP address or dynamic name acceptable
+ `sonarCmdSockPort`: integer of target tcp port for sonar command server
+ `sonarDataSockPort`: integer of target tcp port for sonar data server
+ `logfds`: file descriptor for log output of the class, typically STDOUT


#### EdgeTechHandler::Initialize() ####

	bool EdgeTechHandler::Initialize()

Function that should directly follow established connection.
 

Public Functions {#pub}
----------------
### Connection Services ### {#conn}

#### EdgeTechHandler::PingOnce() 

	int EdgeTechHandler::PingOnce(subsysId_t subsys)

Conduct a single ping for testing purposes.

**Returns:** 0 on success, negative value for number of communication errors.


#### EdgeTechHandler::Connect() 

	int EdgeTechHandler::Connect() 

This method configures and connects tcp client sockets
 
#### EdgeTechHandler::Disconnect()

	void EdgeTechHandler::Disconnect() 
		
Close file descriptors opened in the constructor

#### EdgeTechHandler::isConnected()

	bool EdgeTechHandler::isConnected()

Returns the logical status of an established tcp client to the edgetech command port.
 
 



#### EdgeTechHandler::IsHealthy()

	bool EdgeTechHandler::IsHealthy(void)

Returns the logical status of the connection after sending a test message.

**Returns:** 1 is connected, 0 is not connected.

### Enabling Services ### {#enab}

#### EdgeTechHandler::EnablePing() 

	int EdgeTechHandler::EnablePing(subsysId_t subsys, bool bEnable, const bool &bUpdate, const long &lTimeOutMS)

Enable (true) or disable (false) on given subsys

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::EnablePingAllChannels() 

	int EdgeTechHandler::EnablePingAllChannels(bool bEnable, const bool &bUpdate) 

Enable (true) or disable (false) all channels.

#### EdgeTechHandler::StorageEnable()

	void EdgeTechHandler::EnableStorage(bool bEnable, const bool &bUpdate) 

Enables recording to storage if 1, disables on 0.

**TODO: does not work, investigating with Edgetech.**

### Configuration Services ### {#config}

#### EdgeTechHandler::SetPingRate() 

	int EdgeTechHandler::SetPingRate(subsysId_t subsys, const float& fPingRatePPS, const bool& bUpdate, const long &lTimeOutMS)

Sets the ping rate through pulses per second.

From SonarMessages.h:
> Number of pings per 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.

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::SetPulseFile() 

		int EdgeTechHandler::SetPulseFile(subsysId_t subsys,
		const char * sPulseFileName, int len, const bool &bUpdate)

Set the active pulse for a given subsystem. Inputs are as follows:

+ `subsys`: id of subsystem
+ `sPulseFileName`: string pointer for filename
+ `len`: length of string

**Returns:** 0 on success, negative value for number of communication errors.
 
#### EdgeTechHandler::SetPulseDuration() 
	
	int EdgeTechHandler::SetPulseDuration(subsysId_t subsys, const float& rfPingDurationMS, const bool& bUpdate, const long & lTimeOutMS)

Sets pulse duration and then changes ping rate accordingly.

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::SetRange() - 
 
	int EdgeTechHandler::SetRange(subsysId_t subsys, float &fRangeM, const bool &bUpdate) 

Sets the range in meters.
 
From SonarMessages.h:
> 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.

**Returns:** 0 on success, negative value for number of communication errors.


#### EdgeTechHandler::SetRxGain() 

	int EdgeTechHandler::SetRxGain(float& fRxGain, const bool &bUpdate) 

Set receive gain, AGC must be disabled

From SonarMessages.h:

> 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.

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::SetTriggerMode()

	int EdgeTechHandler::SetTriggerMode(subsysId_t subsys, ETRIGGERMODE trigMode, const bool &bUpdate) 

Set the triggering mode for an individual channel.
	
From SonarMessages.h:
 
 >	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.

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::SetTxPower()

	int EdgeTechHandler::SetTxPower(subsysId_t subsys, 
		const float &rfTxPower, const bool &bUpdate, 
		const long &lTimeOutMS)

Transmits a message to set projector power on given channel.

Variables: 
+ `maxChannels`: number of channels within the given id
+ `rfTxPower`: float value of percent full power

**Returns:** 0 on success, negative value for number of communication errors.

#### EdgeTechHandler::SetTimeFromSystem() 

	int EdgeTechHandler::SetTimeFromSystem(const bool &bUpdate) 

Set the time from the calling system.
 
From SonarMessages.h:

> 	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.
 
	
#### EdgeTechHandler::ReceiveMessage()

	bool EdgeTechHandler::ReceiveMessage() 

Poll the passed port type for a message in buffer. Usually called by Set or Query functions.
### Query Services ###  {#query}

#### EdgeTechHandler::QueryCommonSettings() 

	int EdgeTechHandler::QueryCommonSettings(void)

Poll sonar servers for status and values.
	
#### EdgeTechHandler::QueryPulseFileListQuery() 

	int EdgeTechHandler::QueryPulseFileListQuery(subsysId_t subsys) 

Send messages to query the sonar for available pulsefiles.
 
**Returns:** 0 on success, negative value for number of communication errors.
	

 
### Print Services ### {#print)

#### EdgeTechHandler::printStatus() 

	void EdgeTechHandler::printStatus(FILE* fid)

Print class/subclass variables to supplied file descriptor.

### Data Transmission Services ### {#data}

#### EdgeTechHandler::SendAltitudeData()

	int EdgeTechHandler::SendAltitudeData(const long & flags, const float & altitudeM, const float & forwardVelocityMS, const float & crossTrackVelocityMS, const long &lTimeOutMS)

Send altitude data.

Inputs are as follows:
+ `flags`: validity flags, see DeviceMessages.h
+ `altitudeM`: in decimal meters
+ `forwardVelocityMS`: Forward velocity in m/s
+ `crossTrackVelocityMS`: Cross track velocity in m/s

**Returns:** 0 on success, negative value for number of communication errors.


#### EdgeTechHandler::SendPressureData() 

	void EdgeTechHandler::SendPressureData(float const &pressurePSI,
		float const &tempC, float const &salPSU, float const &condSM,
		float const &sosMS, float const &depthM, long const &flags)

Assemble a structure and reformat common measurements for onboard storage. Inputs are as follows:

+ `pressurePSI: pressure in decimal PSI
+ `tempC`: temperature in decimal degrees Celsius
+ `salPSU`: salinity in decimal PSU
+ `condSM`: conductivity in saliens per meter
+ `sosMS`:  sound of speed in meters per second
+ `depthM`: depth in decimal meters
+ `flags`:  reserved for future implementation (see devicemessages.h)
 
**Returns:** 0 on success, negative value for number of communication errors.


#### EdgeTechHandler::SendCompleteSituation() 

	int EdgeTechHandler::SendCompositeSituation(const long & flags,
		const unsigned char& vDirections, const long & timestampNS,
		const double& latitudeD, const double& longitudeD, const float& depthM,
		const float& altitudeM, const float& heaveM, const float& velocity1MS,
		const float& velocity2MS, const float& velocityDownMS,
		const float& pitchD, const float& rollD, const float& headingD,
		const float& soundSpeedMS, const float& waterTempC) 

Assemble a structure pack into message for onboard storage, Inputs are as follows:

+ `flags`: ValidityFlags indicated which of the following fields are valid.
+ `vDirections`: Velocity1 and 2 type.  0 => North and east, 1 => Foward and stbd, 2 => +45 degrees rotated from forward.
+ `timestamp`: 1/10 of a ns unit timestamp, us since 12:00:00 am GST, January 1, 1970.  To get seconds since 1970 divide by 1e7.
+ `latitude`:  in degrees, north is positive
+ `longitude`: in degrees, east is positive
+ `depth`: below water in meters.
+ `altitude`: in meters (above sea floor).
+ `heave`: in meters - positive is down
+ `velocity1`: North velocity (or forward) in meters per second (see vDirections)
+ `velocity2`: East velocity or stbd in meters per second (see vDirections)
+ `velocityDown`: Down velocity in meters per second
+ `pitch`: in degrees, bow up positive
+ `roll`: in degrees, port up positive
+ `heading`: in degrees (0-360)
+ `soundSpeedMS`: Sound speed in meters / second
+ `waterTempC`: Water temperature in degrees C
 
**Returns:** 0 on success, negative value for number of communication errors.



#### EdgeTechHandler::SendSituation() 

	int EdgeTechHandler::SendSituation(const long & flags,
		const long & timestampUS, const double& latitudeD,
		const double& longitudeD, const double& depthM, const double& headingD,
		const double& pitchD, const double& rollD, const double& xRelativePosM,
		const double& yRelativePosM, const double& zRelativePosM,
		const double& xVelocityMS, const double& yVelocityMS,
		const double& zVelocityMS, const double& northVelocityMS,
		const double& eastVelocityMS, const double& downVelocityMS,
		const double& xAngularRateDS, const double& yAngularRateDS,
		const double& zAngularRateDS, const double& xAccelerationMS,
		const double& yAccelerationMS, const double& zAccelerationMS,
		const double& latitudeStandardDeviationM,
		const double& longitudeStandardDeviationM,
		const double& depthStandardDeviationM,
		const double& headingStandardDeviationD,
		const double& pitchStandardDeviationD,
		const double& rollStandardDeviationD) 

Send a long set of comprehensive state data

**Returns:** 0 on success, negative value for number of communication errors.