/***************************************************************************** - - - POLONY SEQUENCER ACQUISITION SUITE - - Church Lab - - Harvard Medical School - - - - Free software for running a Polony Sequencing automated microscope - - - - ========================================================================= - - - - - - cstage.h - - - - Interface class to Prior encoded stage - - - - Written by Michelle Kuykendal, 08-10-2005 - - - - Revised - - 02-15-2006 GP; added functions to return stage pos, commented nested - - blocks - - - - This software may be used, modified, and distributed freely, but this - - header may not be modified and must appear at the top of this file. - - - - - *****************************************************************************/ /****************************************************************************** ******************************************************************************* **** File: cstage.h **** **** Requirements: cstage.cpp and cport.h should exist in the same **** **** directory as this file. **** **** Purpose: this file defines the CStage class to be used with a **** **** Prior ProScan II Motorized Microscope Stage. it enables the user **** **** to set, confirm, and get the stage position and to initialize and **** **** close the stage. it also provides functions to write to and read **** **** from the stage via the comm port to enable the addition of new **** **** functions in the future. **** **** Initial Version: Aug. 10, 2005 **** **** Programmer: Michelle Kuykendal **** ******************************************************************************* ******************************************************************************/ #ifndef CSTAGE_H #define CSTAGE_H #include #include #include "cport.h" //serial port class #include "reporter.h" class CStage { public: //REQUIREMENTS: none. //USE: CStage() is the constructor for the stage class. it will initialize // the variable stageIsInit (used to check for stage intialization) to // false. it will intialize the Response (char * variable to hold the // expected response from a read call) and xyzPos (after a call to // GetPosition(), this char * variable will hold the x, y, and z positions // of the stage if the return is true. it will hold the string, "Could not // get stage position." if the return is false) variables to NULL. it will // also initialize the minimum and maximum values allowed for the x and y // stage positions. //RETURN VALUE: none. CStage(Reporter*); //REQUIREMENTS: none. //USE: ~CStage() is the destructor for the stage class. //RETURN VALUE: none. ~CStage(); //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. //USE: SetPosition() will check that the x and y values passed to it are // within a valid range for the stage movement. if the variables are in // the valid range, the function will set the private variables, setx and // sety to the values passed. next, the function will write to the stage // to set its position to x,y. it will not set the z position of the stage. // it will then read from the stage until it receives a confirmation // response that the command was received. //RETURN VALUE: the return will be false if the stage was not previously // initialized, if either of the passd variables (x or y) are outside of // the valid range, or if the WriteStage() call is unsuccessful. otherwise, // the return will be true if the stage is already initialized, the x and y // variables are within valid range, and the write and read were // successful. bool SetPosition(int x, int y); //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. // also, a call to SetPosition() should first be made and should return // true. //USE: ConfirmPosition() will continuously write to and read from the stage // to get the current stage position and will compare it to the position // that should have been set during the call to SetPosition(). it will // accept that the stage is in the correct position when it moves within // 200 units on both the x and y axis. //RETURN VALUE: the return will be false if the stage was not previously // initialized, if the WriteStage() call is ever unsuccessful, or if the // function looking for the appropriate position times out. otherwise, // the return will be true when the stage is in the desired location as was // specified by the call to SetPosition(). bool ConfirmPosition(); //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. //USE: GetPosition() will write to and read from the stage to get the // current stage position. it will assign the position to a string to be // returned. //RETURN VALUE: if the call is successful the return will be a string // containing the current stage position in the format, // "X,Y,Z = currentX,currentY,0" where currentX and current Y are the // current stage positions. the string will contain "Could not set the // stage position" if the stage was not previously initialized, or if // the WriteStage() call is unsuccessful. char *GetPosition(); double GetPosX(); double GetPosY(); //REQUIREMENTS: the stage device should be connected to comm port 8 //USE: Init() will first check to be sure the stage has not already been // initialized. it will then open and setup comm port 8. three commands // will be sent to the stage to set its compatibility mode, acceleration // and speed. //RETURN VALUE: the return will be false is the stage was already // initialized or if any of the writes and reads failed. the return will // be true if the stage was not already initialized, the comm port was // opened successfully, and the three initialization commands were // properly sent and executed. bool Init(); //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. //USE: Close() will check to see that the stage was first intialized. it // will then close the comm port that was opened during the call to Init(), // and reset the stage initialization checker to false. //RETURN VALUE: if the port was successfully closed, the return will be // true. otherwise,the return will be false. bool Close(); private: //stage serial port object for reading and writing to COM8 CPort PortStage; //boolean variable to be updated to "true" when the stage is initalized // or to "false" when the stage is closed bool stageIsInit; //char * variable to hold the expected response from a read call char Response[40]; //after a call to GetPosition(), this char * variable will hold the x,y, // and z position of the stagee if the return is true. it will hold the // string, "Could not get stage position." if the return is false. char xyzPos[40]; //will hold the desired x position to move to as designated by a call to // SetPosition() and should range from -291 to -752 int setx; //will hold the desired y position to move to as designated by a call to // SetPosition() and should range from -4358 to -4654 int sety; //xmin, xmax, ymin, and ymax are all set during construction int xmin;//xmin = -752 int xmax;//xmax = -291 int ymin;//ymin = -4654 int ymax;//ymax = -4358 //the time allowed to pass (by checking the system clock) while looping to // look for a read string. int tTimeOut; //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. //USE: WriteStage() will check to see that the stage was first intialized. // it will then write the passed string to the comm port that was opened // during the call to Init(). while the write has not completed (known // because mResWrite, the result of the write, will be false) the function // will continuously check for completion. NOTE: the WriteCPort() command // will only return false if an error occurs. the return value of the // function should not be used to determine if the write was completed. // the return value should only be used to confirm that an error did or did // not occur. if the write command was executed, but the write was not // immediately completed, it will return false and the mResWrite variable // will remain false. if the write was immediately completed, the mResWrite // variable will be true. //RETURN VALUE: the return will be false if the stage has not been first // initialized or the WriteCPort() call returned false due to an error. the // return will be true if the stage is already intialized and te write is // successful. bool WriteStage(char *ToWrite); //REQUIREMENTS: a call to Init() should be made prior to this call for // proper execution, however, a failure will not occur otherwise. the // mBytesToRead parameter of the comm port should first be designated // by the command PortStage.mBytesToRead = num; where num is the number // of bytes to be read. the Response string should first be set to the // string that is expected to be read from the stage. if it is not first // set, the function will return false. //USE: ReadStage() will check to see that the stage was first intialized. // it will then read from the comm port that was opened during the call // to Init() in byte chunks of a size that was designated by the parameter // mBytesToRead. while the read has not completed (known because mResRead, // the result of the read, will be false) the function will continuously // check for completion. it will then compare the read string to the // expected Response string. NOTE: the ReadCPort() command will only // return false if an error occurs. the return value of the function should // not be used to determine if the read was completed. the return value // should only be used to confirm that an error did or did not occur. if // the read command was executed, but the read was not immediately // completed, it will return false and the mResRead variable will remain // false. if the read was immediately completed, the mResRead variable // will be true. //RETURN VALUE: the return will be false if the stage has not been first // initialized, the ReadCPort() call returned false due to an error, or // because the string read was not the same as the Response string. the // return will be true if the stage is already intialized and if what is // read is the same as the Response string bool ReadStage(); Reporter* r; }; #endif