path: root/docs/src/remap/structure.txt

= Extending LinuxCNC

:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}
:ngc: {basebackend@docbook:'':ngc}

== Introduction: Extending the RS274NGC Interpreter by Remapping Codes


=== A Definition: Remapping Codes

By 'remapping codes' we mean one of the following:

. define the semantics of new - that is, currently unallocated - M- or G-codes
. redefine the semantics of a - currently limited - set of existing codes.

=== Why would you want to extend the RS274NGC Interpreter?

The set of codes (M,G,T,S,F) currently understood by the RS274NGC
interpreter is fixed and cannot be extended by configuration options.

In particular, some of these codes implement a fixed sequence of steps
to be executed. While some of these, like M6, can be moderately
configured by activating or skipping some of these steps through ini
file options, overall the behaviour is fairly rigid. So - if your
are happy with this situation, then this manual section is not for you.

In many cases, this means that supporting a non 'out of the box'
configuration or machine is either cumbersome or impossible, or
requires resorting to changes at the 'C/C\+\+' language level. The latter
is unpopular for good reasons - changing internals requires in-depth
understanding of interpreter internals, and moreover brings its own
set of support issues. While it is conceivable that certain patches
might make their way into the main LinuxCNC distribution, the result of
this approach is a hodge-podge of special-case solutions.

A good example for this deficiency is tool change support in LinuxCNC:
while random toolchangers are well supported, it is next to impossible
to reasonably define a configuration for a manual-toolchange machine
with, for example, an automatic tool length offset switch being
visited after a toolchange, and offsets set accordingly. Also, while a
patch for a very specific rack toolchanger exists, it has not found
its way back into the main code base.

However, many of these things may be fixed by using an O-word
procedure instead of a builtin code - whenever the - insufficient -
builtin code is to be executed, call the O-word procedure
instead. While possible, it is cumbersome - it requires source-editing
of NGC programs, replacing all calls to the deficient code by a an
O-word procedure call.

In it's simplest form a remapped code isnt much more than a
spontaneous call to an O-word procedure. This happens behind the scenes
- the procedure is visible at the configuration level, but not at the
NGC program level.

Generally, the behaviour of a remapped code may be defined in the following ways:

- you define a O-word subroutine which implements the desired behaviour
- alternatively, you may employ a Python function which extends the interpreter's behaviour.

==== How to glue things together
M- and G-codes, and O-words subroutine calls have some fairly different syntax.

O-word procedures, for example, take positional parameters
with a specific syntax like so:

[source,{ngc}]
---------------------------------------------------------------------
o<test> call [1.234] [4.65]
---------------------------------------------------------------------

whereas M- or G-codes typically take required or optional 'word'
parameters. For istance, G76 (threading) requires the P,Z,I,J and K
words, and optionally takes the R,Q,H, E and L words.

So it isnt simply enough to say 'whenever you encounter code X, please
call procedure Y' - at least some checking and conversion of paramters
needs to happen. This calls for some 'glue code' between the new code,
and its corresponding NGC procedure to execute before passing control
to the NGC procedure.

This glue code is impossible to write as an O-word procedure itself
since the RS274NGC language lacks the introspective capabilities and
access into interpreter internal data structures to achieve the
required effect. Doing the glue code in - again - 'C/C\+\+' would be an
inflexible and therefore unsatisfactory solution.

==== How Embedded Python fits in

To make a simple situation easy and a complex situation solvable, the
glue issue is addressed as follows:

- for simple situations, a built-in glue procedure (`argspec`) covers most
common parameter passing requirements
- for remapping T,M6,M61,S,F there is some standard Python glue which should
cover most situations, see <<sec:Standard-glue,Standard Glue>>
- for more complex situations, one can write your own Python glue to implement new behaviour.

Embedded Python functions in the Interpreter started out as glue code,
but turned out very useful well beyond that. Users familiar with
Python will likely find it easier to write remapped codes, glue,
O-word procedures etc in pure Python, without resorting to the
somewhat cumbersome RS274NGC language at all.

==== A Word on Embedded Python

Many people are familiar with 'extending' the Python interpreter by
'C/C\+\+' modules, and this is heavily used in LinuxCNC to access Task,
HAL and and Interpreter internals from Python scripts. 'Extending
Python' basically means: your Python script executes as 'it is in the
driver seat', and may access non-Python code by importing and using
extension modules written in 'C/C\+\+'. Examples for this are the LinuxCNC
`hal`, `gcode` and `emc` modules.

Embedded Python is a bit different and and less commonly known: The
main program is written in C/C++ and may use Python like a
subroutine. This is powerful extension mechanism and the basis for the
'scripting extensions' found in many successful software
packages. Embedded Python code may access 'C/C\+\+' variables and
functions through a similar extension module method.

==  Getting started [[remap:getting-started]]

Defining a code involves the following steps:

- pick a code - either use an unallocated code, or redefine an existing code
- deciding how parameters are handled
- decide if and how results are handled
- decide about the execution sequencing.

=== Picking a code

Note that currently only a few existing codes may be redefined,
whereas there are many 'free' codes which might be made available by
remapping. When developing a redefined existing code, it might be a
good idea to start with an unallocated G- or M-code so both the
existing and new behaviour can be exercised. When done, redefine the
existing code to use your remapping setup.

- the current set of unused M-codes open to user definition can be found
<<remap:unallocated-m-codes,here>>,
- unallocated G-codes are listed <<remap:unallocated-g-codes,here>>.
- Existing codes which may be remapped are listed <<remap:remappable-codes,here>>.


===  Parameter handling [[remap:parameter-handling]]

Let's assume the new code will be defined by an NGC procedure, and needs
some parameters, some of which might be required, others might be
optional. We have the following options to feed values to the
procedure:

// . <<remap:extracting-words,extracting words from the current block>>
. extracting words from the current block  and pass them to the
  procedure as parameters (like `X22.34` or `P47`)
