00001 /** 00002 \file AutoAnchorComms.h 00003 AutoAnchor communications and control library 00004 00005 The auto anchor communications library is implemented using a background thread 00006 to handle the sending and receiving of commands. This means that commands will 00007 not block the user interface, and once communications has started, the main application 00008 need not worry about the communications. 00009 00010 If the status of the auto anchor changes, this is optionally indicated asyncronously 00011 by the StatusChangeFunc function. The application may also choose to regularly poll 00012 the status of the auto anchor 00013 00014 */ 00015 00016 /** 00017 \mainpage Overview 00018 00019 This library provides an interface layer between an auto-anchor device connected 00020 through either a serial port or a USB port and your application. 00021 00022 \section including_sec Including in your application 00023 To use the library, include AutoAnchorComms.h and UsbDirect.h in your application, 00024 and then link with aainterface.lib 00025 00026 \section distrib_sec Distributing with your application 00027 Aainterface.dll must be distributed with your application. If you wish to use the 00028 Usb interface functions the drivers must also be installed. 00029 */ 00030 00031 #ifndef _AutoAnchorComms_H 00032 #define _AutoAnchorComms_H 00033 00034 #if defined(__AACOMMS_EXPORTS) 00035 #define __DLL_EXPORT __export 00036 #elif defined(__AACOMMS_IMPORTS) 00037 #define __DLL_EXPORT __import 00038 #else 00039 #define __DLL_EXPORT 00040 #endif 00041 00042 #define MAX_SW_VERSION_STR_LEN 6 00043 #define MAX_SW_BUILD_DATE_STR_LEN 11 00044 #define MAX_HW_VERSION_STR_LEN 10 00045 #define MAX_UNIT_SERIAL_NO_STR_LEN 10 00046 00047 //! Indicates what type of rode is currently present 00048 typedef enum { 00049 rsChain, //! Chain is passing through gypsy 00050 rsRope //! Rope is passing through gypsy 00051 } TRodeStatus; 00052 00053 //! The movement that the gypsy is currently performing 00054 typedef enum { 00055 dStopped, //! Windlass is stopped 00056 dMovingDown, //! Windlass is moving down 00057 dMovingUp, //! Windlass is moving up 00058 dLast 00059 } TWinchDirection; 00060 00061 //! Error conditions that the unit may return 00062 typedef enum { 00063 weNone, //! No error detected 00064 weSensorWiring, //! There is a problem with sensor wiring 00065 weMotorVoltage, //! There is a problem with motor voltage wiring. Only returned on rope/chain installations 00066 weSolenoidUp, //! The wire to the up solenoid is disconnected 00067 weSolenoidDown, //! The wire to the down solenoid is disconnected 00068 weUnderVoltage, //! The voltage applied to the unit is too low 00069 weSmallSignal, //! Signal picked up by sensor is to small. Magnet or sensor may be mounted incorrectly 00070 weExcessiveSignal, //! Signal picked up by sensor is to large. Magnet or sensor may be mounted incorrectly 00071 weSensorPulseTimeout, //! The winch is moving, but no sensor pulses are detected. There may be a problem with sensor wiring, sensor mounting or magnet mounting 00072 weNotInstalled, //! All wires to the unit are disconnected 00073 weUnknown //! An unknown error occured 00074 } TWinchError; 00075 00076 //! Responses to commands 00077 typedef enum { 00078 cmdSuccess, //! The command has completed successfully 00079 cmdFail, //! The command failed 00080 cmdInvalidParameters, //! The parameters passed to the command are invalid 00081 cmdWaitingResponse, //! The command is in progress. Waiting for a response from unit. Keep polling until command complete 00082 cmdUserCancel //! User cancelled the command 00083 } TCommandResponse; 00084 00085 //! Possible connection states 00086 typedef enum { 00087 csOK, //! Connection is open, and AASTAT messages are being received 00088 csCommsTimeout, //! Connection is open, but no AASTAT messages are being received 00089 csIOError, //! There was a problem with the communications channel (USB or Serial port) 00090 csInvalidHandle //! The handle specified is not valid 00091 } TConnectionStatus; 00092 00093 //! Callback function type used for indicating a change of status 00094 typedef void(*cbFunc)(void*); 00095 00096 //! Stores all of the status information for a particular winch 00097 typedef struct { 00098 //! The rode deployed in meters 00099 double RodeDeployed; 00100 //! Inidicates if rode or chain is passing through the gypsy 00101 TRodeStatus RodeStatus; 00102 //! Indicates the direction the winch is moving in 00103 TWinchDirection Direction; 00104 //! Motor voltage. In volts 00105 double MotorVoltage; 00106 //! Motor speed in RPM 00107 double MotorSpeed; 00108 //! Motor load in kg 00109 double MotorLoad; 00110 //! Indicates the most recent error received from the Auto anchor. The error will 00111 //! stay set even after the error condition has gone away. 00112 TWinchError LastError; 00113 //! Version of the firmware in the AA601. Check VersionsValid flag before using 00114 char SWVersionStr[MAX_SW_VERSION_STR_LEN]; 00115 //! Build date of the firmware in the AA601. Check VersionsValid flag before using 00116 char SWBuildDateStr[MAX_SW_BUILD_DATE_STR_LEN]; 00117 //! Hardware version of the AA601. Check VersionsValid flag before using 00118 char HWVersionStr[MAX_HW_VERSION_STR_LEN]; 00119 //! SWVersionStr, SWBuildDateStr & HWVersionStr are only valid if this flag is set 00120 BOOL VersionsValid; 00121 //! The system tick time when the last settings message was received 00122 int LastSettingsTime; 00123 //! The anchor profile that is active 00124 int AnchorProfile; 00125 //! The number of available anchor profiles 00126 int AnchorProfileCount; 00127 //! The circumference of the gypsy (for chain only winches) 00128 int ChainGypsyCircumference; 00129 //! The number of pulses since the last AASTAT message. Use this to check if the winch has moved 00130 int PulseCounts; 00131 //! This is the maximum rode installed on the unit 00132 int MaxRode; 00133 //! This is the number of seconds that the windlass motor has been running since the AA601 was installed. This counter cannot be cleared 00134 int MotorRunningTime; 00135 //! TRUE if unit is in demo mode (generating pulses internally), FALSE if unit is in normal mode (monitoring sensor and motor wires) 00136 BOOL DemoMode; 00137 //! This is set to TRUE if the USB connection fails (usually due to disconnection) 00138 BOOL UsbPortDisconnected; 00139 } TAnchorStatus; 00140 00141 /** 00142 Initialisation function. This function must be called before any of the other 00143 functions in the library 00144 00145 \param StatusChangeFunc This function is called when a new AASTAT message is received. 00146 Be aware that the function is not called from the main application 00147 thread 00148 00149 \param CustData This data is passed to the StatusChangeFunc. Can be used to 00150 identify which winch status changed in a multi-winch environment. 00151 00152 \param PortName Name of the comport to open (e.g. "COM1", "COM2", ...) or serial 00153 number of USB interface to open (e.g. "DPNY3A6P"). If "DEMO" is 00154 specified the library will emulate a connection 00155 00156 \param DisableCommsAckMsg If this is 0, an acknowledge is sent to the aa601 00157 after every AASTAT, and clearing rode by shorting 00158 comms lines is disabled. 00159 Any other value stops acks, and enables clearing rode 00160 by shorting comms lines 00161 00162 \returns Handle to auto-anchor interface, or -1 when an error has occurred 00163 */ 00164 int __DLL_EXPORT 00165 AAComms_Init( cbFunc StatusChangeFunc, void *CustData, char *PortName, int DisableCommsAckMsg ); 00166 00167 /** 00168 Stop an auto-anchor interface that was previously opened with the AAComms_Init function 00169 00170 \param handle The handle of the auto-anchor interface to stop 00171 00172 \returns True when communications stopped with no errors, False otherwise 00173 */ 00174 BOOL __DLL_EXPORT 00175 AAComms_Stop( int handle ); 00176 00177 /** 00178 Gets the current status of the auto anchor connection 00179 00180 \param handle The handle of the auto-anchor connection to get status of 00181 00182 \retval csOK If sentences are being received from auto-anchor 00183 \retval csCommsTimeout Communications has timed out 00184 \retval csIOError There has been an io error (e.g. USB was unplugged) 00185 \retval csInvalidHandle For an invalid handle input 00186 */ 00187 TConnectionStatus __DLL_EXPORT 00188 AAComms_GetConnectionStatus( int handle ); 00189 00190 /** 00191 Gets the current status of the auto anchor 00192 00193 \param handle The handle of the auto-anchor connection to get status of 00194 00195 \param status Pointer to structure to store the auto anchor status in 00196 00197 \retval TRUE Status was read successfully 00198 \retval FALSE There is an error 00199 */ 00200 BOOL __DLL_EXPORT 00201 AAComms_GetStatus( int handle, TAnchorStatus *status ); 00202 00203 /** 00204 Clears the rode to zero 00205 To prevent the user interface from locking up each time a command is sent, the 00206 function will always return immediately even if the command is not complete. 00207 You need to keep polling the function to discover when the command finishes (or fails). 00208 00209 \param handle The handle of the auto-anchor connection to set to zero 00210 00211 \retval cmdSuccess This indicates that a previously initiated command has completed 00212 \retval cmdFail This indicates that a previously initiated command has failed 00213 \retval cmdInvalidParameters The parameters of the command are invalid 00214 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00215 */ 00216 TCommandResponse __DLL_EXPORT 00217 AAComms_ClearRode( int handle ); 00218 00219 TCommandResponse __DLL_EXPORT 00220 AAComms_DebugEnable( int handle, BOOL enable ); 00221 00222 /** 00223 Use this function to set NMEA message rates. 00224 To prevent the user interface from locking up each time a command is sent, the 00225 function will always return immediately even if the command is not complete. You 00226 need to keep polling the function to discover when the command finishes (or fails). 00227 00228 \param handle The handle of the auto-anchor connection 00229 00230 \param MsgName Message name to set the output rate for 00231 00232 \param interval The desired output rate of the message in milliseconds. 00233 Pass 0 to turn message output off 00234 Pass -1 to output message immediately. Normal message rate not affected 00235 00236 \retval cmdSuccess This indicates that a previously initiated command has completed 00237 \retval cmdFail This indicates that a previously initiated command has failed 00238 \retval cmdInvalidParameters The parameters of the command are invalid 00239 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00240 */ 00241 TCommandResponse __DLL_EXPORT 00242 AAComms_SetMsgRate( int handle, char *MsgName, int interval ); 00243 00244 /** 00245 Sets the winch settings 00246 To prevent the user interface from locking up each time a command is sent, the 00247 function will always return immediately even if the command is not complete. You 00248 need to keep polling the function to discover when the command finishes (or fails). 00249 00250 \param handle The handle of the auto-anchor connection 00251 00252 \param AnchorProfile Anchor winch profile. Set to 0 for chain only winches 00253 00254 \param ChainGypsyCircumference Gypsy circumference for chain in mm * 10. 00255 Ignored for profiles > 0 00256 00257 \param MaxRode The maximum amount of rode on board. This is not used by the AA601 at 00258 present (but may be a convenient place to store this value of the display 00259 unit) 00260 00261 \retval cmdSuccess This indicates that a previously initiated command has completed 00262 \retval cmdFail This indicates that a previously initiated command has failed 00263 \retval cmdInvalidParameters The parameters of the command are invalid 00264 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00265 */ 00266 TCommandResponse __DLL_EXPORT 00267 AAComms_SetWinchSettings( int handle, int AnchorProfile, int ChainGypsyCircumference, int MaxRode ); 00268 00269 /** 00270 Reads the winch settings 00271 To prevent the user interface from locking up each time a command is sent, the 00272 function will always return immediately even if the command is not complete. You 00273 need to keep polling the function to discover when the command finishes (or fails). 00274 00275 \param handle The handle of the auto-anchor connection 00276 00277 \param AnchorProfile Location to store anchor winch profile. 0 indicates a chain-only setup 00278 00279 \param ChainGypsyCircumference Location to store gypsy circumference for chain in mm * 10. 00280 Ignored for profiles > 0 00281 00282 \param MaxAnchorProfile Location to store the number of available profiles on the unit 00283 00284 \param MaxRode Location to store the maximum amount of rode on board. This is not used by 00285 the AA601 at present (but may be a convenient place to store this value of the 00286 display unit) 00287 00288 \retval cmdSuccess This indicates that a previously initiated command has completed 00289 \retval cmdFail This indicates that a previously initiated command has failed 00290 \retval cmdInvalidParameters The parameters of the command are invalid 00291 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00292 */ 00293 TCommandResponse __DLL_EXPORT 00294 AAComms_GetWinchSettings( int handle, int *AnchorProfile, int *ChainGypsyCircumference, int *MaxAnchorProfile, int *MaxRode ); 00295 00296 /** 00297 Use this function to enable or disable demo mode 00298 To prevent the user interface from locking up each time a command is sent, the 00299 function will always return immediately even if the command is not complete. You 00300 need to keep polling the function to discover when the command finishes (or fails). 00301 00302 \param handle The handle of the auto-anchor connection 00303 \param demo_mode Pass 0 to turn off demo mode, 1 to turn demo mode on 00304 00305 \retval cmdSuccess This indicates that a previously initiated command has completed 00306 \retval cmdFail This indicates that a previously initiated command has failed 00307 \retval cmdInvalidParameters The parameters of the command are invalid 00308 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00309 */ 00310 TCommandResponse __DLL_EXPORT 00311 AAComms_SetDemoMode( int handle, int demo_mode ); 00312 00313 /** 00314 Reads the software and firmware versions from the device 00315 To prevent the user interface from locking up each time a command is sent, the 00316 function will always return immediately even if the command is not complete. You 00317 need to keep polling the function to discover when the command finishes (or fails). 00318 00319 \param handle The handle of the auto-anchor connection 00320 \param FirmwareVersion Location to store firmware version sring. Must be at least 20 bytes 00321 \param FirmwareBuildDate Location to store firmware build date sring. Must be at least 20 bytes 00322 \param HWVersion Location to store hardware version sring. Must be at least 20 bytes 00323 00324 \retval cmdSuccess This indicates that a previously initiated command has completed 00325 \retval cmdFail This indicates that a previously initiated command has failed 00326 \retval cmdInvalidParameters The parameters of the command are invalid 00327 \retval cmdWaitingResponse The command is in progress. Keep polling till a success or fail is returned 00328 */ 00329 TCommandResponse __DLL_EXPORT 00330 AAComms_GetFirmwareVersion( int handle, char *FirmwareVersion, char *FirmwareBuildDate, char *HWVersion ); 00331 00332 #endif