===============================================================================
 RUNNING THE BIG BLUE CONVERSATIONAL TAB ON A SIMULATED LATHE
 How to graft it onto LinuxCNC's own  sim / axis / lathe-fanucy  sample config
 Written 2026-08-07.  Every step below was built and tested before writing.
===============================================================================

WHY THIS FILE
-------------
The big-blue-lathe config drives real servos through a Mesa 7i92 and needs a
ClassicLadder E-stop chain, gearbox solenoids and sensors to even come out of
E-stop.  A friend with no hardware cannot jog it or run a program.

So instead of shipping the machine config, we bolt the CONVERSATIONAL TURNING
TAB onto a stock LinuxCNC sim.  You get a machine that homes instantly, jogs,
runs programs, does manual tool changes and simulates a spindle - and the
Turning tab writes exactly the same G-code it writes on the real lathe.

The base is  sim/axis/lathe-fanucy  rather than  sim/axis/lathe , because
lathe-fanucy already ships the T-word / wear-offset remap plumbing that big
blue depends on:  the REMAP = T line, the [PYTHON] section, remap.py and
toplevel.py.  That is most of the fiddly part done for you.


===============================================================================
 TWO WAYS TO DO THIS - PICK ONE
===============================================================================

  ROUTE A - USE THE READY-MADE CONFIG.  Two minutes, nothing to type.
  ---------------------------------------------------------------------------
  If you have  big-blue-sim.zip , everything below has already been done for
  you.  The whole finished config is in it.  On the test PC:

      mkdir -p ~/linuxcnc/configs
      unzip big-blue-sim.zip -d ~/linuxcnc/configs/
      linuxcnc ~/linuxcnc/configs/big-blue-sim/big-blue-sim.ini

  That is it.  Skip to STEP 4 - RUN IT.

  You do NOT need to create the lathe-fanucy sample config first.  The zip
  already contains its remap.py and toplevel.py, which is the only thing that
  was ever taken from it.

  ROUTE B - BUILD IT BY HAND.  Steps 1 to 3 below.
  ---------------------------------------------------------------------------
  Do this if you have not got the zip, or if you want to understand what is
  in it, or if you are redoing this on a future LinuxCNC version.

  The only difference between the two routes is the NAME.  Route A gives you
      ~/linuxcnc/configs/big-blue-sim/big-blue-sim.ini
  and Route B gives you
      ~/linuxcnc/configs/lathe-fanucy/lathe-fanucy.ini
  with identical contents.  Wherever this file says "lathe-fanucy.ini" below,
  read it as "whichever of those two you have".

  NOTE FOR THE BIG BLUE MACHINE ITSELF: copying this text file into the
  big-blue-lathe config folder does nothing on its own - it is only a set of
  instructions.  The sim is a SEPARATE config directory.  Nothing here changes
  or touches the real machine's config.


-------------------------------------------------------------------------------
STEP 1 - CREATE THE SIM CONFIG
-------------------------------------------------------------------------------
Launch LinuxCNC's config picker:

    Applications > CNC > LinuxCNC          (or run:  linuxcnc   with no arguments)

Choose:     Sample Configurations > sim > axis > lathe-fanucy
Click OK / Create.  Say yes when it offers to copy the config.

That creates the directory:

    ~/linuxcnc/configs/lathe-fanucy/

containing:  lathe-fanucy.ini   lathe-fanucy.tbl   remap.py
             toolchange.ngc     toplevel.py        README

Start it once now, just to prove the stock sim runs on that PC.  Then quit.

  ** KEEP THE CONFIG AT  ~/linuxcnc/configs/<name>/  **
  Two settings below are relative paths that assume exactly that depth.
  You may rename the folder; do not move it somewhere else.