//. <<remap:referto-inifile-variables, referring to ini file
//variables>>
. referring to ini file variables
. referring to global variables (like `#2200 = 47.11` or
   `#<_global_param> = 315.2`

The first method is preferred for parameters of dynamic nature, , like
positions. You need to define which words on the current block have
any meaning for your new code, and specify how that is passed to the
NGC procedure. Any easy way is to use the
<<remap:argspec-parameter,argspec statement>>. A custom prolog might
provide better error messages.

Using to ini file variables is most useful for referring to setup
information for your machine, for instance a fixed position like a
tool-length sensor position. The advantage of this method is that the
parameters are fixed for your configuration regardless which NGC file
you're currently executing.

Referring to global variables is always possible, but they are easily
overlooked.

Note there's a limited supply of words which may be used as
parameters, so one might need to fall back to the second and third
methods if many parameters are needed.

=== Handling results [[remap:handling-results]]

Your new code might succeed or fail, for instance if passed an invalid
parameter combination. Or you might choose to 'just execute' the
procedure and disregard results, in which case there isnt much work to do.

Epilog handlers help in processing results of remap procedures - see
the reference section.

=== Execution sequencing [[remap:execution-sequencingg]]
Excecutable G-code words are classified into <<sec:Modal-Groups,modal
groups>>, which also defines their relative execution behaviour.

If a  G-code block  contains several executable words on a line, these
words are executed in a predefined <<sec:Order-of-Execution, order of
execution>>, not in the order they appear in block.

When you define a new executable code, the interpreter does not yet
know where your code fits into this scheme. For this
reason, you need to choose an appropriate modal group for your code to
execute in.

=== An minimal example remapped code

To give you an idea how the pieces fit together, let's explore a
fairly minimal but complete remapped code definition. We choose an
unallocated M-code and add the following option to the ini file:

[source,{ini}]
---------------------------------------------------------------------
[RS274NGC]
REMAP=M400  modalgroup=10 argspec=Pq ngc=myprocedure
---------------------------------------------------------------------

In a nutshell, this means:

- The `M400` code takes a required parameter `P` and an optional
  parameter `Q`. Other words in the current block are ignored with
  respect to the `M400` code. If the `P` word is not present, fail
  execution with an error.

- when an `M400` code is encountered, execute `myprocedure.ngc`  along
the other <<sec:Modal-Groups,modal group>> 10 M-codes as per
<<sec:Order-of-Execution, order of execution>>.

- the value of `P`, and `Q` are available in the procedure as local
   named parameters. The may be referred to  as `#<P>` and `#<Q>`. The
   procedure may test whether the `Q` word was present with the
   <<EXISTS-Function,`EXISTS`>> builtin function.

The file `myprocedure.ngc` is expected to exists in the `[DISPLAY]NC_FILES` or
`[RS274NGC]SUBROUTINE_PATH` directory.

A detailed discussion of REMAP parameters is found in the reference
section below.



== Configuring Remapping



=== The REMAP statement
To remap a code, define it using the `REMAP` option in
`RS274NG` section of your ini file. Use one `REMAP` line per remapped code.

The syntax of the `REMAP` is:

`REMAP=`'<code>' '<options>'::
    where '<code>' may be one of `T`,`M6`,`M61`,`S`,`F` (existing codes) or any of the
    unallocated <<remap:unallocated-m-codes,M-codes>> or <<remap:unallocated-g-codes,G-codes>>.

It is an error to omit the '<code>' parameter.

The options of the REMAP statement are separated by whitespace. The options are
keyword-value pairs and currently are:

`modalgroup=`'<modal group>'::
        G-codes;; the only currently supported modal group is 1, which
        is also the default value if no group is given. Group 1 means
        'execute alongside other G-codes'.

	M-codes;; currently supported modal groups are:
        5,6,7,8,9,10. If no modalgroup is give, it defaults to 10
        ('execute after all other words in the block').

	T,S,F;; for these the modal group is fixed and any
	`modalgroup=` option is ignored.

`argspec=`'<argspec>'::
	See <<remap:argspec-parameter, description of the argspec
	parameter options>>. Optional.

`ngc=`'<ngc_basename>'::
	 Basename of an O-word subroutine file name. Do not specify an
	 .ngc extension. Searched for in the directories specified in
	 the directory specified in `[DISPLAY]PROGRAM_PREFIX`, then in
	 `[RS274NGC]SUBROUTINE_PATH`. Mutually exclusive with
	 `python=`. It is an error to omit both `ngc=` and  `python=`.

`python=`'<Python function name>'::
	Instead of calling an ngc O-word procedure call a Python
	function. The function is expected to be defined in the
	`module_basename.oword`
	module. Mutually exclusive with `ngc=`.

`prolog=`'<Python function name>'::
	Before executing an ngc procedure, call this Python function.
	The function is expected to be defined in the
	`module_basename.remap`
	module. Optional.

`epilog=`'<Python function name>'::
	After executing an ngc procedure, call this Python function.
	The function is expected to be defined in the
	`module_basename.remap`
	module. Optional.

The `python`, `prolog` and `epilog` options require the Python
Interpreter plugin to be  <<remap:embedded-Python,configured>>, and
appropriate Python functions to be defined there so they can be
referred to with these options.

The syntax for defining a new code, and redefining an existing code is
identical.

=== Useful REMAP option combinations

Note that while many combinations of argspec options are possible, not
all of them make sense. The following combinations are useful idioms:

`argspec=`'<words>' `ngc=`'<procname>' `modalgroup=`'<group>'::
    The recommended way to call an NGC procedure with a standard argspec parameter
    conversion. Used if argspec is good enough. Note it's not good
    enough for remapping the Tx and M6/M61 toolchange codes.

`prolog=`'<pythonprolog>' `ngc=`'<procname>' `epilog=`'<pythonepilog>' `modalgroup=`'<group>'::
    Call a Python prolog function to take any preliminary steps, then call the NGC
    procedure. When done, call the Python epilog function to do any
    cleanup or result extraction work which cannot be handled in G-code.
    The most flexible way of remapping a code to an NGC procedure,
    since almost all of the Interpreter internal variables, and some
    internal functions may be accessed from the prolog and epilog
    handlers. Also, a longer rope to hang yourselves.

`python=`'<pythonfunction>' `modalgroup=`'<group>'::
    Directly call to a Python function without any argument conversion.
    The most powerful way of remapping a code and going straight to
    Python. Use this if you dont need an NGC procedure, or NGC is
    just getting in your way.

`argspec=`'<words>' `python=`'<pythonfunction>' `modalgroup=`'<group>'::
    Convert the argspec words and pass them to a Python function as
    keyword argument dictionary. Use it when you're too lazy to
    investigate words passed on the block yourself.

Note that if all you want to achieve is to call some Python code from
G-code, there is the somewhat easier way of
<<remap:Python-O-word-procs, calling Python functions like O-word procedures>>.

=== The 'argspec' parameter [[remap:argspec-parameter]]


The argument specification (keyword `argspec`) describes required and
optional words to be passed to an ngc procedure, as well as optional
precondtions for that code to execute.

An argspec consists of 0 or more  characters of the class
 `[@A-KMNP-Za-kmnp-z^>]` . It can by empty (like `argspec=`).

An empty argspec, or no argspec argument at all implies the remapped
code does not receive  any parameters from the block. It will ignore
any extra parameters present.

Note that RS274NGC rules still apply - for instance you may use axis
words (eg X,Y,Z) only in the context of a G-code.

`ABCDEFGHIJKMPQRSTUVWXYZ`::
	Defines a required word parameter: an uppercase letter specifies that
	the corresponding word *must*
	be present in the current block. The word`s value will be
	passeed as a local named parameter with a corresponding name.
	If the `@` character is
	present in the argspec, it will be passed as positional
	parameter, see below.

`abcdefghijkmpqrstuvwxyz`::
	Defines an optional word parameter: a lowercase letter specifies that
	the corresponding word *may* be present in the current block.
	If the word is present, the word's value will be
	passed as a local named parameter. If the `@` character is
	present in the argspec, it will be passed as positional
	parameter, see below.

`@`::
	The `@` (at-sign) tells argspec to pass words as positional
	parameters, in the order defined following the `@`
	option. Note that when using positional parameter passing,
	a procedure cannot tell whether a word was present or not, see
	example below.

TIP: this helps with packaging existing NGC procedures as remapped
codes. Existing procedures do expect positional parameters. With the
`@` option, you can avoid rewriting them to refer to local named
parameters.


`^`::
	The `^` (caret) character specifies that the current
	spindle speed must be greater than zero (spindle running),
	otherwise the code fails with an appropriate error message.

`>`::
	The `>` (greater-than) character specifies that the current
	feed must be greater than zero, otherwise the code fails with
	an appropriate error message.

`n`::
	The `n` (greater-than) character specifies to pass the current
	line number in the `n`local named parameter.

By default, parameters are passed  as local named parameter to an NGC
procedure. These local parameters appear as 'already set' when the
procedure starts executing, which is different from existing semantics
(local variables start out with value 0.0 and need to be explicitly
assigned a value).

Optional word parameters may be tested for presence by the `EXISTS(#<word>)` idiom.

==== Example for named parameter passing to NGC procedures

Assume the code is defined as

`REMAP=M400  modalgroup=10 argspec=Pq ngc=m400`

and `m400.ngc` looks as follows:

[source,{ngc}]
----------------------------------------------------------------------------------
o<m400> sub
(P is required since it's uppercase in the argspec)
(debug, P word=#<P>)
(the q argspec is optional since its lowercase in the argspec. Use as follows:)
o100 if [EXISTS[#<q>]]
    (debug, Q word set: #<q>)
o100 endif
o<m400> endsub
M2
----------------------------------------------------------------------------------

- executing `M400` will fail with the message
  `user-defined M400: missing: P`
- executing `M400 P123` will display `P word=123.000000`
- executing `M400 P123 Q456` will display `P word=123.000000` and `Q word set: 456.000000`

==== Example for positional parameter passing to NGC procedures

Assume the code is defined as

`REMAP=M410  modalgroup=10 argspec=@PQr ngc=m410`

and `m410.ngc` looks as follows:

[source,{ngc}]
----------------------------------------------------------------------------------
o<m410> sub
(debug, [1]=#1 [2]=#2 [3]=#3)
o<m410> endsub
M2
----------------------------------------------------------------------------------

- executing `M410 P10` will display `m410.ngc: [1]=10.000000 [2]=0.000000`
- executing `M410 P10 Q20` will display `m410.ngc: [1]=10.000000 [2]=20.000000`

NB: you lose the capability to distinguish more than one optional
parameter word, and you cannot tell whether an optional parameter was
present but had the value 0, or was not present at all.

==== Simple example for named parameter passing to a Python function

It's possible to define new codes 'without' any NGC procedure. Here's
a simple first example, a more complex one can be found in the next
section.

Assume the code is defined as

`REMAP=G88.6 modalgroup=1  argspec=XYZp  python=g886`

This instructs the interpreter to execute the Python function `g886`
in the `module_basename.remap` module
which might look like so:

[source,python]
---------------------------------------------------------------------
from interpreter import INTERP_OK
from emccanon import MESSAGE

def g886(self, **words):
    for key in words:
        MESSAGE("word '%s' = %f" % (key, words[key]))
    if words.has_key('p'):
        MESSAGE("the P word was present")
    MESSAGE("comment on this line: '%s'" % (self.blocks[self.remap_level].comment))
    return INTERP_OK
---------------------------------------------------------------------
Try this with out with:
  g88.6 x1 y2 z3
  g88.6 x1 y2 z3 p33 (a comment here)

You'll notice the gradual introduction of the embedded Python
environment - see <<sec:Programming-Embedded-Python,here>> for details.  Note that
with Python remapping functions, it make no sense to have Python
prolog or epilog functions since it's executing a Python function in
the first place.

====  Advanced example: Remapped codes in pure Python

The `interpreter` and `emccanon` modules expose most of the Interpreter
and some Canon internals, so many things which  so far required coding in
'C/C\+\+' can be now be done in Python.

The following example is based on the `nc_files/involute.py` script -
but canned as a G-code with some parameter extraction and checking. It
also demonstrates calling the interpreter recursively (see `self.execute()`).

Assuming a definition like so (NB: this does not use argspec):

`REMAP=G88.1 modalgroup=1  py=involute`

The `involute` function in `python/remap.py` listed below does all
word extraction from the current block directly. Note that interpreter
errors can be translated to Python exceptions. Remember this is
'readahead time' - execution time errors cannot be trapped this way.

[source,python]
---------------------------------------------------------------------
import sys
import traceback
from math import sin,cos

from interpreter import *
from emccanon import MESSAGE
from util import lineno, call_pydevd
# raises InterpreterException if execute() or read() fails
throw_exceptions = 1


def involute(self, **words):
    """ remap function with raw access to Interpreter internals """

    if self.debugmask & 0x20000000: call_pydevd() # USER2 debug flag

    if equal(self.feed_rate,0.0):
        return "feedrate > 0 required"

    if equal(self.speed,0.0):
        return "spindle speed > 0 required"

    plunge = 0.1 # if Z word was given, plunge - with reduced feed

    # inspect controlling block for relevant words
    c = self.blocks[self.remap_level]
    x0 = c.x_number if c.x_flag else 0
    y0 = c.y_number if c.y_flag else 0
    a  = c.p_number if c.p_flag else 10
    old_z = self.current_z

    if self.debugmask & 0x10000000:
        print "x0=%f y0=%f a=%f old_z=%f" % (x0,y0,a,old_z)

    try:
        #self.execute("G3456")  # would raise InterpreterException
        self.execute("G21",lineno())
        self.execute("G64 P0.001",lineno())
        self.execute("G0 X%f Y%f" % (x0,y0),lineno())

        if c.z_flag:
            feed = self.feed_rate
            self.execute("F%f G1 Z%f" % (feed * plunge, c.z_number),lineno())
            self.execute("F%f" % (feed),lineno())

        for i in range(100):
            t = i/10.
            x = x0 + a * (cos(t) + t * sin(t))
            y = y0 + a * (sin(t) - t * cos(t))
            self.execute("G1 X%f Y%f" % (x,y),lineno())

        if c.z_flag: # retract to starting height
            self.execute("G0 Z%f" % (old_z),lineno())

    except InterpreterException,e:
        msg = "%d: '%s' - %s" % (e.line_number,e.line_text, e.error_message)
	return msg

    return INTERP_OK
---------------------------------------------------------------------

The examples described so far can be found in
'configs/sim/axis/remap/getting-started' with complete working
configurations.

== Upgrading an existing configuration for remapping

The minimal prerequisites for using `REMAP` statements are as follows:

- the Python plugin must be activated by specifying a
 `[PYTHON]TOPLEVEL=<path-to-toplevel-script>` in the ini file.
- the toplevel script needs to import the `remap` module, which can be
 initially empty, but the import needs to be in place.
- The Python interpreter needs to find the remap.py module above, so
 the path to the directory where your Python modules live needs to be
 added with  `[PYTHON]APPEND=<path-to-your-local-Python-directory>`
- Recommended: import the `stdglue` handlers in the `remap` module. In
 this case Python also needs to find `stdglue.py` - we just copy it
 from the distribution so you can make local changes as
 needed. Depending on your installation the path to `stdglue.py` might
 vary. 

Assuming your configuration lives under `/home/user/xxx` and the ini
file is `/home/user/xxx/xxx.ini`, execute the following commands.

[source,sh]
---------------------------------------------------------------------
$ cd /home/user/xxx
$ mkdir python
$ cd python
$ cp /usr/share/linuxcnc/ncfiles/remap_lib/python-stdglue/stdglue.py .
$ echo 'from stdglue import *' >remap.py
$ echo 'import remap' >toplevel.py
---------------------------------------------------------------------

Now edit `/home/user/xxx/xxx.ini` and add the following:

[source,{ini}]
---------------------------------------------------------------------
[PYTHON]
TOPLEVEL=/home/user/xxx/python/toplevel.py
APPEND=/home/user/xxx/python
---------------------------------------------------------------------

Now verify that LinuxCNC comes up with no error messages - from a
terminal window execute:

[source,sh]
---------------------------------------------------------------------
$ cd /home/user/xxx
$ linuxcnc xxx.ini
---------------------------------------------------------------------


== Remapping toolchange-related codes: T, M6, M61

=== Overview

If you are unfamiliar with LinuxCNC internals, first read the
<<remap::how-toolchange-currently-works, How toolchange currently
works>> section (dire but necessary).

Note than when remapping an existing code, we completely disable
<<remap::interpreter-action-on-M6,this codes' builtin functionality>>
of the interpreter. 

So our remapped code will need to do a bit more
than just generating some commands to move the machine as we like - it
will also need to replicate those steps from this sequence which are
needed to keep the interpreter and task happy.

However, this does *not* affect the processing of
toolchange-related commands in task and iocontrol. This means when we
execute <<remap::send-tool-load-msg,step 6b>> this will still cause
<<remap::iocontrol-action-on-load,iocontrol to do its thing>>.


Decisions, decisions:

- Do we want to use an O-word procedure or do it all in Python code?
- Is the iocontrol HAL sequence (tool-prepare/tool-prepared and
 tool-change/tool-changed pins) good enough or do we need a different kind
 of HAL interaction for our toolchanger (for example: more HAL pins
 involved with a  different interaction sequence)? 

Depending on the answer, we have four different scenarios:

- When using an O-word procedure, we need prolog and epilog functions
- if using all Python code and no O-word procedure, a Python function
is enough
- when using the iocontrol pins, our O-word procedure or Python code
will contain mostly moves
- when we need a more complex interaction than offered by iocontrol,
we need to completely define our own interactíon, using `motion.digital*` and
`motion.analog*` pins, and essentially ignore the iocontrol pins by
looping them.

NOTE: If you hate O-word procedures and love Python, you're free to do it
all in Python, in which case you would just have a `python=<function>`
spec in the REMAP statement. But assuming most folks would be interested in
using O-word procedures because they are more familiar with that, we'll do
that as the  first example.

So the overall approach for our first example will be:

. we'd like to do as much as possible with G-code in an O-word
procedure for flexibility. That includes all HAL interaction which
would normally be handled by iocontrol - because we rather would want to do
clever things with moves, probes, HAL pin I/O and so forth.

. we'll try to minimize Python code to the extent needed  to keep the interpreter happy,
and cause task to actually do anything. That will go into the
`prolog` and `epilog` Python functions.


=== Understanding the role of iocontrol with remapped toolchange codes
Iocontrol provides two HAL interaction sequences we might or might not
use:

- when the NML message queued by a SELECT_POCKET() canon command is
executed, this triggers the "raise tool-prepare and wait for
tool-prepared to become high" HAL sequence in iocontrol, besides
setting the XXXX pins
- when the NML message queued by the CHANGE_TOOL() canon command is
executed, this triggers the  "raise tool-change and wait for
tool-changed to become high" HAL sequence in iocontrol, besides
setting the XXXX pins

What you need to decide is whether the existing iocontrol HAL sequences
are sufficient to drive your changer. Maybe you need a different
interaction sequence - for instance more HAL  pins, or maybe a more
complex interaction. Depending on the answer, we might continue to use the existing
iocontrol HAL sequences, or define our own ones. 

For the sake of documentation, we'll disable these  iocontrol
sequences, and roll our own - the result will look and feel like the
existing interaction, but now we have complete control over them
because they are executed in our own O-word procedure.

So what we'll do is use some `motion.digital-*` and `motion.analog-*`
pins, and the associated `M62` .. `M68` commands to do our own HAL
interaction in our O-word procedure, and those will effectively
replace the iocontrol 'tool-prepare/tool-prepared' and
'tool-change/tool-changed' sequences. So we'll define our pins
replacing existing iocontrol pins functionally, and go ahead and make
the iocontrol interactions a noop. We'll use the following
correspondence in our example:

Iocontrol pin correspondence in the examples

[format="csv",width="60%",cols="2"]
[frame="topbot",grid="none"]
[options="header"]
|======
iocontrol.0 pin	,motion pin     
tool-prepare,digital-out-00 
tool-prepared,digital-in-00  
tool-change,digital-out-01 
tool-changed,digital-in-01  
tool-prep-number,analog-out-00  
tool-prep-pocket,analog-out-01  
tool-number,analog-out-02  
|======

Let us assume you want to redefine the M6 command, and replace it by
an O-word procedure, but other than that things 'should continue to
work'.

So what our O-word procedure would do is to replace the steps
<<remap::interpreter-action-on-M6,outlined here>>. Looking through
these steps you'll find that NGC code can be used for most of them,
but not all. So the stuff NGC cant handle will be done in Python prolog
and epilog functions.

=== Specifying the M6 replacement
To convey the idea, we just replace the builtin M6 semantics with our
own. Once that works, you may go ahead and place any actions you see
fit into the O-word procedure.

Going through the <<remap::interpreter-action-on-M6,steps>>, we find:

. check for T command already executed - *execute in Python prolog*
. check for cutter compensation being active - *execute in Python prolog*
. stop the spindle if needed - *can be done in NGC*
. quill up - *can be done in NGC*
. if TOOL_CHANGE_AT_G30 was set:
.. move the A, B and C indexers if applicable - *can be done in NGC*
.. generate rapid move to the G30 position - *can be done in NGC*
. send a CHANGE_TOOL Canon command to task  - *execute in Python epilog*
. set the numberer parameters 5400-5413 according to the new tool - *execute in Python epilog*
. signal to task to stop calling the interpreter for readahead until
toolchange complete - *execute in Python epilog*

So we need a prolog, and an epilog. Lets assume our ini file incantation of the M6 remap looks as follows:

 REMAP=M6   modalgroup=6  prolog=change_prolog ngc=change epilog=change_epilog

So the prolog covering steps 1 and 2 would look like so - we decide to
pass a few variables to the remap procedure which can be inspected and
changed there, or used in a message. Those are: `tool_in_spindle`,
`selected_tool` (tool numbers) and their respective pockets
`current_pocket` and `selected_pocket`:

[source,python]
---------------------------------------------------------------------
def change_prolog(self, **words):
    try:
	if self.selected_pocket < 0:
            return "M6: no tool prepared"

	if self.cutter_comp_side:
            return "Cannot change tools with cutter radius compensation on"

	self.params["tool_in_spindle"] = self.current_tool
	self.params["selected_tool"] = self.selected_tool
	self.params["current_pocket"] = self.current_pocket
        self.params["selected_pocket"] = self.selected_pocket
        return INTERP_OK
    except Exception, e:
        return "M6/change_prolog: %s" % (e)
---------------------------------------------------------------------

You will find that most prolog functions look very similar: first test
that all preconditions for executing the code hold, then prepare the
environment - inject variables and/or do any preparatory processing
steps which cannot easily be done in NGC code; then hand off to the
NGC procedure by returning INTERP_OK.

Our first iteration of the O-word procedure is unexciting - just
verify we got parameters right, and signal success by returning a
positive value; steps 3-5 would eventually be covered here (see
<<remap:referto-inifile-variables,here>> for the variables referring
to ini file settings):


[source,{ngc}]
---------------------------------------------------------------------
O<change> sub
(debug, change: current_tool=#<current_tool>)
(debug, change: selected_pocket=#<selected_pocket>)
;
; insert any g-code which you see fit here, eg:
; G0  #<_ini[setup]tc_x>  #<_ini[setup]tc_y>  #<_ini[setup]tc_z>
;
O<change> endsub [1]
m2
---------------------------------------------------------------------

Assuming success of `change.ngc`, we need to mop up steps 6-8:

[source,python]
---------------------------------------------------------------------
def change_epilog(self, **words):
    try:
        if self.return_value > 0.0:
            # commit change
            self.selected_pocket =  int(self.params["selected_pocket"])
            emccanon.CHANGE_TOOL(self.selected_pocket)
            # cause a sync()
            self.tool_change_flag = True
            self.set_tool_parameters()
            return INTERP_OK
        else:
            return "M6 aborted (return code %.1f)" % (self.return_value)

    except Exception, e:
        return "M6/change_epilog: %s" % (e)
---------------------------------------------------------------------

This replacement M6 is compatible with the builtin code,
except steps 3-5 need to be filled in with your NGC code.

Again, most epilogs have a common scheme: first, determine whether
things went right in the remap procedure, then do any commit and cleanup
actions which cant be done in NGC code.

=== Configuring iocontrol with a remapped M6

Note that the sequence of operations has changed: we do everything
required in the O-word procedure - including any HAL pin
setting/reading to get a changer going, and to acknowledge a tool
change - likely with `motion.digital-*` and `motion-analog-*` IO
pins. When we finally execute the `CHANGE_TOOL()` command, all
movements and HAL interactions are already completed.

Normally only now iocontrol would do its thing as outlined
<<remap::iocontrol-action-on-load,here>>. However, we dont need the
HAL pin wiggling anymore - all iocontrol is left to do is to accept
we're done with prepare and change.

This means that the corresponding iocontrol pins have no function any
more. Therefore, we configure iocontrol to immediately acknowledge a
change by configuring like so:

[source,{hal}]
---------------------------------------------------------------------
# loop change signals when remapping M6
net tool-change-loop iocontrol.0.tool-change iocontrol.0.tool-changed
---------------------------------------------------------------------
If you for some reason want to remap `Tx` (prepare), the corresponding
iocontrol pins need to be looped as well.

=== Writing the change and prepare O-word procedures

The standard prologs and epilogs found in
`ncfiles/remap_lib/python-stdglue/stdglue.py` pass a few 'exposed
parameters' to the remap procedure.

An 'exposed parameter' is a named local variable visible in a remap
procedure which corresponds to interpreter-internal variable which 
is relevant for the current remap. Exposed parameters
are set up in the respective prolog, and inspected in the epilog. They
can be changed in the remap procedure and the change will be picked up
in the epilog. The exposed parameters for remappable builtin codes are:


- `T` (prepare_prolog): `#<tool>` , `#<pocket>`
- `M6` (change_prolog): `#<tool_in_spindle>`, `#<selected_tool>`, `#<current_pocket>`, `#<selected_pocket>`
- `M61` (settool_prolog): `#<tool>` , `#<pocket>`
- `S` (setspeed_prolog):  `#<speed>`
- `F` (setfeed_prolog):  `#<feed>`

If you have specific needs for extra parameters to be made visible,
that can simply be added to the prolog - practically all of the
interpreter internals are visible to Python.

=== Making minimal changes to the builtin codes, including `M6`

Remember that normally remapping a code completely disables all internal
processing for that code.

However, in some situations it might be sufficient to add a few codes around
the existing `M6` builtin implementation, like a tool length probe,
but other than that retain the behaviour of the builtin `M6`.

Since this might be a common scenario, the builtin behaviour of
remapped codes has been made available within the remap
procedure. The interpreter detects that you are referring to a
remapped code within the procedure which is supposed to redefine its
behaviour. In this case, the builtin behaviour is used - this
currently is enabled for the set: `M6`, `M61`,`T`, `S`, `F`). Note
that otherwise referring to a code within its own remap procedure
would be a error - a `remapping recursion`.

Slightly twisting a builtin would look like so (in the case of `M6`):

 REMAP=M6   modalgroup=6  ngc=mychange 

[source,{ngc}]
---------------------------------------------------------------------
o<mychange> sub
M6 (use builtin M6 behaviour)
(.. move to tool length switch, probe and set tool length..)
o<mychange> endsub 
m2
---------------------------------------------------------------------


CAUTION: when redefining a builtin code, *do not specify any leading
zeroes in G- or M-codes* - for example, say `REMAP=M1 ..`, not
`REMAP=M01 ...`.

See the `configs/sim/axis/remap/extend-builtins` directory for a complete
configuration which is the recommded starting point for own work
when extending builtin codes.


=== Specifying the T (prepare) replacement
If you're confident with the  <<remap::interpreter-action-on-T,default
implementation>>, you wouldnt need to do this. But remapping is also a
way to work around deficiencies in the current implementation, for
instance to not block until the "tool-prepared" pin is set.

What you could do, for instance, is:
- in a remapped T, just set the equivalent of the "tool-prepare" pin,
but *not* wait for "tool-prepared" here
- in the corresponding remapped M6, wait for the "tool-prepared" at
the very beginning of the O-word procedure.

Again, the iocontrol tool-prepare/tool-prepared pins would be unused
and replaced by `motion.*` pins, so those would pins must be looped:
[source,{hal}]
---------------------------------------------------------------------
# loop prepare signals when remapping T
net tool-prep-loop iocontrol.0.tool-prepare iocontrol.0.tool-prepared
---------------------------------------------------------------------
So, here's the setup for a remapped T:

  REMAP=T  prolog=prepare_prolog epilog=prepare_epilog ngc=prepare

[source,python]
---------------------------------------------------------------------
def prepare_prolog(self,**words):
    try:
        cblock = self.blocks[self.remap_level]
        if not cblock.t_flag:
            return "T requires a tool number"

        tool  = cblock.t_number
        if tool:
            (status, pocket) = self.find_tool_pocket(tool)
            if status != INTERP_OK:
                return "T%d: pocket not found" % (tool)
        else:
            pocket = -1 # this is a T0 - tool unload
            
        # these variables will be visible in the ngc oword sub
        # as #<tool> and #<pocket> local variables, and can be
        # modified there - the epilog will retrieve the changed
        # values
        self.params["tool"] = tool
        self.params["pocket"] = pocket

        return INTERP_OK
    except Exception, e:
        return "T%d/prepare_prolog: %s" % (int(words['t']), e)

---------------------------------------------------------------------

The minimal ngc prepare procedure again looks like so:
[source,{ngc}]
---------------------------------------------------------------------
o<prepare> sub
; returning a positive value to commit:
o<prepare> endsub [1]
m2
---------------------------------------------------------------------

And the epilog:
[source,python]
---------------------------------------------------------------------
def prepare_epilog(self, **words):
    try:
        if self.return_value > 0:
            self.selected_tool = int(self.params["tool"])
            self.selected_pocket = int(self.params["pocket"])
            emccanon.SELECT_POCKET(self.selected_pocket, self.selected_tool)
            return INTERP_OK
        else:
            return "T%d: aborted (return code %.1f)" % (int(self.params["tool"]),self.return_value)

    except Exception, e:
        return "T%d/prepare_epilog: %s" % (tool,e)

---------------------------------------------------------------------

prepare_prolog and prepare_epilog are part of the 'standard glue'
provided by 'nc_files/remap_lib/python-stdglue/stdglue.py'.
This module is intended to cover most
standard remapping situations in a common way.


=== Error handling: dealing with abort
The builting toolchange procedure has some precautions for dealing
with a program abort (e.g. hitting Escape in Axis during a
change). Your remapped function has none of this, therefore some
explicit cleanup might be needed if a remapped code is aborted. In
particular, a remap procedure might establish modal settings which are
undesirable to have active after an abort. For instance, if your
remap procedure has motion codes (G0,G1,G38..) and the remap is
aborted, then the last modal code will remain active. However, you
very likely want to have any modal motion canceled when the remap is
aborted.

The way to do this is by using the `[RS274NGC]ON_ABORT_COMMAND`
feature. This ini option specifies a O-word procedure call which is
executed if task for some reason aborts program execution. 

[source,{ini}]
---------------------------------------------------------------------
[RS274NGC]
ON_ABORT_COMMAND=O <on_abort> call 
---------------------------------------------------------------------

The suggested on_abort procedure would look like so (adapt to
your needs):

[source,{ngc}]
---------------------------------------------------------------------
o<on_abort> sub

G54 (origin offsets are set to the default)
G17 (select XY plane)
G90 (absolute)
G94 (feed mode: units/minute)
M48 (set feed and speed overrides)
G40 (cutter compensation off)
M5  (spindle off)
G80 (cancel modal motion)
M9  (mist and coolant off)

o<on_abort> endsub
m2
---------------------------------------------------------------------

CAUTION: Never use an `M2` in a O-word subroutine, including this
one. It will cause hard-to-find errors. For instance, using an `M2` in
a subroutine will not end the subroutine properly and will leave the
subroutine NGC file open, not your main program.

Make sure `on_abort.ngc` is along the interpreter search path
(recommended location: `SUBROUTINE_PATH` so as not to clutter your
`NC_FILES` directory with internal procedures). `on_abort` receives a
single parameter indicating the cause for calling the abort procedure,
which might be used for conditional cleanup.

Statements in that procedure typically would assure that post-abort
any state has been cleaned up, like HAL pins properly reset. For an
example, see `configs/sim/axis/remap/rack-toolchange`.

Note that terminating a remapped code by returning INTERP_ERROR from
the epilog (see previous section) will also cause the `on_abort` procedure
to be called.

=== Error handling: failing a remapped code NGC procedure
If you determine in your handler procedure that some error condition
occurred, do not use `M2` to end your handler - see above:

If displaying an operator error message and stopping the current program is
good enough, use the `(abort, <message>)` feature to terminate the handler with an
error message. Note that you can subsitute numbered, named, ini and
HAL parameters in the text like
in this example (see also `tests/interp/abort-hot-comment/test.ngc`):

[source,{ngc}]
---------------------------------------------------------------------
o100 if [..] (some error condition)
     (abort, Bad Things! p42=#42 q=#<q> ini=#<_ini[a]x> pin=#<_hal[component.pin])
o100 endif
---------------------------------------------------------------------
NB: ini and HAL variable expansion need explicit enabling with
<<sub:ini-features,FEATURE>>.

If more fine grained recovery action is needed, use the idiom
laid out in the previous example:

- define an epilog function, even if it's just to signal an error
  condition
- pass a negative value from the handler to signal
  the error
- inspect the return value in the epilog function.
- take any recovery action needed
- return the error message string from the handler, which will set the
  interpreter error message and abort the program (pretty much like
  `(abort, message=`

This error message will be displayed in the UI, and returning
INTERP_ERROR will cause this error handled like any other runtime error.

Note that both `(abort, msg)` and returning INTERP_ERROR from an
epilog will cause any ON_ABORT handler to be called as well if defined
(see previous section).

== Remapping other existing codes: S, M0, M1, M60

=== Automatic gear selection be remapping  S (set spindle speed)
A potential use for a remapped S code would be 'automatic gear
selection' depending on speed. In the remap procedure one would test
for the desired speed attainable given the current gear setting, and
change gears appropriately if not.

=== Adjusting the behaviour of M0, M1, M60
A use case for remapping M0/M1 would be to customize the behaviour of
the existing code. For instance, it could be desirable to turn off the
spindle, mist and flood during an M0 or M1 program pause, and turn
these settings back on when the program is resumed.

For a complete example doing just that, see
'configs/sim/axis/remap/extend-builtins/', which adapts M1 as laid out above.

== Creating new G-code cycles [[remap:G-code-cycles]]

A G-code cycle as used here is meant to behave as follows:

* On first invocation, the associated words are collected and the
G-code cycle is executed.
* If subsequent lines just continue parameter words applicable to this
code, but no new G-code, the previous G code is reeexecuted with the
parameters changed accordingly.

An example: Assume you have `G84.3` defined as remapped G code cycle
with the following ini segment (see <<sec::cycle-stdglue,here>> for
a detailed description of +cycle_prolog+ and +cycle_epilog+):

[source,{ini}]
---------------------------------------------------------------------
[RS274NGC]
# A cycle with an oword procedure: G84.3 <X- Y- Z- Q- P->
REMAP=G84.3 argspec=xyzabcuvwpr prolog=cycle_prolog ngc=g843 epilog=cycle_epilog modalgroup=1 
---------------------------------------------------------------------
Executing the following lines:
[source,{ngc}]
---------------------------------------------------------------------
g17 
(1)   g84.3 x1 y2 z3  r1  
(2)   x3 y4 p2            
(3)   x6 y7 z5            
(4)   G80                 
---------------------------------------------------------------------
causes the following (note 'R' is sticky, and 'Z' is sticky since the plane is 'XY'):

. `g843.ngc` is called with words x=1, y=2, z=3, r=1
. `g843.ngc` is called with words x=3, y=4, z=3, p=2, r=1 
. `g843.ngc` is called with words x=6, y=7, z=3, r=1
.  The `G84.3` cycle is cancelled.

Besides creating new cycles, this provides an easy method for
repackaging existing G-codes which do not behave as cycles. For
instance, the `G33.1` Rigid Tapping code does not behave as a
cycle. With such a wrapper, a new code can be easily created which
uses `G33.1` but behaves as a cycle.

See 'configs/sim/axis/remap/cycle' for a complete example of this
feature. It contains two cycles, one with an NGC procedure like above,
and a cycle example using just Python.

== Configuring  Embedded Python  [[remap:embedded-Python]]

The Python plugin serves both the interpreter, and task if so
configured, and hence has its own section `PYTHON` in the ini file.

=== Python plugin : ini file configuration

`[PYTHON]`

`TOPLEVEL=`'<filename>'::
	filename of the initial Python script to execute on
	startup. This script is responsible for setting up the package
	name structure, see below.

`PATH_PREPEND=`'<directory>'::
	prepend this directory to `PYTHON_PATH`. A repeating
	group.

`PATH_APPEND=`'<directory>'::
	append this directory to `PYTHON_PATH`. A repeating
	group.

`LOG_LEVEL=`'<integer>'::
	log level of plugin-related actions. Increase this if you
	suspect problems. Can be very verbose.


`RELOAD_ON_CHANGE`='[0|1]'::
	reload the 'TOPLEVEL' script if the file was changed. Handy
	for debugging but currently incurs some runtime overhead. Turn
	this off for production configurations.

`PYTHON_TASK`='[0|1]'::
	Start the Python task plugin. Experimental. See xxx.


=== Executing Python statements from the interpreter [[remap::executing-Python-statements]]

For ad-hoc execution of commands the Python 'hot comment' has been
added. Python output by default goes to stdout, so you need to start
LinuxCNC from a terminal window to see results. Example (eg. in the
MDI window):

  ;py,print 2*3

Note that the interpreter instance is available here as `self`, so you
could also run:

  ;py,print self.tool_table[0].toolno

The `emcStatus` structure is accessible, too:

  ;py,from emctask import *
  ;py,print emcstat.io.aux.estop

== Programming Embedded Python in the RS274NGC Interpreter [[sec:Programming-Embedded-Python]]

=== The Python plugin namespace
The namespace is expected to be laid out as follows:

`oword`::
	Any callables in this module are candidates for Python O-word
	procedures. Note that the Python `oword` module is checked
	*before* testing for a NGC procedure with the same name - in
	effect names in `oword` will hide NGC files of the same
	basename.

`remap`::
	Python callables referenced in an argspec `prolog`,`epilog` or
	`python` option are expected to be found here.

`namedparams`::
	Python funtcions int this module extend or redefine the namespace of
	predefined named parameters, see
	<<sec:Adding-Predefined-Named-Parameters,adding predefined parameters>>.

`task`::
	Task-related callables are expected here.


=== The Interpreter as seen from Python

The interpreter is an existing C++ class ('Interp') defined in
'src/emc/rs274ngc'. Conceptually all `oword.<function>` and
`remap.<function>` Python calls are methods of this Interp class,
although there is no explicit Python definition of this class (it's a
'Boost.Python' wrapper instance) and hence receive the as the first
parameter `self` which can be used to access internals.

=== The Interpreter `__init__` and `__delete__` functions

If the `TOPLEVEL`  module defines a function `__init__`, it will be
called once the interpreter is fully configured (ini file read, and
state synchronized with the world model). 

If the `TOPLEVEL`  module defines a function `__delete__`, it will be
called once before the interpreter is shutdown and after the persistent
parameters have been saved to the `PARAMETER_FILE`.

Note_ at this time, the `__delete__` handler does not work for
interpreter instances created by importing the `gcode` module. If you
need an equivalent functionality there (which is quite unlikely),
please consider the Python `atexit` module.

[source,python]
---------------------------------------------------------------------
# this would be defined in the TOPLEVEL module

def __init__(self):
    # add any one-time initialisation here
    if self.task:
	# this is the milltask instance of interp
	pass
    else:
	# this is a non-milltask instance of interp
        pass

def __delete__(self):
    # add any cleanup/state saving actions here
    if self.task: # as above
	pass
    else:
        pass
---------------------------------------------------------------------

This function may be used to initialize any Python-side attributes
which might be needed later, for instance in remap or oword
functions, and save or restore state beyond what `PARAMETER_FILE` provides.

If there are setup or cleanup actions which are to happen only in the
milltask Interpreter instance (as opposed to the interpreter instance
which sits in the `gcode` Python module and serves preview/progress
display purposes but nothing else), this can be tested for by
<<cha:Axis-Preview-and-Remapped-code-execution,evaluating
'self.task'>>.

An example use of `__init__` and `__delete__` can be found in
'configs/sim/axis/remap/cycle/python/toplevel.py' initialising attributes
needed to handle cycles in 'ncfiles/remap_lib/python-stdglue/stdglue.py'
(and imported into 'configs/sim/axis/remap/cycle/python/remap.py').


=== Calling conventions: NGC to Python

Python code is called from NGC in the following situations:

- during normal program execution:
* when an O-word call like `O<proc> call` is executed and the name
`oword.proc` is defined and callable
* when a comment like `;py,<Python statement>` is executed
- during execution of a remapped code: any `prolog=`, `python=` and
  `epilog=` handlers.

==== Calling O-word Python subroutines  [[remap:Python-O-word-procs]]
Arguments:

`self`::
	the interpreter instance

`*args`::
	  the list of actual positional parameters. Since the number
	  of actual parameters may vary, it is best to use this style of declaration:

[source,python]
---------------------------------------------------------------------
# this would be defined in the oword module
def mysub(self, *args):
    print "number of parameters passed:", len(args)
    for a in args:
	print a
---------------------------------------------------------------------
==== Return values of O-word Python subroutines
Just as NGC procedures may return values, so do O-word Python
subroutines. They are expected to either:

- return no value (no `return` statement or the value `None`)
- a float or int value
- a string, this  means 'this is an error message, abort the program'. Works like `(abort, msg)`.

Any other return value type will raise a Python exception.

In a calling NGC environment, the follwing predefined named parameters
are available:

`#<_value>`::
	      value returned by the last procedure called. Initialized
	      to 0.0 on startup. Exposed in Interp as `self.return_value` (float).

`#<_value_returned>`::
	      indicates the last procedure called did `return`or
	      `endsub` with an explicit value. 1.0 if true. Set to 0.0 on each `call`. Exposed
	      in Interp was  `self.value_returned` (int).


See also `tests/interp/value-returned` for an example.

==== Calling conventions for 'prolog=' and 'epilog=' subroutines

Arguments are:

`self`::
	the interpreter instance

`words`::
	keyword parameter dictionary. If an argspec was present, words
	are collected from the current block accordingly and passed in
	the dictionary for  convenience (the words could as well be
	retrieved directly from the  calling block, but this requires
	more knowledge of interpreter internals). If no argspec was
	passed, or only optional values were specified and none of
	these was present in the calling block, this dict is
	empty. Word names are converted to lowercase.

Example call:
[source,python]
---------------------------------------------------------------------
def minimal_prolog(self, **words): # in remap module
    print len(words)," words passed"
    for w in words:
        print "%s: %s" % (w, words[w])
    if words['p'] < 78: # NB: could raise an exception if p were optional
       return "failing miserably"
    return INTERP_OK
---------------------------------------------------------------------

Return values:

`INTERP_OK`:: return this on success. You need to import this from
`interpreter`.

`"a message text"`:: returning a string from a handler means 'this is
an error message, abort the program'. Works like `(abort, msg)`.

.

==== Calling conventions for 'python=' subroutines

Arguments are:

`self`::
	the interpreter instance

`words`::
	keyword parameter dictionary. the same  kwargs dictionary as
	prologs and epilogs (see above).

The minimum `python=` function example:
[source,python]
---------------------------------------------------------------------
def useless(self,  **words): # in remap module
    return INTERP_OK
---------------------------------------------------------------------
Return values:

`INTERP_OK`:: return this on success

`"a message text"`:: returning a string from a handler means 'this is
an error message, abort the program'. Works like `(abort, msg)`.

If the handler needs to execute a 'queuebuster
operation' (tool change, probe, HAL pin reading) it is supposed
to suspend execution with the following statement:

`yield INTERP_EXECUTE_FINISH`::
       This signals task to stop readahead, execute all
       queued operations, execute the 'queuebuster' operation, 
       synchronize interpreter state with machine state, and th	en signal
	the interpreter to continue. At this point the function is
	resumed at the statement following the `yield ..` statement.

==== Dealing with queuebuster: Probe, Toolchange and waiting for a HAL pin


Queue busters interrupt a procedure at the point where such an
operation is called, hence the procedure needs to be restarted
after the interpreter synch(). When this happens the procedure needs to
know if it is restarted, and where to continue. The Python generator
method is used to deal with procedure restart.

This demonstrates call continuation with a single point-of-restart:

[source,python]
---------------------------------------------------------------------
def read_pin(self,*args):
    # wait 5secs for digital-input 00 to go high
    emccanon.WAIT(0,1,2,5.0)
    # cede control after executing the queue buster:
    yield INTERP_EXECUTE_FINISH
    # post-sync() execution resumes here:
    pin_status = emccanon.GET_EXTERNAL_DIGITAL_INPUT(0,0);
    print "pin status=",pin_status
---------------------------------------------------------------------

WARNING: The 'yield' feature is fragile. The following restrictions
apply to the usage of 'yield INTERP_EXECUTE_FINISH': 

- Python code executing a 'yield INTERP_EXECUTE_FINISH' must be part
  of a remap procedure. Yield does not work in a Python oword procedure.
- A Python remap subroutine containing 'yield INTERP_EXECUTE_FINISH' statement may
not return a value, as with normal Python yield statements.
- Code following a yield may not recursively call the interpreter, like with
  self.execute("<mdi command>"). This is an architectural restriction
  of the interpreter and is not fixable without a major redesign.

=== Calling conventions: Python to NGC

NGC code is executed from Python when:

- the method `self.execute(<NGC code>[,<line number>])` is executed
-  during execution of a remapped code, if a `prolog=` function is
 defined, the NGC procedure given in `ngc=` is executed immediately
 thereafter.

The prolog handler does not call the handler, but it prepares its call
environment, for instance by setting up predefined local parameters.

==== Inserting parameters in a prolog, and retrieving  them in an epilog

Conceptually a prolog and an epilog execute at the same call level
like the O-word procedure, that is: after the subroutine call is set
up, and before the subroutine endsub or return.

This means that any local variable created in a prolog will be a local
variable in the O-word procedure, and any local variables created in
the O-word procedure are still accessible when the epilog executes.

The `self.params` array handles reading and setting numbered and named
parameters. If a named parameter begins with `_` (underscore), it is
assumed to be a global parameter; if not, it is local to the calling
procedure. Also, numbered parameters in the range 1..30 are treated
like local variables; their original values are restored on
return/endsub from an O-word procedure.

Here is an example remapped code demonstrating insertion and
extraction of parameters into/from the O-word procedure:

  REMAP=m300 prolog=insert_param ngc=testparam epilog=retrieve_param modalgroup=10

[source,python]
---------------------------------------------------------------------
def insert_param(self, **words): # in the remap module
    print "insert_param call level=",self.call_level
    self.params["myname"] = 123
    self.params[1] = 345
    self.params[2] = 678
    return INTERP_OK

def retrieve_param(self, **words):
    print "retrieve_param call level=",self.call_level
    print "#1=", self.params[1]
    print "#2=", self.params[2]
    try:
        print "result=", self.params["result"]
    except Exception,e:
	return "testparam forgot to assign #<result>"
    return INTERP_OK
---------------------------------------------------------------------

[source,{ngc}]
---------------------------------------------------------------------
o<testparam> sub
(debug, call_level=#<_call_level> myname=#<myname>)
; try commenting out the next line and run again
#<result> = [#<myname> * 3]
#1 = [#1 * 5]
#2 = [#2 * 3]
o<testparam> endsub
m2
---------------------------------------------------------------------

`self.params()` returns a list of all variable names currently defined.
Since `myname` is local, it goes away after the epilog finishes.

==== Calling the interpreter from Python

You can recursively call the interpreter from Python code as follows:

  self.execute(<NGC code>[,<line number>])

Examples:
[source,python]
---------------------------------------------------------------------
  self.execute("G1 X%f Y%f" % (x,y))
  self.execute("O <myprocedure> call", currentline)
---------------------------------------------------------------------

You might want to test for the return value being `<
INTERP_MIN_ERROR`. If you're using lots of execute() statements, it's
probably easier to trap InterpreterException as per below.

CAUTION: The parameter insertion/retrieval method described in the previous section does not
work in this case. It is good enough for just executing simple NGC
commands or a procedure call and advanced introspection into the
procedure, and passing of local named parameters is not needed. The
recursive call feature is fragile.

==== Interpreter Exception during execute()

if `interpreter.throw_exceptions` is nonzero (default 1), and self.execute() returns an error, the exception
`InterpreterException` is raised. InterpreterException has the
following attributes:

`line_number`:: where the error occured
`line_text`:: the NGC statement causing the error
`error_message`:: the interpreter's error message

Errors can be trapped in the following Pythonic way:

[source,python]
-------------------------------------------------------------------
import interpreter
interpreter.throw_exceptions = 1
   ...
   try:
        self.execute("G3456")  #  raise InterpreterException

   except InterpreterException,e:
        msg = "%d: '%s' - %s" % (e.line_number,e.line_text, e.error_message)
        return msg  # replace builtin error message
---------------------------------------------------------------------
// NOTE: to iterate is human, to recurse: divine.

==== Canon
The canon layer is practically all free functions. Example:
[source,python]
---------------------------------------------------------------------
import emccanon
def example(self,*args):
    ....
    emccanon.STRAIGHT_TRAVERSE(line,x0,y0,z0,0,0,0,0,0,0)
    emccanon.STRAIGHT_FEED(line,x1,y1,z1,0,0,0,0,0,0)
    ...
    return INTERP_OK
---------------------------------------------------------------------

The actual canon functions are declared in `src/emc/nml_intf/canon.hh`
and implemented in `src/emc/task/emccanon.cc`.  The implementation of
the Python functions can be found in `src/emc/rs274ncg/canonmodule.cc`.

=== Builtin modules
The following modules are builtin:

`interpreter`::
	exposes internals of the Interp class. See
	 `src/emc/rs274ngc/interpmodule.cc`, and the
	`tests/remap/introspect` regression test.

`emccanon`::
	exposes most calls of  `src/emc/task/emccanon.cc`.

`emctask`::
	exposes the `emcStatus` class instance. See  `src/emc/task/taskmodule.cc`.
	Not present when using the `gcode` module used for user
	interfaces - only present in the milltask instance of the interpreter.

== Adding Predefined Named Parameters [[sec:Adding-Predefined-Named-Parameters]]

The interpreter comes with a set of <<sec:Predefined-Named-Parameters,predefined named parameters>> for
accessing internal state from the NGC language level. These parameters
are read-only and global, and hence cannot be assigned to.

Additional parameters may be added by defining a function in the
`namedparams` module. The name of the function defines the name of the
new predefined named parameter, which now can be referenced in
arbitrary expressions.

To add or redefine a named parameter:

* add a `namedparams` module so it can be found by the interpreter
* define new parameters by functions (see below). These functions
 receive `self` (the interpreter instance) as parameter and so can
 access aribtrary state. Arbitrary Python capabilities can be used to return a value.
* import that module from the `TOPLEVEL` script

[source,python]
---------------------------------------------------------------------
# namedparams.py
# trivial example
def _pi(self):
    return 3.1415926535
---------------------------------------------------------------------

[source,{ngc}]
---------------------------------------------------------------------
#<circumference> = [2 * #<radius> * #<_pi>]
---------------------------------------------------------------------

Functions in `namedparams.py` are expected to return a float or int
value. If a string is returned, this sets the interpreter error
message and aborts execution.

Ònly functions with a leading underscore are added as parameters,
since this is the RS274NGC convention for globals.

It is possible to redefine an existing predefined parameter by adding
a Python function of the same name to the `namedparams` module. In
this case, a warning is generated during startup.

While the above example isnt terribly useful, note that pretty much
all of the interpreter internal state is accessible from Python, so
arbitrary predicates may be defined this way. For a slightly more
advanced example, see `tests/remap/predefined-named-params`.

== Standard Glue routines [[sec:Standard-glue]]

Since many remapping tasks are very similar, I've started collecting
working prolog and epilog routines in a single Python module. These
can currently be found in
'ncfiles/remap_lib/python-stdglue/stdglue.py' and provide the
following routines:

=== T: +prepare_prolog+ and +prepare_epilog+ 

These wrap a NGC procedure for Tx Tool Prepare.

==== Actions of +prepare_prolog+

The following parameters are made visible to the NGC procedure:

- `#<tool>` - the parameter of the `T` word
- `#<pocket>` - the corresponding pocket

If tool number zero is requested (meaning Tool unload), the
corresponding pocket is passed as -1.

It is an error if:

- no tool number is given as T paramater
- the tool cannot be found in the tool table.

Note that unless you set the `[EMCIO] RANDOM_TOOLCHANGER=1` parameter,
tool and pocket number are identical, and the pocket number from the
tool table is ignored. This is currently a restriction.

==== Actions of +prepare_epilog+

- The NGC procedure is expected to return a positive value, otherwise
  and error message containing the return value is given and the
  interpreter abors.
- In case the NGC procedure executed the T command (which then refers
  to the builtin T behaviour), no further action is taken. This can be
  used for instance to minimally adjust the builtin behaviour be
  preceding or following it with some other statements.
- Otherwise, the `#<tool>` and `#<pocket>` parameters are extracted
  from the subroutine's parameter space. This means that the NGC
  procedure could change these values, and the epilog takes the
  changed values in account.
- then, the Canon command `SELECT_POCKET(#<pocket>,#<tool>)` is executed.

=== M6: +change_prolog+ and +change_epilog+ 

These wrap a NGC procedure for M6 Tool Change. 

==== Actions of +change_prolog+

* The following three steps are applicable only if the `iocontrol-v2`
component is used:
** If parameter 5600 (fault indicator) is greater than zero, this indicates a Toolchanger
fault, which is handled as follows:
** if parameter 5601 (error code) is negative, this indicates a hard
fault and the prolog aborts with an error message.
** if parameter 5601 (error code) is greater equal zero, this indicates a soft
fault. An informational message is displayed and the prolog continues.

* If there was no preceding T command which caused a pocket to be
selected, the prolog aborts with an error message.
* If cutter radius compensation is on, the prolog aborts with an error
message.

Then, the following parameters are exported to the NGC procedure:

- `#<tool_in_spindle>` : the tool number of the currently loaded tool
- `#<selected_tool>` : the tool number selected 
- `#<selected_pocket>` : the selected tool's pocket number


==== Actions of +change_epilog+

* The NGC procedure is expected to return a positive value, otherwise
  and error message containing the return value is given and the
  interpreter abors.
* If parameter 5600 (fault indicator) is greater than zero, this indicates a Toolchanger
fault, which is handled as follows (`iocontrol-v2`-only):
** if parameter 5601 (error code) is negative, this indicates a hard
fault and the epilog aborts with an error message.
** if parameter 5601 (error code) is greater equal zero, this indicates a soft
fault. An informational message is displayed and the epilog continues.
* In case the NGC procedure executed the M6 command (which then refers
  to the builtin M6 behaviour), no further action is taken. This can be
  used for instance to minimally adjust the builtin behaviour be
  preceding or following it with some other statements.
* Otherwise, the `#<selected_pocket>` parameter is extracted
  from the subroutine's parameter space, and used to set the
  interpreter's `current_pocket` variable. Again, the 
  procedure could change this value, and the epilog takes the
  changed value in account.
* then, the Canon command `CHANGE_TOOL(#<selected_pocket>)` is
  executed.
* The new tool parameters (offsets, diameter etc) are set.


=== G code Cycles: +cycle_prolog+ and +cycle_epilog+ [[sec::cycle-stdglue]]

These wrap a NGC procedure so it can act as a cycle, meaning the
motion code is retained after finishing execution. If the next line
just contains parameter words (e.g. new X,Y values), the code is
executed again with the new parameter words merged into the set of the
paramters given in the first invocation.

These routines are designed to work in conjunction with an
<<remap:argspec-parameter,`argspec=<words>` parameter>>. While this is
easy to use, in a realistic scenario you would avoid argspec and do a
more thorough investigation of the block manually in order to give better
error messages.

The suggested argspec is as follows:
[source,{ini}]
---------------------------------------------------------------------
REMAP=G<somecode> argspec=xyzabcuvwqplr prolog=cycle_prolog ngc=<ngc procedure> epilog=cycle_epilog modalgroup=1 
---------------------------------------------------------------------
This will permit +cycle_prolog+ to determine the compabitibily of any
axis words give in the block, see below.


//sec:Cycle-Sticky-Words
//sec:Canned-Cycle-Errors
//sec:Retract-Mode
==== Actions of +cycle_prolog+
* Determine whether the words passed in from the current block fulfill
the conditions outlined under <<sec:Canned-Cycle-Errors,Canned Cycle
Errors>>.
** export the axis words as +<x>+, +#<y>+ etc; fail if axis words from
different groups (XYZ) (UVW) are used together, or any of (ABC) is given.
** export 'L-' as +#<l>+; default to 1 if not given.
** export 'P-' as +#<p>+; fail if p less than 0.
** export 'R-' as +#<r>+; fail if r not given, or less equal 0 if given.
** fail if feed rate is zero, or inverse time feed or cutter
compensation is on.
* Determine whether this is the first invocation of a cycle G code, if
so:
** Add the words passed in (as per argspec) into a set of sticky
parameters, which is retained across several invocations.
* If not (a continuation line with new parameters):
** merge the words passed in into the existing set of sticky
paramaters.
* export the set of sticky parameters to the NGC procedure.

==== Actions of +cycle_epilog+
* Determine if the current code was in fact a cycle, if so:
** retain the current motion mode so a continuation line without a
motion code will execute the same motion code.

=== S (Set Speed) : +setspeed_prolog+ and +setspeed_epilog+ 
TBD

=== F (Set Feed) : +setfeed_prolog+ and +setfeed_epilog+ 
TBD

=== M61 Set tool number : +settool_prolog+ and +settool_epilog+ 
TBD

== Remapped code execution

=== NGC procedure call environment during remaps

Normally, an O-word procedure is called with positional parameters.
This scheme is very limiting in particular in the presence of optional
parameters. Therefore, the calling convention has been extended to use
something remotely similar to the Python keyword arguments model.

see  LINKTO gcode/main Subroutines: sub, endsub, return, call.

=== Nested remapped codes

Remapped codes may be nested just like procedure calls - that is, a
remapped code whose NGC procedure refers to some other remapped code
will execute properly.

The maximum nesting level remaps is currently 10.

=== Sequence number  during remaps

Sequence numbers are propagated and restored like with O-word
calls. See `tests/remap/nested-remaps/word` for the regression test,
which shows sequence number tracking during nested remaps three levels
deep.

=== Debugging flags

The following flags are relevant for remapping and Python - related execution:

 EMC_DEBUG_OWORD             0x00002000  traces execution of O-word subroutines
 EMC_DEBUG_REMAP             0x00004000  traces execution of remap-related code
 EMC_DEBUG_PYTHON            0x00008000  calls to the Python plugin
 EMC_DEBUG_NAMEDPARAM        0x00010000  trace named parameter access
 EMC_DEBUG_PYTHON_TASK       0x00040000  trace the task Python plugin
 EMC_DEBUG_USER1             0x10000000  user-defined - not interpreted by LinuxCNC
 EMC_DEBUG_USER2             0x20000000  user-defined - not interpreted by LinuxCNC

'or' these flags into the `[EMC]DEBUG` variable as needed. For a current
list of debug flags see 'src/emc/nml_intf/debugflags.h'.

=== Debugging Embedded Python code

Debugging of embedded Python code is harder than debugging normal
Python scripts, and only a limited supply of debuggers exists. A
working open-source based solution is to use the
http://www.eclipse.org[Eclipse IDE], and the http://www.pydev.org[PydDev]
Eclipse plugin and its
http://pydev.org/manual_adv_remote_debugger.html[remote debugging
feature].

To use this approach:

- install Eclipse via the the 'Ubuntu Software Center' (choose first
selection)
- install the PyDev plugin from the
http://pydev.org/updates[Pydev Update Site]
- setup the LinuxCNC source tree as an Eclipse project
- start the Pydev Debug Server in Eclipse
- make sure the embedded Python code can find the `pydevd.py` module
which comes with that plugin - it's buried somewhere deep under the
Eclipse install directory. Set the the `pydevd` variable in `util.py`
to reflect this directory location.
- `import pydevd` in your Python module - see example `util.py` and `remap.py`
- call `pydevd.settrace()` in your module at some point to connect to
the Eclipse Python debug server - here you can set breakpoints in your
code, inspect variables, step etc as usual.

CAUTION:  `pydevd.settrace()` will block execution if Eclipse and the
Pydev debug server have not been started.

To cover the last two steps: the `o<pydevd>` procedure helps to get
into the debugger from MDI mode. See also the `call_pydevd` function
in `util.py` and its usage in `remap.involute` to set a breakpoint.

Here's a screenshot of Eclipse/PyDevd debugging the `involute`
procedure from above:

image::images/debug_embedded_python.png[Debugging with Eclipse]

See the Python code in `configs/sim/axis/remap/getting-started/python` for details.

== Axis Preview and Remapped code execution
[[cha:Axis-Preview-and-Remapped-code-execution]]

For complete preview of a remapped code's toolpath some precautions
need to be taken. To understand what is going on, let's review the
preview and execution process (this covers the Axis case, but others
are similar):

First, note that there are *two* independent interpreter instances
involved:

- one instance in the milltask program, which executes a program when
you hit the 'Start' button, and actually makes the machine move
- a second instance in the user interface whose primary purpose is to
generate the toolpath preview. This one 'executes' a program once it
is loaded, but it doesnt actually cause machine movements.

Now assume that your remap procedure contains a G38 probe operation,
for example as part of a tool change with automatic tool length
touchoff. If the probe fails, that would clearly be an error, so you'd
display a message and abort the program. 

Now, what about preview of this procedure?  At preview time, of course
it's not known whether the probe succeeds or fails - but you would
likely want to see what the maximum depth of the probe is, and assume
it  succeeds and continues execution to
preview further movements. Also, there is no point in displaying a
'probe failed' message and aborting *during preview*.

The way to address this issue is to test in your procedure whether it
executes in preview or execution mode. This can be checked for by
testing the `#<_task>` <<sec:Predefined-Named-Parameters, predefined
named parameter>> - it will be 1 during actual execution and 0 during
preview. See
'configs/sim/axis/remap/manual-toolchange-with-tool-length-switch/nc_subroutines/manual_change.ngc'
for a complete usage example.

Within Embedded Python, the task instance can be checked for by
testing 'self.task' - this will be 1 in the milltask instance, and 0
in the preview instance(s).

== Remappable Codes [[sec:remap:remappable-codes]]

=== Existing codes which can be remapped [[remap:remappable-codes]]

The current set of *existing* codes open to redefinition is:

- Tx (Prepare)
- M6 (Change tool)
- M61 (Set tool number)
- M0 (pause a running program temporarily)
- M1 (pause a running program temporarily if the optional stop switch is on)
- M60 (exchange pallet shuttles and then pause a running program temporarily)
- S  (set spindle speed)
- F  (set feed)

Note that the use of M61 currently requires the use of iocontrol-v2.

=== Currently unallocated G-codes: [[remap:unallocated-g-codes]]

These codes are currently undefined in the current implementation of LinuxCNC
and may be used to define new G-codes:

FIXTHIS too verbose

G0.1 G0.2 G0.3 G0.4 G0.5 G0.6 G0.7 G0.8 G0.9
G1.1 G1.2 G1.3 G1.4 G1.5 G1.6 G1.7 G1.8 G1.9
G2.1 G2.2 G2.3 G2.4 G2.5 G2.6 G2.7 G2.8 G2.9
G3.1 G3.2 G3.3 G3.4 G3.5 G3.6 G3.7 G3.8 G3.9
G4.1 G4.2 G4.3 G4.4 G4.5 G4.6 G4.7 G4.8 G4.9
G5.4 G5.5 G5.6 G5.7 G5.8 G5.9
G6 G6.1 G6.2 G6.3 G6.4 G6.5 G6.6 G6.7 G6.8 G6.9
G7.1 G7.2 G7.3 G7.4 G7.5 G7.6 G7.7 G7.8 G7.9
G8.1 G8.2 G8.3 G8.4 G8.5 G8.6 G8.7 G8.8 G8.9
G9 G9.1 G9.2 G9.3 G9.4 G9.5 G9.6 G9.7 G9.8 G9.9
G10.1 G10.2 G10.3 G10.4 G10.5 G10.6 G10.7 G10.8 G10.9
G11 G11.1 G11.2 G11.3 G11.4 G11.5 G11.6 G11.7 G11.8 G11.9
G12 G12.1 G12.2 G12.3 G12.4 G12.5 G12.6 G12.7 G12.8 G12.9
G13 G13.1 G13.2 G13.3 G13.4 G13.5 G13.6 G13.7 G13.8 G13.9
G14 G14.1 G14.2 G14.3 G14.4 G14.5 G14.6 G14.7 G14.8 G14.9
G15 G15.1 G15.2 G15.3 G15.4 G15.5 G15.6 G15.7 G15.8 G15.9
G16 G16.1 G16.2 G16.3 G16.4 G16.5 G16.6 G16.7 G16.8 G16.9
G17.2 G17.3 G17.4 G17.5 G17.6 G17.7 G17.8 G17.9
G18.2 G18.3 G18.4 G18.5 G18.6 G18.7 G18.8 G18.9
G19.2 G19.3 G19.4 G19.5 G19.6 G19.7 G19.8 G19.9
G20.1 G20.2 G20.3 G20.4 G20.5 G20.6 G20.7 G20.8 G20.9
G21.1 G21.2 G21.3 G21.4 G21.5 G21.6 G21.7 G21.8 G21.9
G22 G22.1 G22.2 G22.3 G22.4 G22.5 G22.6 G22.7 G22.8 G22.9
G23 G23.1 G23.2 G23.3 G23.4 G23.5 G23.6 G23.7 G23.8 G23.9
G24 G24.1 G24.2 G24.3 G24.4 G24.5 G24.6 G24.7 G24.8 G24.9
G25 G25.1 G25.2 G25.3 G25.4 G25.5 G25.6 G25.7 G25.8 G25.9
G26 G26.1 G26.2 G26.3 G26.4 G26.5 G26.6 G26.7 G26.8 G26.9
G27 G27.1 G27.2 G27.3 G27.4 G27.5 G27.6 G27.7 G27.8 G27.9
G28.2 G28.3 G28.4 G28.5 G28.6 G28.7 G28.8 G28.9
G29 G29.1 G29.2 G29.3 G29.4 G29.5 G29.6 G29.7 G29.8 G29.9
G30.2 G30.3 G30.4 G30.5 G30.6 G30.7 G30.8 G30.9
G31 G31.1 G31.2 G31.3 G31.4 G31.5 G31.6 G31.7 G31.8 G31.9
G32 G32.1 G32.2 G32.3 G32.4 G32.5 G32.6 G32.7 G32.8 G32.9
G33.2 G33.3 G33.4 G33.5 G33.6 G33.7 G33.8 G33.9
G34 G34.1 G34.2 G34.3 G34.4 G34.5 G34.6 G34.7 G34.8 G34.9
G35 G35.1 G35.2 G35.3 G35.4 G35.5 G35.6 G35.7 G35.8 G35.9
G36 G36.1 G36.2 G36.3 G36.4 G36.5 G36.6 G36.7 G36.8 G36.9
G37 G37.1 G37.2 G37.3 G37.4 G37.5 G37.6 G37.7 G37.8 G37.9
G38 G38.1 G38.6 G38.7 G38.8 G38.9
G39 G39.1 G39.2 G39.3 G39.4 G39.5 G39.6 G39.7 G39.8 G39.9
G40.1 G40.2 G40.3 G40.4 G40.5 G40.6 G40.7 G40.8 G40.9
G41.2 G41.3 G41.4 G41.5 G41.6 G41.7 G41.8 G41.9
G42.2 G42.3 G42.4 G42.5 G42.6 G42.7 G42.8 G42.9
G43.2 G43.3 G43.4 G43.5 G43.6 G43.7 G43.8 G43.9
G44 G44.1 G44.2 G44.3 G44.4 G44.5 G44.6 G44.7 G44.8 G44.9
G45 G45.1 G45.2 G45.3 G45.4 G45.5 G45.6 G45.7 G45.8 G45.9
G46 G46.1 G46.2 G46.3 G46.4 G46.5 G46.6 G46.7 G46.8 G46.9
G47 G47.1 G47.2 G47.3 G47.4 G47.5 G47.6 G47.7 G47.8 G47.9
G48 G48.1 G48.2 G48.3 G48.4 G48.5 G48.6 G48.7 G48.8 G48.9
G49.1 G49.2 G49.3 G49.4 G49.5 G49.6 G49.7 G49.8 G49.9
G50 G50.1 G50.2 G50.3 G50.4 G50.5 G50.6 G50.7 G50.8 G50.9
G51 G51.1 G51.2 G51.3 G51.4 G51.5 G51.6 G51.7 G51.8 G51.9
G52 G52.1 G52.2 G52.3 G52.4 G52.5 G52.6 G52.7 G52.8 G52.9
G53.1 G53.2 G53.3 G53.4 G53.5 G53.6 G53.7 G53.8 G53.9
G54.1 G54.2 G54.3 G54.4 G54.5 G54.6 G54.7 G54.8 G54.9
G55.1 G55.2 G55.3 G55.4 G55.5 G55.6 G55.7 G55.8 G55.9
G56.1 G56.2 G56.3 G56.4 G56.5 G56.6 G56.7 G56.8 G56.9
G57.1 G57.2 G57.3 G57.4 G57.5 G57.6 G57.7 G57.8 G57.9
G58.1 G58.2 G58.3 G58.4 G58.5 G58.6 G58.7 G58.8 G58.9
G59.4 G59.5 G59.6 G59.7 G59.8 G59.9
G60 G60.1 G60.2 G60.3 G60.4 G60.5 G60.6 G60.7 G60.8 G60.9
G61.2 G61.3 G61.4 G61.5 G61.6 G61.7 G61.8 G61.9
G62 G62.1 G62.2 G62.3 G62.4 G62.5 G62.6 G62.7 G62.8 G62.9
G63 G63.1 G63.2 G63.3 G63.4 G63.5 G63.6 G63.7 G63.8 G63.9
G64.1 G64.2 G64.3 G64.4 G64.5 G64.6 G64.7 G64.8 G64.9
G65 G65.1 G65.2 G65.3 G65.4 G65.5 G65.6 G65.7 G65.8 G65.9
G66 G66.1 G66.2 G66.3 G66.4 G66.5 G66.6 G66.7 G66.8 G66.9
G67 G67.1 G67.2 G67.3 G67.4 G67.5 G67.6 G67.7 G67.8 G67.9
G68 G68.1 G68.2 G68.3 G68.4 G68.5 G68.6 G68.7 G68.8 G68.9
G69 G69.1 G69.2 G69.3 G69.4 G69.5 G69.6 G69.7 G69.8 G69.9
G70 G70.1 G70.2 G70.3 G70.4 G70.5 G70.6 G70.7 G70.8 G70.9
G71 G71.1 G71.2 G71.3 G71.4 G71.5 G71.6 G71.7 G71.8 G71.9
G72 G72.1 G72.2 G72.3 G72.4 G72.5 G72.6 G72.7 G72.8 G72.9
G73.1 G73.2 G73.3 G73.4 G73.5 G73.6 G73.7 G73.8 G73.9
G74 G74.1 G74.2 G74.3 G74.4 G74.5 G74.6 G74.7 G74.8 G74.9
G75 G75.1 G75.2 G75.3 G75.4 G75.5 G75.6 G75.7 G75.8 G75.9
G76.1 G76.2 G76.3 G76.4 G76.5 G76.6 G76.7 G76.8 G76.9
G77 G77.1 G77.2 G77.3 G77.4 G77.5 G77.6 G77.7 G77.8 G77.9
G78 G78.1 G78.2 G78.3 G78.4 G78.5 G78.6 G78.7 G78.8 G78.9
G79 G79.1 G79.2 G79.3 G79.4 G79.5 G79.6 G79.7 G79.8 G79.9
G80.1 G80.2 G80.3 G80.4 G80.5 G80.6 G80.7 G80.8 G80.9
G81.1 G81.2 G81.3 G81.4 G81.5 G81.6 G81.7 G81.8 G81.9
G82.1 G82.2 G82.3 G82.4 G82.5 G82.6 G82.7 G82.8 G82.9
G83.1 G83.2 G83.3 G83.4 G83.5 G83.6 G83.7 G83.8 G83.9
G84.1 G84.2 G84.3 G84.4 G84.5 G84.6 G84.7 G84.8 G84.9
G85.1 G85.2 G85.3 G85.4 G85.5 G85.6 G85.7 G85.8 G85.9
G86.1 G86.2 G86.3 G86.4 G86.5 G86.6 G86.7 G86.8 G86.9
G87.1 G87.2 G87.3 G87.4 G87.5 G87.6 G87.7 G87.8 G87.9
G88.1 G88.2 G88.3 G88.4 G88.5 G88.6 G88.7 G88.8 G88.9
G89.1 G89.2 G89.3 G89.4 G89.5 G89.6 G89.7 G89.8 G89.9
G90.2 G90.3 G90.4 G90.5 G90.6 G90.7 G90.8 G90.9
G91.2 G91.3 G91.4 G91.5 G91.6 G91.7 G91.8 G91.9
G92.4 G92.5 G92.6 G92.7 G92.8 G92.9
G93.1 G93.2 G93.3 G93.4 G93.5 G93.6 G93.7 G93.8 G93.9
G94.1 G94.2 G94.3 G94.4 G94.5 G94.6 G94.7 G94.8 G94.9
G95.1 G95.2 G95.3 G95.4 G95.5 G95.6 G95.7 G95.8 G95.9
G96.1 G96.2 G96.3 G96.4 G96.5 G96.6 G96.7 G96.8 G96.9
G97.1 G97.2 G97.3 G97.4 G97.5 G97.6 G97.7 G97.8 G97.9
G98.1 G98.2 G98.3 G98.4 G98.5 G98.6 G98.7 G98.8 G98.9
G99.1 G99.2 G99.3 G99.4 G99.5 G99.6 G99.7 G99.8 G99.9

=== Currently unallocated M-codes: [[remap:unallocated-m-codes]]

These codes are currently undefined in the current implementation of LinuxCNC
and may be used to define new M-codes:

 M10
 M11 M12 M13 M14 M15 M16 M17 M18 M19 M20
 M21 M22 M23 M24 M25 M26 M27 M28 M29 M31 M32 M33 M34 M35 M36 M37 M38 M39 M40
 M41 M42 M43 M44 M45 M46 M47 M54 M55 M56 M57 M58 M59 M74 M75 M76 M77 M78 M79 M80
 M81 M82 M83 M84 M85 M86 M87 M88 M89 M90
 M91 M92 M93 M94 M95 M96 M97 M98 M99

All codes between `M199`  and `M999`.

=== readahead time and execution time
foo

=== plugin/pickle hack
foo

=== Module, methods, classes, etc reference
foo


== Introduction: Extending Task Execution
foo

=== Why would you want to change Task Execution?
foo

=== A diagram: task, interp, iocontrol, UI (??)
foo

== Models of Task execution
foo

=== Traditional iocontrol/iocontrolv2 execution
foo

=== Redefining IO procedures
foo

=== Execution-time Python procedures
foo

// setup examples

== A short survey of LinuxCNC program execution
To understand remapping of codes it might be helpful to survey the
execution  of task and interpreter as far as it relates to remapping.

=== Interpreter state
Conceptually, the interpreter's state consist of variables which fall into
the following categories:

1. configuration information (typically from INI file)
2. the 'World model' - a representation of actual machine state
3. modal state and settings
4. interpreter execution state

(3) refers to state which is 'carried over' between executing
individual NGC codes - for instance, once the spindle is turned on and
the speed is set, it remains at this setting until turned off. The
same goes for many codes, like feed, units, motion modes (feed or
rapid)  and so forth.

(4) holds information about the block currently executed, whether we
are in a subroutine, interpreter variables etc.

Most of this state is aggregated in a - fairly unsystematic -
`structure _setup` (see interp_internals.hh).

=== Task and Interpreter interaction, Queueing and Read-Ahead

The task part of LinuxCNC is responsible for coordinating actual machine
commands - movement, HAL interactions and so forth. It does not by
itself handle the RS274NGC language. To do so, task calls upon the
interpreter to parse and execute the next command - either from MDI or
the current file.

The interpreter execution generates canonical machine operations, which
actually move something. These are, however, not immediately executed but
put on a queue. The actual execution of these codes happens in the task
part of LinuxCNC: canon commands are pulled off that interpreter queue,
and executed resulting in actual machine movements.

This means that typically the interpreter is far ahead of the actual
execution of commands - the parsing of the program might well be
finished before any noticeable movement starts. This behaviour is
called 'read-ahead'. 

=== Predicting the machine position

To compute canonical machine operations in advance during readahead,
the interpreter must be able to predict the machine position after
each line of Gcode, and that is not always possible.

Let's look at a simple example program which does relative moves
(G91), and assume the machine starts at x=0,y=0,z=0. Relative moves
imply that the outcome of the next move relies on the position of the
previous one:

[source,{ngc}]
---------------------------------------------------------------------
N10 G91
N20 G0 X10 Y-5 Z20
N30 G1 Y20 Z-5
N40 G0 Z30
N50 M2
---------------------------------------------------------------------

Here the interpreter can clearly predict machine positions for each line:

After N20: x=10 y=-5 z=20; after N30: x=10 y=15 z=15; after N40: x=10 y=15 z=45

and so can parse the whole program and generate canonical operations
well in advance.


=== Queuebusters break position prediction

However, complete readahead is only possible when the
interpreter can predict the position impact for *every* line in the
program in advance. Let's look at a modified example:

[source,{ngc}]
---------------------------------------------------------------------
N10 G91
N20 G0 X10 Y-5 Z20
N30 G38.3 Z-10
N40 O100 if [#5070 EQ 0]
N50    G1 Y20 Z-5
N60 O100 else
N70    G0 Z30
N80 O100 endif
N90 G1 Z10
N95 M2
---------------------------------------------------------------------
To pre-compute the move in N90, the interpreter would need to know
where the machine is after line N80 - and that depends on whether the
probe command succeeded or not, which is not known until it's actually
executed.

So, some operations are incompatible with further read-ahead. These
are called 'queue busters', and they are:

- reading a HAL pin's value with M66: value of HAL pin not predictable
- loading a new tool with M6: tool geometry not predictable
- executing a probe with G38.x: final position and success/failure not predictable


=== How queuebusters are dealt with

Whenever the interpreter encounters a queuebuster, it needs to stop
readahead and wait until the relevant result is avalaible. The way
this works is:

- when such a code is encountered, the interpreter returns a
special return code to task ('INTERP_EXECUTE_FINISH'). 

- this returncode signals to task to stop readahead for now, execute
all queued canonical commands built up so far (including the last one,
which is the queue buster), and then 'synchronize 
the interpreter state with the world model'. Technically, this means
updating internal variables to reflect HAL pin values, reload tool
geometries after an M6, and convey results of a probe.

- The interpreter's 'synch()' method is called by task and does just
that - read all the world model 'actual' values which are relevant for
further execution.

- at this point, task goes ahead and calls the interpreter for more
  readahead - until either the program ends or another queuebuster is encountered.

=== Word order and execution order

One or several 'words' may be present on an NGC 'block' if they are
compatible (some are mutually exclusive and must be on different
lines).  The execution model however prescribes a strict ordering of
execution of codes, regardless of their appearance on the source line
(<<sec:Order-of-Execution, G-Code Order of Execution>>).

=== Parsing

Once a line is read (in either MDI mode, or from the current NGC
file), it is parsed and flags and parameters are set in a 'struct
block' (struct _setup, member block1). This struct holds all information
about the current source line, but independent of different ordering
of codes on the current line: as long as several codes are compatible,
any source ordering will result in the same variables set in the
struct block. Right after parsing, all codes on a block are checked for
compatibility.

=== Execution

After successful parsing the block is executed by execute_block(), and
here the different items are handled according to execution order.

If a "queue buster" is found, a corresponding flag is set in the
interpreter state (toolchange_flag, input_flag, probe_flag) and the
interpreter returns an INTERP_EXECUTE_FINISH return value, signaling
'stop readahead for now, and resynch' to the caller ('task').
If no queue busters are found
after all items are executed, INTERP_OK is returned, signalling that
read-ahead may continue.

When read ahead continues after the synch, task starts executing
interpreter read() operations again.  During the next read operation,
the abovementioned flags are checked and corresponding variables are
set (because the a synch() was just executed, the values are now
current). This means that the next command already executes in the
properly set variable context.

=== Procedure execution

O-word procedures complicate handling of queue busters a bit. A queue
buster might be found somewhere in a nested procedure, resulting in a
semi-finished procedure call when INTERP_EXECUTE_FINISH is
returned. Task makes sure to synchronize the world model, and continue
parsing and execution as long as there is still a procedure executing
(call_level > 0).

=== How toolchange currently works [[remap::how-toolchange-currently-works]]
The actions happening in LinuxCNC are a bit involved, but it's necessary
to get the overall idea what currently happens before you set out to
adapt those workings to your own needs.

Note that remapping an existing code completely disables all internal
processing for that code. That means that beyond your desired
behaviour - probably described through an NGC Oword or Python
procedure, you need to replicate those internal actions of the
interpreter which together result in a complete replacement of the
existing code. The prolog and epilog code is the place to do this.

==== How tool information is communicated
Several processes are 'interested' in tool information: task and its
interpreter, as well as the user interface. Also, the 'halui' process.

Tool information is held in the 'emcStatus' structure, which is
 shared by all parties. One of its fields is the 'toolTable' array,
 which holds the description as loaded from the tool table file (tool
 number, diameter, frontangle, backangle and orientation for lathe,
 tool offset information).

The authoritative source and only process actually 'setting' tool
information in this structure is the 'iocontrol' process. All others
processes just consult this structure. The interpreter holds actually
a local copy of the tool table.

For the curious, the current emcStatus structure can be accessed by
<<remap::executing-Python-statements,Python statements>>. The
interpreter's perception of the tool currently loaded for instance is
accessed by:

 ;py,from interpreter import *
 ;py,print this.tool_table[0]

To see fields in the global emcStatus structure, try this:

 ;py,from emctask import *
 ;py,print emcstat.io.tool.pocketPrepped
 ;py,print emcstat.io.tool.toolInSpindle
 ;py,print emcstat.io.tool.toolTable[0]

You need to have LinuxCNC started from a terminal window to see the
results.

=== How Tx (Prepare Tool) works



==== Interpreter action on a Tx command [[remap::interpreter-action-on-T]]

All the interpreter does is evaluate the toolnumber paramter, looks up
its corresponding pocket, remembers it in the `selected_pocket`
variable for later, and  queues a canon command
(SELECT_POCKET). See 'Interp::convert_tool_select' in 'src/emc/rs274/interp_execute.cc'.

==== Task action on SELECT_POCKET

When task gets around to handle a SELECT_POCKET, it sends a
EMC_TOOL_PREPARE message to the iocontrol process, which handles most
tool-related actions in LinuxCNC.

In the current implementation, task actually waits for iocontrol to
complete the changer positioning operation, which is not necessary IMO
- it defeats the idea that changer preparation and code execution can
proceed in parallel.

==== Iocontrol action on EMC_TOOL_PREPARE

When iocontrol sees the select pocket command, it does the related HAL
pin wiggling - it sets the "tool-prep-number" pin to indicate which
tool is next, raises the "tool-prepare" pin, and waits for the
"tool-prepared" pin to go high.

When the changer responds by asserting "tool-prepared", it considers
the prepare phase to be completed and signals task to
continue. (again, this 'wait' istn strictly necessary IMO)

==== Building the prolog and epilog for Tx

See the Python functions `prepare_prolog` and `prepare_epilog` in 
`configs/sim/axis/remap/toolchange/python/toolchange.py`.


=== How M6 (Change tool) works

You need to understand this fully before you can adapt it. It is very
relevant to writing a prolog and epilog handler for a remapped
M6. Remapping an existing codes means you disable the internal steps
taken normally, and replicate them as far as needed for your own
purposes.

Even if you are not familiar with C, I suggest you look at the
'Interp::convert_tool_change' code in
'src/emc/rs274/interp_convert.cc'.

==== Interpreter action on a M6 command [[remap::interpreter-action-on-M6]]
When the interpreter sees an M6, it:

. checks whether a T command has already been executed (test
'settings->selected_pocket' to be >= 0) and fail with 'Need tool
prepared -Txx- for toolchange' message if not.
. check for cutter compensation being active, and fail with 'Cannot
change tools with cutter radius compensation on' if so.
. stop the spindle except if the "TOOL_CHANGE_WITH_SPINDLE_ON" ini
option is set.
. generate a rapid 'Z up' move if if the "TOOL_CHANGE_QUILL_UP" ini
option is set.
. if TOOL_CHANGE_AT_G30 was set:
.. move the A, B and C indexers if applicable
.. generate rapid move to the G30 position
. execute a CHANGE_TOOL canon command,with the selected pocket as
parameter. CHANGE_TOOL will:
.. generate a rapid move to TOOL_CHANGE_POSITION if so set in ini
.. enqueue an EMC_TOOL_LOAD NML message to task. [[remap::send-tool-load-msg]]
. set the numberer parameters 5400-5413 according to the new tool
. signal to task to stop calling the interpreter for readahead by
returning INTERP_EXECUTE_FINISH since M6 is a queue buster.

==== What task does when it sees a CHANGE_TOOL command
Again, not much more than passing the buck to iocontrol by sending it
an EMC_TOOL_LOAD message, and waiting until iocontrol has done its
thing.

==== Iocontrol action on EMC_TOOL_LOAD [[remap::iocontrol-action-on-load]]

. it asserts the "tool-change" pin
. it waits for the "tool-changed" pin to become active
. when that has happened:
.. deassert "tool-change"
.. set "tool-prep-number" and "tool-prep-pocket" pins to zero
.. execute the 'load_tool()' function with the pocket as parameter.

The last step actually sets the tooltable entries in the 'emcStatus'
structure. The actual action taken depends on whether the
RANDOM_TOOLCHANGER ini option was set, but at the end of the process
'toolTable[0]' reflects the tool currently in the spindle.

When that has happended:

. iocontrol signals task to go ahead
. task tells the interpreter to execute a 'synch()' operation, to see
what has changed
. the interpreter 'synch()' pulls all information from the world model
needed, among it the changed tool table.

From there on, the interpreter has complete  knowledge of the world
model and continues with readahead.

==== Building the prolog and epilog for M6
See the Python functions `change_prolog` and `change_epilog` in 
`configs/sim/axis/remap/toolchange/python/toolchange.py`.

=== How M61 (Change tool number) works
M61 requires a non-negative `Q`parameter (tool number). If zero, this
means 'unload tool', else 'set current tool number to Q'. 

==== Building the replacement for M61
An example Python redefinition for M61 can be found in the
`set_tool_number` function in 
`configs/sim/axis/remap/toolchange/python/toolchange.py`.


== Optional Interpreter features: ini file configuration[[sub:ini-features]]
(((Enabling optional features)))

There are some interpreter features in this branch which are
experimental, and not backwards compatible, which is why they need to
be enabled explicitly. They are specified as follows:

[source,{ini}]
---------------------------------------------------------------------
  [RS274NGC]
  FEATURES = <feature mask>
---------------------------------------------------------------------

Mask bits are:

`Retain G43: 1 (experimental)`:: 
	When set, you can  turn on G43 after loading the first tool,
        and then not worry about it through the program.  When you
	finally unload the last tool, G43 mode is canceled. 
	This is experimental as it changes the
	operation of legal ngc program, but it could be argued that
	those programs are buggy or likely to be not what the author
        intended.
 
`add n_args parameter:  2`::
       A called subroutine can determine the number of actual positional 
       parameters passed by inspecting the +#<n_args>+ parameter.


`enable #<_ini[section]name> readonly variables:  4`:: 
	if set, the interpreter will fetch read-only values from the
	ini file through this special variable syntax.
	

`enable #<_hal[Hal item]> readonly variables: 8`:: 
	if set, the interpreter will fetch read-only values from HAL 
	file through this special variable syntax.

`preserve case in O-word names within comments: 16`:: 
	  if set, enables reading of mixed-case HAL items in
	  structured comments like  '(debug, #<_hal[MixedCaseItem])'.
	  Really a cludge which should go away.

== Named parameters and inifile variables [[remap:referto-inifile-variables]]

To access ini file values from G-code,  use the following named
parameter syntax:

	  #<_ini[section]name>

For example, if the ini file looks like so:

[source,{ini}]
---------------------------------------------------------------------
[SETUP]
XPOS = 3.145
YPOS = 2.718
---------------------------------------------------------------------

you may refer to the O-word named parameters `#<_ini[setup]xpos>` and
`#<_ini[setup]ypos>` within G-code.

`EXISTS` can be used to test for presence of a given ini file
variable:

[source,{ngc}]
---------------------------------------------------------------------
o100 if [EXISTS[#<_ini[setup]xpos>]]
  (debug, [setup]xpos exists: #<_ini[setup]xpos>)
o100 else
  (debug, [setup]xpos does not exist)
o100 endif
---------------------------------------------------------------------

The value is read from the inifile once, and cached in the
interpreter. These parameters are read-only - assigning a value will
cause a runtime error. The names are not case sensitive - they are
converted to uppercase before consulting the ini file.

Permanent setup information is usually stored in the ini file. While
ini variables can be easily accessed from the shell, Python and C code,
so far there was no way to refer to ini file variables from G-code.
This release enables such access. The feature was motivated by the
need to replace ini variables which are currently used in the
hard-coded toolchange process, like the `[EMCIO]TOOL_CHANGE_POSITION` parameter.


CAUTION: this section doesnt really belong here but since it comes with
the same branch, here it rests for now until its clear this will be
merged. It should go into the gcode/overview Named Parameters section.


== Named parameters and HAL items [[remap:referto-hal-items]]


To read arbitrary HAL pins, signals and parameters from G-code,  use the following named
parameter syntax:

	  #<_hal[hal_name]>

where `hal_name` may be a pin, parameter or signal name. 

Example:

[source,{ngc}]
---------------------------------------------------------------------
(debug, #<_hal[motion-controller.time]>)
---------------------------------------------------------------------

Access of HAL items is read-only. Currently, only all-lowercase HAL
names can be accessed this way.

`EXISTS` can be used to test for the presence of a given HAL item:

[source,{ngc}]
---------------------------------------------------------------------
o100 if [EXISTS[#<_hal[motion-controller.time]>]]
  (debug, [motion-controller.time] exists: #<_hal[motion-controller.time]>)
o100 else
  (debug, [motion-controller.time] does not exist)
o100 endif
---------------------------------------------------------------------

This feature was motivated by the desire for stronger coupling between
user interface components like `GladeVCP` and `PyVCP` to act as
paramter source for driving NGC file behaviour. The alternative -
going through the M6x pins and wiring them - has a limited,
non-mmemonic namespace and is unncessary cumbersome just as a
UI/Interpreter communications mechanism.


CAUTION: this section doesnt really belong here but since it comes with
the same branch, here it rests for now until its clear this will be
merged. It should go into the gcode/overview Named Parameters section.

==  Status

. the RELOAD_ON_CHANGE feature is fairly broken. Restart after
changing a Python file.

. M61 (remapped or not) is broken in iocontrol and requires
iocontrol-v2 to actually work.

// A short survey of LinuxCNC execution
// Interpreter internals access - Python view
// Task internals access - Python view

==  Build notes - Lucid (10.04)

For the interpreter & task Python plugins, this is required:

 apt-get install libboost-python1.40-dev

When compiling you might notice that interpmodule.cc takes very long
to compile, which is normal - the extensive use of C++ templates makes the
compiler breathe heavily. 

If you want to play with the configs/sim/axis/remap/iocontrol-removed
example, you need to install as follows:

 apt-get unixODBC-dev libsqliteodbc sqlite3
 git clone https://code.google.com/p/pyodbc/
 sudo  python setup.py build install

If you'd want to try how the Firefox SQlite manager plugin looks &
feels as a tooltable editor, try this:

. read http://code.google.com/p/sqlite-manager/

. download the zip file  'SQLiteManager 0.7.7 as XULRunner App' 
    or whatever is the latest from http://code.google.com/p/sqlite-manager/downloads/list

. create a directory under your home directory, eg ~/sqlite-manager

. unzip the zp file from 1) into this directory
 
.try running firefox with this plugin and the tooltable.sqlite file in this directory like so:
 `firefox -app <homdir>/sqlite-manager/application.ini -f tooltable.sqlite`
   
 firefox should come up with the sqlite manager extension and having this database opened

. adapt the following command line with appropriate paths in the ini file:

`TOOL_EDITOR= firefox -app  /home/mah/sqlite-manager/application.ini -f /home/mah/emc2-dev/configs/sim/remap/iocontrol-removed/tooltable.sqlite`



==  Build notes - Hardy (8.04)

Building and running on Hardy is possible. runtests works fine too, so
the remapping framework per se is ok.

However running the examples is quite limited as of now:

The Git version included in 8.04 is too old to pull
https://code.google.com/p/pyodbc/ so the iocontrol-removed demo cant
be run.

The  python-gtkglext1 dependency is missing for reasons I dont
understand.

Even if python-gtkglext1 is installed, the startup of the
manualtoolchange and racktoolchange demos fails due to gladevcp startup issues.

Note that has nothing to to with the new code but rather the very old
platform trying to run gladevcp.

==  Workarounds

The workaround mentioned below was necessary up to commit
d21a488a9e82dd85aa17207b80e3d930afeff202 . References to
DISPLAY_LD_PRELOAD and TASK_LD_PRELOAD have been removed from the ini
files under configs/sim/axis/remap because they are not needed anymore.

Configure now tests whether a workaround is required, and
automatically does 'the right thing' if needed.

 # Michael Haberler 4/2011
 #
 # if you get a segfault like described
 # here: https://bugs.launchpad.net/ubuntu/+source/mesa/+bug/259219
 # or here: https://www.libavg.de/wiki/LinuxInstallIssues#glibc_invalid_pointer :
 #
 # specify a workaround with:
 # [DISPLAY]
 # DISPLAY_LD_PRELOAD = /usr/lib/libstdc++.so.6
 # and
 # [TASK]
 # TASK_LD_PRELOAD = /usr/lib/libstdc++.so.6
 #
 # this is actually a bug in libgl1-mesa-dri and it looks
 # it has been fixed in mesa - 7.10.1-0ubuntu2
 # unfortunately for now this workaround is needed
 DISPLAY_LD_PRELOAD = /usr/lib/libstdc++.so.6


// normal, _italic_, *bold*, +mono+.
// ``double quoted'', `single quoted'.
// normal, ^super^, ~sub~.
// normal, italic, bold, mono.
// “double quoted”, ‘single quoted’.
// normal, super, sub.
// Command: `ls -al`
// +mono *bold*+
// `passthru *bold*`

== Changes

- the method to return error messages and fail used to be
  'self.set_errormsg(text)' followed by 'return INTERP_ERROR'. This
  has been replaced by merely returning a string from a Python handler
  or oword subroutine. This sets the error message and aborts the
  progam. Previously there was no clean way to abort a Python oword
  subroutine.