:lang: en
:toc:

[[cha:iov2]]
= I/O Control V2

// Custom lang highlight
// must come after the doc title, to work around a bug in asciidoc 8.6.6
:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

== Description

I/O control handles I/O tasks like coolant, toolchange, e-stop and lube. The
signals are turned on and off in userspace with G-code or in the case of e-stop
in HAL.

I/O Control V2 adds more toolchanger support for communication with the
toolchanger.

* LinuxCNC originated abort and toolchanger fault: iocontrol reliably abort a
  change operation in progress (tool-change asserted). A toolchanger may at any
  time signal a fault which will abort the next M6. For instance, a toolchanger
  finding an empty pocket during a prepare operation should be able to signal a
  fault to iocontrol, and iocontrol act appropriately when the M6 change
  operation is executed.

* Communicate abort/fault cause : let iocontrol know why toolchanger caused
  an fault, and why iocontrol aborted. This is for UI purposes. It would be a
  candidate for a #5xxx parameter, and selective display in the UI.

* No race conditions between iocontrol and toolchanger: the protocol between
  iocontrol and toolchanger must be unambiguous with respect to which operation
  is signalled, and if a change operation is aborted or complete.

* Consistent view of state: Both parties must have a consistent view of the
  state at any point in time with respect to aborted versus completed, and tool
  number and pocket.

* Handshaked signaling an abort/fault: an abort signaled by LinuxCNC to the
  toolchanger, and a fault indicated from the toolchanger is handshaked to
  assure reliable signaling, and optionally force lock-step behaviour.
  Handshaking is optional and can be jumpered in HAL if not needed.

* Backwards compatibility: A toolchanger ignoring the iocontrol emc-abort line
  and sticking to old handling will "continue to work" (subject to race condition) 

If you have strict timing requirements or simply need more I/O, consider using
the realtime I/O provided by link:../man/man9/motion.9.html[motion] instead.

== Usage

INI file options:

.[EMCIO] section
PROTOCOL_VERSION = 2 :: Defaults to 2. Setting to 1 will emulate old iocontrol behaviour. 

EMCIO = iov2 -support-start-change :: You need to explicitly enable the start-change protocol by adding the 
  -support-start-change option; otherwise the start-change pin remains
  low and   start-change-ack is ignored. The reason for this is better
  backwards compatibility.

.[TASK] section
IO_ERROR :: Printf-style template for operator error display (negative
  toolchanger fault codes) . No quoting needed. Example: `IO_ERROR = Toolchanger
  fault %d`. Default: toolchanger error %d.

.[EMC] section +
DEBUG :: To get a (quite detailed) trace, set either the RCS debugging flag
  (0x00000200) to turn on RCS debugging messages all over LinuxCNC or use the
  new iocontrol debugging bit (0x00001000) only for iov2 messages. 

== Pins

* iocontrol.0.coolant-flood (Bit, Out) TRUE when flood coolant is requested

* iocontrol.0.coolant-mist (Bit, Out) TRUE when mist coolant is requested

* iocontrol.0.emc-enable-in (Bit, In) Should be driven FALSE when an external
  estop condition exists.

* iocontrol.0.lube (Bit, Out) TRUE when lube is requested. This pin gets driven
  TRUE when the controller comes out of E-stop, and when the "Lube On" command
  gets sent to the controller. It gets driven FALSE when the controller goes
  into E-stop, and when the "Lube Off" command gets sent to the controller.

* iocontrol.0.lube_level (Bit, In) Should be driven FALSE when lubrication tank
  is empty.

* iocontrol.0.tool-change (Bit, Out) TRUE when a tool change is requested

* iocontrol.0.tool-changed (Bit, In) Should be driven TRUE when a tool change is
  completed.

* iocontrol.0.tool-number (s32, Out) Current tool number

* iocontrol.0.tool-prep-number (s32, Out) The number of the next tool, from the
  RS274NGC T-word

* iocontrol.0.tool-prep-pocket (s32, Out) This is the pocket number (location in
  the tool storage mechanism) of the tool requested by the most recent T-word.

* iocontrol.0.tool-prepare (Bit, Out) TRUE when a Tn tool prepare is requested

* iocontrol.0.tool-prepared (Bit, In) Should be driven TRUE when a tool prepare 
  is completed.

* iocontrol.0.user-enable-out (Bit, Out) FALSE when an internal estop condition
  exists

* iocontrol.0.user-request-enable (Bit, Out) TRUE when the user has requested 
  that estop be cleared

Additional pins added by I/O Control V2

* emc-abort: (Bit, Out) signals emc-originated abort to toolchanger.

