AutoAnchorComms.h

Go to the documentation of this file.
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

Generated on Fri Feb 10 22:31:49 2006 for Auto anchor communications library by  doxygen 1.4.6-NO