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

@@ -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 <stdlib.h>
+/* ISO C Standard:  7.16  Boolean type and values  <stdbool.h> */
 #include <stdbool.h>
 #include <math.h>
 #include <float.h>
@@ -19,6 +25,7 @@
 #include <rs232controller.h>
 #include <modriv.h>
 #include <dynstring.h>
+
 /*
 #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;