-------------------------------------------------------------------------------
STEP 2 - COPY FILES IN FROM THE BIG BLUE ZIP
-------------------------------------------------------------------------------
Unzip the big blue config somewhere, then copy these files into
~/linuxcnc/configs/lathe-fanucy/ .  Overwrite when asked.

  REQUIRED - the conversational tab itself:

    lathe_profile.py      all the G-code generation.  The whole cycle library.
    lathe_handler.py      the GladeVCP glue: reads the fields, calls the
                          generator, writes the file, loads it into AXIS.
    thread_data.py        the standard thread table (ISO, UNC, UNF, BSP,
                          NPT, BSPT) and the thread-form arithmetic.
    lathe_conv.ui         the panel layout.  GENERATED - never hand-edit it.

  REQUIRED - the tool + wear behaviour, so the sim matches the machine:

    toolchange.ngc        OVERWRITES the one lathe-fanucy ships.  See the
                          note below - this one is NOT the same.
    tool.tbl              T1..T20 plus wear rows T10001..T10020.
                          (Replaces lathe-fanucy.tbl, which only has 2 tools.)

  RECOMMENDED - the tool wear Offsets tab:

    offsets_handler.py
    offsets.ui            GENERATED - never hand-edit.
    offsets.css           GENERATED - never hand-edit.

  OPTIONAL - only if you want to change field ranges or run the self-tests:

    build_lathe_conv_ui.py    regenerates lathe_conv.ui
    build_offsets_ui.py       regenerates offsets.ui + offsets.css
    check_lathe_profile.py    the round-trip validator
    golden_dump.py            the regression harness
    backups/golden-current/   the baseline golden_dump.py diffs against


  DO NOT COPY remap.py OR toplevel.py.
  lathe-fanucy already has them and they are identical to big blue's apart
  from comments.  That is the bit you get for free.

  DO NOT COPY the __pycache__ FOLDER.
  Those are compiled .py files from this machine's Python version and a stale
  one can shadow a .py you just copied.  Let Python rebuild it.


  ** WHY toolchange.ngc MUST BE REPLACED **
  lathe-fanucy's version reads the T word BACKWARDS from big blue's:

      lathe-fanucy :  T0201  =  tool 1, wear 2      (last 2 digits = tool)
      big blue     :  T0201  =  tool 2, wear 1      (first 2 digits = tool,
                                                     the Fanuc convention)

  Every T word the conversational tab writes is symmetric - tool 3 is T0303 -
  so the two agree on anything the panel generates and you would never notice.
  You WILL notice the moment you hand-type an asymmetric word in MDI.
  Big blue's version also adds three things fanucy's has not got:
    - a leading G30 park before the change
    - a bare word below 100 stays a plain tool number, no wear
      (this is required: AXIS sends "t<n> m6" itself on every file open)
    - hard limits on the wear offset, 0.5 mm radius on X and 1.0 mm on Z,
      which abort the program if the tool table holds something silly.
  Copy big blue's so the sim tests the real behaviour.


-------------------------------------------------------------------------------
STEP 3 - REPLACE THE INI
-------------------------------------------------------------------------------
Open ~/linuxcnc/configs/lathe-fanucy/lathe-fanucy.ini and replace the WHOLE
file with the text between the two ==== lines below.

(Replacing the whole file is deliberate: there are about a dozen scattered
edits and hand-applying them is where mistakes happen.)

==== BEGIN lathe-fanucy.ini ==================================================
[EMC]
VERSION = 1.1
MACHINE = big-blue-lathe-SIM
  DEBUG = 0

[DISPLAY]
             DISPLAY = axis
               LATHE = 1
            GEOMETRY = xz
          CYCLE_TIME = 0.100
     POSITION_OFFSET = RELATIVE
   POSITION_FEEDBACK = ACTUAL
   MAX_FEED_OVERRIDE = 2.0
MAX_SPINDLE_OVERRIDE = 2.0
MIN_SPINDLE_OVERRIDE = 0.5
      PROGRAM_PREFIX = ../../nc_files
       INTRO_GRAPHIC = linuxcnc.gif
          INTRO_TIME = 2
          INCREMENTS = 5mm 1mm .5mm .1mm .05mm .01mm .005mm