* emc-abort-ack: (Bit, In) Acknowledge line from toolchanger for previous signal,
  or jumpered to abort-tool-change if not used in toolchanger. NB: after
  signaling an emc-abort, iov2 will block until emc-abort-ack is raised.

* emc-reason: (S32, Out) convey cause for EMC-originated abort to toolchanger.
  Usage: UI informational. Valid during emc-abort TRUE.

* start-change: (Bit, Out) asserted at the very beginning of an M6 operation,
  before any spindle-off, quill-up, or move-to-toolchange-position oeprations
  are executed.

* start-change-ack: (Bit, In) acknowledgment line for start-change. 

* toolchanger-fault: (Bit, In) toolchanger signals fault. This line is
  contionuously monitored. A fault toggles a flag in iocontrol which is
  reflected in the toolchanger-faulted pin.

* toolchanger-fault-ack: (Bit, Out) handshake line for above signal. will be set
  by iov2 after above fault line TRUE is recognized and deasserted when
  toolchanger-fault drops. Toolchanger is free to interpret the ack; reading the
  -ack lines assures fault has been received and acted upon.

* toolchanger-reason: (S32, In) convey reason code for toolchanger-originated
  fault to iov2. Usage: signal whether to continue or abort the program, plus UI
  informational if negative. Read during toolchanger-fault TRUE. Non-zero values
  will cause an Axis operator operator message or error message, see below. 

* toolchanger-faulted: (Bit, Out) signals toolchanger-notify line has toggled and
  toolchanger-reason-code was in the fault range. Next M6 will abort.

* toolchanger-clear-fault: (Bit, In) resets TC fault condition. Deasserts
  toolchanger-faulted if toolchanger-notify is line FALSE. Usage: UI - e.g.
  clear fault condition button.

== Parameters

* iocontrol.0.tool-prep-index (s32, RO) IO's internal array index of the prepped
  tool requested by the most recent T-word. 0 if no tool is prepped. On random
  toolchanger machines this is tool's pocket number (ie, the same as the
  tool-prep-pocket pin), on non-random toolchanger machines this is a small
  integer corresponding to the tool's location in the internal representation of
  the tool table. This parameter returns to 0 after a successful tool change M6.

== Communications

If LinuxCNC signals an abort for whatever reason, this is reflected in the
emc-abort and emc-reason pins. The toolchanger is expected to acknowledge the
emc-abort pin by raising the emc-abort-ack pin - iov2 will block until this is
done. If you do not need the abort handshake feature, jumper them as follows:

[source,{hal}]
----
 net emc-abort-ack iocontrol.0.emc-abort iocontrol.0.emc-abort-ack 
----

The emc-reason pin is considered valid during emc-abort being TRUE.

The reason codes are as follows for LinuxCNC internally generated aborts
(see emc.hh ca line 321):

*	EMC_ABORT_TASK_EXEC_ERROR = 1,
*	EMC_ABORT_AUX_ESTOP = 2,
*	EMC_ABORT_MOTION_OR_IO_RCS_ERROR = 3,
*	EMC_ABORT_TASK_STATE_OFF = 4,
*	EMC_ABORT_TASK_STATE_ESTOP_RESET = 5,
*	EMC_ABORT_TASK_STATE_ESTOP = 6,
*	EMC_ABORT_TASK_STATE_NOT_ON = 7,
*	EMC_ABORT_TASK_ABORT = 8,
*	EMC_ABORT_USER = 100 

iov2 adds one more code, namely EMC_ABORT_BY_TOOLCHANGER_FAULT = 101 which is
signaled when an M6 aborts due to the toolchanger-faulted pin being TRUE.

To signal toolchanger faults to LinuxCNC, wire the toolchanger-fault pin,
and optionally the toolchanger-reason and toolchanger-ack pins.

The toolchanger-fault triggers the fault condition, which is reflected in the
toolchanger-faulted pin. This condition can be cleared by asserting the
toolchanger-clear-fault pin, provided the toolchanger-fault pin is FALSE.

The value of the toolchanger-reason pin is used as follows:

* toolchanger-reason > 0 : The toolchange process is not completed and the
  program continues, however parameter #5060 is set to 1.0 to indicate the fault.
  Parameter #5601 contains the value of the toolchanger-reason pin.
** toolchanger-reason = 0 : the program is aborted
** toolchanger-reason < 0 : the program is aborted and an operator error
   message is displayed by using the IO_ERROR template. 

The usage of the toolchanger-fault-ack pin is optional. It will become TRUE when
toolchanger-fault is raised and the toolchanger-reason pin has been read by iov2. 

// vim: set syntax=asciidoc:
