M19 orient spindle: document

configs/sim/orient.README

@@ -0,0 +1,20 @@
+The orient.ini configuration helps exploring
+the M19 command and its effect on various HAL pins.
+
+Note the ORIENT_OFFSET value in orient.ini which is
+added to the R word.
+
+
+run, and execute in MDI:
+
+M19
+M5
+M19 R45 P1
+S500 M3
+
+Acknowledge an spindle-orient request by
+pushing the spindle-is-oriented button.
+
+-mah
+
+

docs/man/man9/motion.9

@@ -203,6 +203,32 @@ Desired spindle speed in rotations per minute
 \fBmotion.spindle-speed-out-rps\fR OUT float
 Desired spindle speed in rotations per second
 
+.TP
+\fBspindle-orient-angle\fR OUT float    
+Desired spindle orientation for M19. Value of the M19 R word parameter plus the value of the [RS274NGC]ORIENT_OFFSET ini parameter.
+
+.TP
+\fBspindle-orient-fwd\fR OUT bit
+Desired spindle rotation direction for M19. Default 1. Set to zero if M19 P1 is given.
+
+.TP
+\fBspindle-orient\fR OUT bit
+Indicates start of spindle orient cycle. Set by M19. Cleared by any of M3,M4,M5. 
+If spindle-orient-fault is not zero during spindle-orient true, the M19 command fails with an error message.
+
+.TP
+\fBspindle-is-oriented\fR IN bit
+Acknowledge pin for spindle-orient. Completes orient cycle. If spindle-orient was true when spindle-is-oriented 
+was asserted, the spindle-orient pin is cleared and the spindle-locked pin is asserted. Also, the spindle-brake pin is asserted.
+
+.TP
+\fBspindle-orient-fault\fR IN s32
+Fault code input for orient cycle. Any value other than zero will cause the orient cycle to abort.
+
+.TP
+\fBspindle-locked\fR OUT bit
+Spindle orient complete pin. Cleared by any of M3,M4,M5. 
+
 .TP
 \fBmotion.teleop-mode\fR OUT bit
 

docs/src/config/emc2hal.txt

@@ -154,6 +154,65 @@ motion.tooloffset.x ... motion.tooloffset.w::
      it could come from the tool table (`G43` active), or it could
      come from the gcode (`G43.1` active)
 
+spindle-orient-angle::
+	(float,out) Desired spindle orientation for M19. Value of the
+	M19 R word parameter plus the value of the [RS274NGC]ORIENT_OFFSET ini parameter.
+
+spindle-orient-fwd::
+	(bit,out) Desired spindle rotation direction for M19. Default 1. Set to zero if M19 P1 is given.
+
+spindle-orient::
+	(out,bit)
+	Indicates start of spindle orient cycle. Set by M19. Cleared by any of M3,M4,M5. 
+	If spindle-orient-fault is not zero during spindle-orient
+	true, the M19 command fails with an error message.
+
+spindle-is-oriented::
+	(in, bit) Acknowledge pin for spindle-orient. Completes orient
+	cycle. If spindle-orient was true when spindle-is-oriented was
+	asserted, the spindle-orient pin is cleared and the
+	spindle-locked pin is asserted. Also, the spindle-brake pin is asserted.
+
+spindle-orient-fault::
+	(s32, in) Fault code input for orient cycle. Any value other
+	than zero  will cause the orient cycle to abort.
+
+spindle-lock::
+	(bit, out) Spindle orient complete pin. Cleared by any of M3,M4,M5. 
+
+==== HAL pin usage for M19 orient spindle
+
+Conceptually the spindle is in one of the following modes:
+
+ - rotation mode (the default)
+ - searching for desired orientation mode
+ - orienation complete mode.
+
+When an M19 is executed, the spindle changes to 'searching for desired
+orientation' , and the `spindle-orient` HAL pin is asserted.  The
+desired target position is specified by the `spindle-orient-angle` and
+`spindle-orient-fwd` pins and driven by the M19 R and P parameters.
+
+The HAL support logic is expected to react to `spindle-orient` by
+moving the spindle to the desired position. When this is complete, the
+HAL logic is expected to acknowledge this by asserting the
+`spindle-is-oriented` pin.
+
+Motion then acknowledges this by deasserting the `spindle-orient` pin
+and asserts the `spindle-locked` pin to indicate 'orientation
+complete' mode. It also raises the `spindle-brake` pin. The spindle now
+is in 'orientation complete' mode.
+
+If, during `spindle-orient` being true, and `spindle-is-oriented` not
+yet asserted the `spindle-orient-fault` pin has a value other than
+zero, the M19 command is aborted, a message including the fault code
+is displayed, and the motion queue is flushed. The spindle reverts to
+rotation mode.
+
+Also, any of the M3,M4 or M5 commands cancel either 'searching for
+desired orientation' or 'orientation complete' mode. This is indicated
+by deasserting both the `spindle-orient` and `spindle-locked` pins.
+
 === Parameters
 
 Many of these parameters serve as debugging aids, and are subject to

docs/src/config/ini_config.txt

@@ -482,6 +482,11 @@ PARAMETER_FILE = myfile.var::
     file which contains the parameters used by the interpreter (saved
     between runs). 
 
+ORIENT_OFFSET = 0::
+    (((ORIENT OFFSET ))) A float value added to the R word parameter
+    of an <<sec:M19,M19 Orient Spindle> operation. Used to define an arbitrary
+    zero position regardless of encoder mount orientation.
+
 RS274NGC_STARTUP_CODE = G01 G17 G20 G40 G49 G64.1 P0.001 G80 G90 G92 G94 G97 G98::
     (((RS274NGC STARTUP CODE))) A string of NC codes that the interpreter
     is initialized with. This is not a substitute for specifying modal

docs/src/gcode/main.txt

@@ -1762,6 +1762,30 @@ To turn all coolant off, program `M9`.
 It is always OK to use any of these commands, 
 regardless of what coolant is on or off.
 
+== M19 Orient Spindle [[sec:M19]]
+(((M19 Orient Spindle)))
+
+To start spindle orientation mode, program `M19`.
+
+ M19 R- P-
+
+ - The optional R- word specifies the desired angle in degrees (default 0). 
+ - The optional P- word specifies the rotation direction (default clockwise, 
+   a value of 1 specifies counterclockwise rotation). 
+
+M19 cancels spindle rotation mode and enters spindle orientation
+mode. M19 turns off the spindle, unlocks the spindle brake and then starts the
+orientation HAL pin protocol. See the motion manpage for the pin
+description.
+
+Any M3,M4,M5 spindle command will cancel spindle orientation mode and
+switch back to rotation mode, which is the default.
+
+The `[RS274NGC]ORIENT_OFFSET` value from the ini file is added to the
+R word to define an aribtrary zero position.
+
+M19 is a modal group 7 command (same as M3,M4,M5). 
+
 == Overrides [[sec:Overrides]]
 
 === M48, M49 Override Control[[sub:M48-Both-Override]][[sub:M49-Neither-Override]](((M48, M49 Override Control)))

docs/src/gcode/overview.txt

@@ -798,7 +798,7 @@ being in effect. The modal groups are shown in Table
 |Lathe Diameter Mode          | G7, G8
 |Stopping                     | M0, M1, M2, M30, M60
 |Tool Change                  | M6 Tn
-|Spindle                      | M3, M4, M5
+|Spindle                      | M3, M4, M5, M19
 |Coolant                      | (M7 M8 can both be on), M9
 |Override Switches            | M48, M49
 |Flow Control                 | O-