DEFAULT_LINEAR_VELOCITY = 6.0
    MAX_LINEAR_VELOCITY = 166.666667
    MIN_LINEAR_VELOCITY = 0.5

EMBED_TAB_NAME = Turning
EMBED_TAB_COMMAND = gladevcp -c lathe_conv -x {XID} -u lathe_handler.py lathe_conv.ui
EMBED_TAB_NAME = Offsets
EMBED_TAB_COMMAND = gladevcp -c offsets -x {XID} -u offsets_handler.py offsets.ui

[FILTER]
PROGRAM_EXTENSION = .png,.gif,.jpg Grayscale Depth Image
PROGRAM_EXTENSION = .py Python Script
              png = image-to-gcode
              gif = image-to-gcode
              jpg = image-to-gcode
               py = python3

[RS274NGC]
SUBROUTINE_PATH = ./:../
          REMAP = T prolog=get_T_number ngc=toolchange
 PARAMETER_FILE = sim-lathe.var
RS274NGC_STARTUP_CODE = G7 G18 G21 G90 G54 G64 P0.01 Q0.01
CENTRE_ARC_RADIUS_TOLERANCE_MM = 0.50

[EMCMOT]
      EMCMOT = motmod
COMM_TIMEOUT =       1.0
 BASE_PERIOD =   50000
SERVO_PERIOD = 1000000

[TASK]
      TASK = milltask
CYCLE_TIME = 0.001

[HAL]
HALFILE = LIB:basic_sim.tcl

[TRAJ]
         COORDINATES = X Z
        LINEAR_UNITS = mm
       ANGULAR_UNITS = degree
DEFAULT_LINEAR_VELOCITY = 16.67
MAX_LINEAR_VELOCITY = 166.67
DEFAULT_LINEAR_ACCELERATION = 300.0
MAX_LINEAR_ACCELERATION = 400.0

[EMCIO]
                 TOOL_TABLE = tool.tbl

[KINS]
KINEMATICS = trivkins coordinates=xz
    JOINTS = 2

[AXIS_X]
       MIN_LIMIT = -500.0
       MAX_LIMIT =  500.0
    MAX_VELOCITY =  200.0
MAX_ACCELERATION =  400.0

[AXIS_Z]
       MIN_LIMIT = -2000.0
       MAX_LIMIT =   200.0
    MAX_VELOCITY =  166.666667
MAX_ACCELERATION =  300.0

[JOINT_0]
            TYPE = LINEAR
    MAX_VELOCITY =  200.0
MAX_ACCELERATION =  400.0
       MIN_LIMIT = -500.0
       MAX_LIMIT =  500.0
 HOME_SEARCH_VEL =    0
  HOME_LATCH_VEL =    0
   HOME_SEQUENCE =    0

[JOINT_1]
            TYPE = LINEAR
    MAX_VELOCITY =  166.666667
MAX_ACCELERATION =  300.0
       MIN_LIMIT = -2000.0
       MAX_LIMIT =   200.0
 HOME_SEARCH_VEL =    0
  HOME_LATCH_VEL =    0
   HOME_SEQUENCE =    1

[PYTHON]
# where to find Python code
# code specific for this configuration
PATH_PREPEND= ./
# generic support code
PATH_APPEND= ../../nc_files/remap_lib/python-stdglue/
PATH_APPEND= /usr/share/linuxcnc/ncfiles/remap_lib/python-stdglue/

# import the following Python module
TOPLEVEL= toplevel.py

# the higher the more verbose tracing of the Python plugin
LOG_LEVEL = 0
==== END lathe-fanucy.ini ====================================================


