From 52b57c96cdd404e889a7595680da87647ce653d2 Mon Sep 17 00:00:00 2001 From: Ferdi Franceschini Date: Tue, 30 May 2006 16:49:01 +1000 Subject: [PATCH] Added more doxygen documentation. Fixed compile errors. r1011 | ffr | 2006-05-30 16:49:01 +1000 (Tue, 30 May 2006) | 2 lines --- site_ansto/motor_dmc2280.c | 94 ++++++++++++++++++++++++++++++++------ 1 file changed, 80 insertions(+), 14 deletions(-) diff --git a/site_ansto/motor_dmc2280.c b/site_ansto/motor_dmc2280.c index e1c5d4b4..d14949dc 100644 --- a/site_ansto/motor_dmc2280.c +++ b/site_ansto/motor_dmc2280.c @@ -6,8 +6,14 @@ * Copyright: see file Copyright.txt * * Ferdi Franceschini November 2005 + * + * TODO + * - Add nopowersave optional parameter. + * - nopowersave = 0 (default) switch motor off after move. + * - nopowersave = 1 leave motor on after move. */ #include +/* ISO C Standard: 7.16 Boolean type and values */ #include #include #include @@ -19,6 +25,7 @@ #include #include #include + /* #include "splint/splint_fortify.h" #include "splint/splint_tclDecls.h" @@ -30,7 +37,7 @@ /* XXX Should this also free pData */ int readRS232(prs232 self, /*@out@*/void *data, /*@out@*/int *dataLen); void KillRS232(/*@only@*/ void *pData); -/*@only@*/ Tcl_GetVar2(Tcl_Interp *interp, char *name1, char *name2, int flags); +/*@only@*/ char *Tcl_GetVar2(Tcl_Interp *interp, char *name1, char *name2, int flags); /*@observer@*/ Tcl_Interp *InterpGetTcl(SicsInterp *pSics); /*@+incondefs@*/ /*----------------------------------------------------------------------- @@ -129,21 +136,33 @@ typedef struct __MoDriv { static int DMC2280Receive(pDMC2280Driv self, /*@out@*/ char *reply); -/* Return motor speed in steps/sec */ +/** \brief Convert motor speed from physical units to steps/sec + * \param self (r) provides access to the motor's data structure + * \param speed in physical units, eg mm/sec degrees/sec + * \return the speed in motor steps/sec + */ static int motSpeed(pDMC2280Driv self, float speed) { int motSpeed; - motSpeed = abs((int)(speed * self->stepsPerX + 0.5)); - return motSpeed; + motSpeed = abs((int)(speed * self->stepsPerX + 0.5)); + return motSpeed; } -/* Return motor acceleration in steps/sec^2 */ +/** \brief Convert motor acceleration from physical units to steps/sec^2 + * \param self (r) provides access to the motor's data structure + * \param acceleration in physical units, eg mm/sec^2 degrees/sec^2 + * \return the acceleration in motor steps/sec^2 + */ static int motAccel(pDMC2280Driv self, float accel) { int motAccel; motAccel = abs((int)(accel * self->stepsPerX + 0.5)); return motAccel; } -/* Return motor deceleration in steps/sec^2 */ +/** \brief Convert motor deceleration from physical units to steps/sec^2 + * \param self (r) provides access to the motor's data structure + * \param deceleration in physical units, eg mm/sec^2 degrees/sec^2 + * \return the deceleration in motor steps/sec^2 + */ static int motDecel(pDMC2280Driv self, float decel) { int motDecel; motDecel = abs((int)(decel * self->stepsPerX + 0.5)); @@ -224,7 +243,7 @@ static int DMC2280Send(pDMC2280Driv self, /*@unique@*/char *command) { return HWFault; snprintf(pError, ERRLEN, "DMC2280ERROR: Bad command '%s'", command); SCWrite(self->pCon, reply, eError); - SICSLogWrite(self->pCon, reply, eError); + SICSLogWrite(reply, eError); self->errorCode = BADCMD; return FAILURE; default: @@ -234,7 +253,16 @@ static int DMC2280Send(pDMC2280Driv self, /*@unique@*/char *command) { } } -/** \brief +/** \brief Gets output from the DMC2280, the abstract motor code should + * handle retries if the request times out. + * + * Note: The timeout for readRS232TillTerm is set by DMC2280Connect + * \param self (rw) provides access to the motor's data structure + * \param *reply (w) the data from the DMC2280. + * \return + * - SUCCESS + * - FAILURE + * \see SUCCESS FAILURE */ static int DMC2280Receive(pDMC2280Driv self, /*@out@*/char *reply) { int i, status, retries=20, dataLen=255; @@ -254,6 +282,7 @@ static int DMC2280Receive(pDMC2280Driv self, /*@out@*/char *reply) { } return FAILURE; } + /** \brief Reads motor position, implements the GetPosition * method in the MotorDriver interface. * @@ -715,7 +744,11 @@ static int DMC2280SetPar(void *pData, SConnection *pCon, return 0; } -/*--------------------------------------------------------------------*/ +/** \brief List the motor parameters to the client. + * \param self (r) provides access to the motor's data structure + * \param *name (r) name of motor. + * \param *pCon (r) connection object. + */ static void DMC2280List(void *self, char *name, SConnection *pCon){ char buffer[BUFFLEN]; @@ -739,7 +772,9 @@ static void DMC2280List(void *self, char *name, SConnection *pCon){ SCWrite(pCon, buffer, eStatus); return; } -/*---------------------------------------------------------------------*/ +/** \brief Free memory if motor is removed + * \param *pData (rw) provides access to the motor's data structure + */ static void KillDMC2280(void *pData){ pDMC2280Driv self = NULL; self = (pDMC2280Driv)pData; @@ -749,12 +784,18 @@ static void KillDMC2280(void *pData){ return; } /*@only@*/ prs232 createRS232(char *host, int iPort); -/*@null@ @only@*/ static prs232 DMC2280Connect(SConnection *pCon, char *buffer, int port) { +/** \brief Open a connection to the motor controller + * \param *pCon (r) connection object. + * \param *host (r) DMC2280 host address or name. + * \param port DMC2280 port number + * \return controller structure + */ +/*@null@ @only@*/ static prs232 DMC2280Connect(SConnection *pCon, char *host, int port) { prs232 controller=NULL; char pError[ERRLEN]; int usecTimeout = 50000; /* 50msec timeout */ - controller=createRS232(buffer,port); + controller=createRS232(host,port); if (controller==NULL) { snprintf(pError, ERRLEN, "ERROR: failed to create controller for %s at port %d", @@ -776,7 +817,17 @@ static void KillDMC2280(void *pData){ return controller; } -/* Get configuration parameter */ +/** \brief Get configuration parameter + * \param *pCon (r) connection object. + * \param *pTcl (r) Tcl interpreter + * \param *params Tcl array of configuration parameters + * \param *parName name of parameter to get from the array + * \param mustHave indicates optional or mandatory parameters\n + * possible values + * - _REQUIRED + * - _OPTIONAL + * \return a string with the parameter value + */ /*@observer@*/static char *getParam(SConnection *pCon, Tcl_Interp *pTcl, char *params, char *parName, int mustHave ) { char *pPtr=NULL; char pError[ERRLEN]; @@ -788,7 +839,22 @@ static void KillDMC2280(void *pData){ return pPtr; } -/*------------------------------------------------------------------*/ +/** \brief Create a driver for the DMC2280 Galil controller. + * + * This is called by the Motor configuration command in the + * SICS configuration file when you create a DMC2280 motor. + * + * Usage:\n + * Motor stth DMC2280 paramArray\n + * - stth is the motor name + * - DMC2280 is the motor type that will lead to calling this function. + * - paramArray is a Tcl array of the motor parameters. + * + * \param *pCon (r) connection object. + * \param *motor (r) motor name + * \param *params (r) configuration parameter array. + * \return a reference to Motordriver structure + */ /*@null@*/ MotorDriver *CreateDMC2280(SConnection *pCon, char *motor, char *params){ /*@keep@*/ pDMC2280Driv pNew = NULL; char *pPtr = NULL;