- made fixes to hkl

- Introduced a help system
- introduced a module for handling automatic updates of files during
  long measurements
- Added a circular buffer and handling facilities to varlog
- Upgraded documentation


SKIPPED:
	psi/faverage.h
	psi/nxamor.tex
	psi/pimotor.h
	psi/pimotor.tex

doc/user/motor.htm

@@ -47,8 +47,83 @@ or equal to zero for the motor being movable.
 <li> <b> Precision </b> denotes the precision to expect from the motor  in positioning. Can usually only be set by managers.
 <li> <b> AccessCode </b> specifies the level of user privilege  necessary to  operate the motor. Some  motors are for  adjustment only and can be harmful to move once the  adjustment has been done. Others must be moved for the experiment. Values  are 0 - 3 for internal, manager, user and spy. This parameter can  only be changed by managers.
 <li> <b> Sign </b> reverses the operating sense of the motor.  
- For cases where electricians and not physicists have defined the  operating sense of the motor. Usually a parameter not to be changed  by ordinary users.
+ For cases where electricians and not physicists have defined the
+ operating sense of the motor. Usually a parameter not to be changed
+ by ordinary users.
+<li><b> failafter </b>This is the number of consecutive failures of
+positioning operations this motor allows before it thinks that
+something is really broken and aborts the experiment.
+<li><b> maxretry </b>When a motor finishes driving, SICS checks if the
+desired position was reached. If the position read back from the motor
+is not within  precision to the desired value, the motor is
+restarted. This is done at max maxretry times. After maxretry retries,
+the motor throws an error.
+<li></b> ignorefault </b>If this is bigger then 0, positioning faults
+from the motor will be ignored. 
 </ul>
 <p>
+<h2>Motor Error Handling Concepts</h2>
+<p>
+As mechanical components motors are prone to errors. SICS knows about
+two different classes of motor errors:
+<dl>
+<dt>HWFault
+<dd>This is when there is a problem communicating with the motor, a
+limit is violated etc. SICS assumes that such errors are so grave that
+no fix is possible. If such a HWFault is detected a configurable
+interrupt (see parameter InterruptMode) is set which can be used by
+upper level code to act upon the problem.
+<dt>HWPosFault
+<dd>This is a positioning failure, i.e. The motor did not reach the
+desired position. Such a positioning problem can come from two
+sources:
+<ul>
+<li>The positioning problem is reported by the motor driver. SICS then
+assumes that the driver has done something to solve the problem and
+promotes this problem to a HWFault.
+<li>The motor driver reported no error and SICS figures out by itself,
+that the desired position has not been reached. SICS thinks that this
+is the case if the difference between the desired position and the
+position read from the motor controller is greater then the parameter
+precision. If SICS detects such a problem it tries to reposition the
+motor. This is done for the number of times specified through the
+parameter maxretries. If the position has not been reached after
+maxretries repositionings, a HWFault is assumed.   
+</ul>
+</dl>
+In any case lots of warnings and infos are printed. 
+</p>
+<p>
+If SICS tries to drive an axis which is for some reason broken to
+often hardware damage may occur (and HAS occurred!). Now, SICS has no
+means to detect if the mispositioning of a motor is due to a concrete
+block in the path of the instrument or any other reason. What SICS can
+do though is to count how often a motor mispositions in
+sequence. This means SICS counts mispositionings if it cannot drive a
+motor, if the motor is driven succesfully, the count is cleared. If
+the count of mispositionings becomes higher then the parameter
+failafter, SICS thinks that there is something really, really wrong
+and aborts the measurement and prints an error message containing the
+string: MOTOR ALARM.
+</p>
+<p>
+There are some common pitfalls with this scheme:
+<dl>
+<dt>You want upper level code to be signalled when your critical motor
+fails.
+<dd>Solution: set the parameter interruptmode to something useful and
+check for the interrupt in upper level code.
+<dt>SICS falsly reports mispositionings.
+<dd>Solution: increase the precision parameter.
+<dt>You know that a motor is broken, you cannot fix it, but you want
+to measure anyway.
+<dd>Solution: increase the precision parameter, if SICS finds the
+positioning problem, increase maxretries, increase the failafter
+parameter. In the worst case set the ignorefault parameter to greater
+0, this will prevent all motor alarms. 
+</dl>
+</p>
 </body>
 </html>
+
+