-------------------------------------------------------------------------------
WHAT CHANGED IN THAT INI, AND WHY  (reference - you do not have to do anything)
-------------------------------------------------------------------------------
Everything below is a change from the stock lathe-fanucy.ini.

 [DISPLAY]
   EMBED_TAB_NAME / EMBED_TAB_COMMAND  x2
        THE WHOLE POINT.  Two of them: Turning and Offsets.  AXIS accepts
        repeated pairs; the HAL component name after -c must be unique.
        The panel declares NO HAL pins, so there is no postgui wiring to do.
   GEOMETRY = xz
        front-tool lathe.  Big blue has no BACK_TOOL_LATHE.
   PROGRAM_PREFIX = ../../nc_files
        The panel always writes to ~/linuxcnc/nc_files/lathe (it creates the
        folder itself).  This makes AXIS's file dialog open in the same place.
        It is RELATIVE to the config directory, which is why the config has to
        stay at ~/linuxcnc/configs/<name>/ .  Do not write ~/linuxcnc/nc_files
        here - AXIS does not expand "~" for this setting.
   INCREMENTS, the velocity lines, the override limits
        metric values, copied from big blue so jogging feels the same.

 [RS274NGC]
   RS274NGC_STARTUP_CODE = G7 G18 G21 G90 G54 G64 P0.01 Q0.01
        G7 is DIAMETER MODE and is the important one - without it the DRO
        reads radius and every number on the Turning tab means something else.
        G18 is the XZ plane, G21 millimetres.  The generated programs set
        their own modes on line 1 anyway, but MDI and the DRO need this.
   CENTRE_ARC_RADIUS_TOLERANCE_MM
        the cycles emit arcs in centre format; this matches the machine.
   REMAP / PARAMETER_FILE / SUBROUTINE_PATH   unchanged from lathe-fanucy.

 [TRAJ]
   LINEAR_UNITS = mm            stock lathe-fanucy is INCH.  Must change.
   the velocity / acceleration lines are metric to match.

 [EMCIO]
   TOOL_TABLE = tool.tbl        big blue's table, 20 tools + 20 wear rows.
   TOOL_CHANGE_POSITION and TOOL_CHANGE_WITH_SPINDLE_ON were REMOVED -
        toolchange.ngc does its own G30 park, and a manual tool change should
        stop the spindle.

 [AXIS_X] [AXIS_Z] [JOINT_0] [JOINT_1]
   limits X -500..500 , Z -2000..200 , metric velocities
        Stock is inches and tiny (X +-10, Z -2..4) - a 52 mm bar would trip a
        soft limit immediately.
        These are deliberately LOOSER than the real machine (X -400..25,
        Z -1850..5).  On the real lathe the G54 work offset is about -318 mm
        in X, so work X0 sits well inside travel.  The sim starts with all
        offsets at zero, so a 800 mm diameter needs 400 mm of X.  Setting the
        real limits here would make perfectly good programs refuse to run.
   HOME_SEARCH_VEL = 0 , HOME_LATCH_VEL = 0
        homes instantly where it stands, no home switches needed.  Press
        Home All and you are done.  The real machine homes on the encoder
        index, which a sim has not got.

 [PYTHON]
   a SECOND PATH_APPEND = /usr/share/linuxcnc/ncfiles/remap_lib/python-stdglue/
        remap.py does "from stdglue import *", and stdglue lives outside the
        config.  Stock lathe-fanucy only looks in ../../nc_files/remap_lib/,
        which exists on a fresh install but not if someone has put their own
        files in ~/linuxcnc/nc_files.  The absolute path is the belt to that
        brace.  PATH_APPEND is documented as a repeating group, so having two
        is legal.  Without this the T remap dies with
        "Python plugin required for prolog=, but not available".

 [HAL]
   HALFILE = LIB:basic_sim.tcl      unchanged.  This is what gives you
        simulated motion, simulated home switches, hal_manualtoolchange, and
        a simulated spindle encoder - which is what makes G33 threading and
        G33.1 rigid tapping actually run in the preview.


-------------------------------------------------------------------------------
WHAT IS DELIBERATELY *NOT* COPIED
-------------------------------------------------------------------------------
Do not copy any of these.  Each one needs hardware that is not there, and most
will stop the config loading at all.

  big-blue-lathe.ini        the real machine ini.  Superseded by the above.
  big-blue-lathe.hal        Mesa 7i92 / 7i77 hardware.
  big-blue-lathe-sim.hal    still loads ClassicLadder and pid components.
  custom.hal                gearbox solenoids, spindle mux, coolant, conveyor.
  custom.clp                the ClassicLadder program.
  mpgbigblue.hal            the 7i84 handwheel.
  pyvcp-panel.xml           the right-hand strip: gear LEDs, gear buttons,
  pyvcp_options.hal         tool buttons.  All of it is wired to halui MDI
                            commands, ClassicLadder outputs and gearbox
                            signals that do not exist here.
  m301.ngc .. m305.ngc      the gearbox M-codes.  These wait on the four gear
                            sensors with M66.  In a sim nothing ever drives
                            those pins, so the program would sit there.
                            NO REMAP LINES FOR THEM ARE IN THE INI ABOVE -
                            that is on purpose.
  shutdown.hal, custom_postgui.hal, custom_gvcp.hal, gvcp-panel.ui
  linuxcnc.var, position.txt, rs274ngc.var
                            machine runtime state.  Let the sim make its own.
  local_nc_files/           only holds warmup.ngc, which is a big blue
                            warm-up program.  Copy it if you like, but the
                            ini above does not reference it.

The Turning tab does not use any of it.  It only writes G-code.


-------------------------------------------------------------------------------
STEP 4 - RUN IT
-------------------------------------------------------------------------------
Route A (the zip):
    linuxcnc ~/linuxcnc/configs/big-blue-sim/big-blue-sim.ini
Route B (built by hand):
    linuxcnc ~/linuxcnc/configs/lathe-fanucy/lathe-fanucy.ini

or pick it from the config chooser under "My Configurations".

Then, in order:

  1. F1 to clear E-stop, F2 machine on.
  2. Press "Home All".  Both axes home instantly at wherever they are.
  3. Click the "Turning" tab along the top of the right-hand pane.
     Nine pages: OD turning, ID boring, Facing, Groove, Part off, Drilling,
     OD thread, ID thread, Program.
  4. On OD turning, press Generate.
     - the status line should name the file it wrote
     - AXIS should load it and show the toolpath in the preview
     - the file lands in ~/linuxcnc/nc_files/lathe/
  5. Press Cycle Start and watch it run.  A manual tool change dialog will
     pop up at the start - click Continue.
  6. Try the other pages the same way.  On the threading pages press the
     thread picker button to fill a standard thread in.
  7. On the Program tab, "Add to program" a couple of cycles from different
     pages and press Generate - it joins them into one file with the tool
     changes in between.


-------------------------------------------------------------------------------
DIFFERENCES YOU WILL SEE vs THE REAL MACHINE
-------------------------------------------------------------------------------
None of these are faults.  Expect them.

  G30 goes to X0 Z0.
      On big blue G30 is stored at about X0 Z-1530, so a tool change is a
      full rapid down the bed and back.  In the sim the parameter file starts
      empty so G30 parks at the machine origin.  If you want a more realistic
      park: jog somewhere clear, then type   G30.1   in MDI.  That stores the
      current position as G30 and it persists in sim-lathe.var.

  No gear box.
      The real spindle command is divided by the engaged gear ratio, so a
      D600 rpm cap means nothing in bottom gear.  There is no gearbox here,
      and M301..M304 are not remapped.  Spindle speed is taken literally.

  Coolant does nothing visible.
      M8 is accepted.  On the real machine it drives 7i77 output-13.
      (M7 mist does nothing on the real machine either - it is netted to
      iocontrol but reaches no output pin.)

  Rigid tapping "works" here but has never been run for real.
      basic_sim.tcl gives a perfect simulated spindle encoder, so G33.1 runs
      beautifully in the sim.  Whether big blue's analog drive can actually
      track well enough to tap is a machine question the sim cannot answer.

  The tab may show a horizontal scrollbar on a small screen.
      The pages need roughly 570-800 px of width.  The scrollbar is normal
      and the pages are meant to scroll; nothing is broken.

  Tool geometry offsets are big blue's real ones.
      tool.tbl carries Z offsets up to 486 mm.  Positions in the sim will
      look odd against the DRO for that reason.  Harmless.


-------------------------------------------------------------------------------
IF IT WILL NOT START
-------------------------------------------------------------------------------
Never judge it by the exit code - after a config error LinuxCNC retries
"waiting for s.joints<0>" forever and a killed run looks like a healthy one.
The truth is in the NEWEST of these two files:

    /tmp/linuxcnc.debug.*      interpreter / HAL / Python errors
    /tmp/linuxcnc.print.*      startup sequence, which HAL files loaded

Common ones:

  "Python plugin required for prolog=, but not available"
      the [PYTHON] PATH_APPEND lines are wrong, or stdglue.py is not where
      they point.  Check:
          ls /usr/share/linuxcnc/ncfiles/remap_lib/python-stdglue/stdglue.py

  The Turning tab is missing or blank
      an EMBED_TAB_COMMAND typo, or a missing file.  gladevcp errors show up
      in the terminal you launched from, so launch from a terminal.
      Check lathe_conv.ui, lathe_handler.py, lathe_profile.py and
      thread_data.py are all present in the config directory.

  "Cannot open ini-file" from the Generate button
      should not happen - the panel spawns its own private rs274 with the
      machine environment stripped out.  If you see it, lathe_profile.py did
      not get copied over cleanly.

  Generate says "rs274 not found"
      the panel expands G71/G70 with the real interpreter.  rs274 ships with
      LinuxCNC; make sure you launched via the linuxcnc scripts and not from
      a bare shell with no LinuxCNC environment.


-------------------------------------------------------------------------------
HOW THIS WAS CHECKED BEFORE BEING WRITTEN DOWN
-------------------------------------------------------------------------------
The config above was built and every cycle type was generated and pushed
through the real interpreter against this exact ini.  All ten parsed clean:

    od_profile  80 moves, 1 tool change      groove      56 moves
    id_profile  35 moves                     partoff     55 moves
    od_sepfin   86 moves, 2 tool changes     drilling    24 moves
    facing      26 moves                     od_thread   35 moves
    id_thread   35 moves                     joined program 181 moves, 3 changes

and the T remap was checked with a deliberately ASYMMETRIC word - T0203 came
back as tool 2 with wear 3 applied, which is big blue's Fanuc digit order and
NOT lathe-fanucy's reversed one.  That is the check that proves step 2's
toolchange.ngc actually got copied.

You can repeat that yourself from inside the config directory:

    cd ~/linuxcnc/configs/big-blue-sim          # or .../lathe-fanucy
    mkdir -p /tmp/rs274home
    printf 'G7 G18 G21\nT0203\nG0 X20 Z2\nM2\n' > /tmp/tw.ngc
    HOME=/tmp/rs274home rs274 -i big-blue-sim.ini -t tool.tbl -g /tmp/tw.ngc \
        | grep -E "SELECT_TOOL|TOOL_LENGTH"

The fake HOME is not decoration.  LinuxCNC 2.10 keeps the live tool table in a
shared memory map at $HOME/.tool.mmap, and rs274 opens it as CREATOR - it will
TRUNCATE the running machine's tool table if LinuxCNC is up.  Giving it a
throwaway HOME gives it a private one.  (The Turning tab already does this for
every rs274 it spawns; this is only for when you run rs274 by hand.)

Expect SELECT_TOOL(2), then two USE_TOOL_LENGTH_OFFSET lines where the second
differs from the first by the wear row's amount.
If you get SELECT_TOOL(3), the old lathe-fanucy toolchange.ngc is still there.

===============================================================================
