╔════════════════════════════════════════════════════════════════╗
║  LinuxCNC Tool Database - Installation & Auto-Launch Guide    ║
╚════════════════════════════════════════════════════════════════╝

This guide explains how to install and configure the tool database
system so that db_tool_manager (GUI) launches automatically when
LinuxCNC starts.

═══════════════════════════════════════════════════════════════════
1. INSTALLATION
═══════════════════════════════════════════════════════════════════

Step 1: Copy binaries to system location
-----------------------------------------
$ sudo cp db_tool /usr/local/bin/
$ sudo cp db_tool_manager /usr/local/bin/
$ sudo chmod 755 /usr/local/bin/db_tool
$ sudo chmod 755 /usr/local/bin/db_tool_manager

Step 2: Verify installation
----------------------------
$ db_tool --help
$ db_tool_manager

═══════════════════════════════════════════════════════════════════
2. LINUXCNC CONFIGURATION
═══════════════════════════════════════════════════════════════════

To use db_tool as your tool database provider, edit your LinuxCNC
configuration file (.ini):

Find the [EMCIO] section and modify:

  [EMCIO]
  # Change TOOL_TABLE to DB_PROGRAM
  DB_PROGRAM = db_tool /path/to/your/tool_database.dat

  # Or with custom options:
  DB_PROGRAM = db_tool --period 0.5 /path/to/tool_database.dat

  # Disable GUI auto-launch if needed:
  DB_PROGRAM = db_tool --no-launch-gui /path/to/tool_database.dat

Example full path:
  DB_PROGRAM = db_tool ~/linuxcnc_tool_data/sim_axis2_tools.dat

═══════════════════════════════════════════════════════════════════
3. AUTO-LAUNCH BEHAVIOR
═══════════════════════════════════════════════════════════════════

When LinuxCNC starts db_tool:
-----------------------------
1. db_tool loads the tool database
2. db_tool automatically launches db_tool_manager GUI
3. GUI connects to the same database file
4. GUI displays current tool and machine status in real-time

The GUI shows:
--------------
- Current tool loaded in spindle (green highlight)
- Machine running status (ON/OFF)
- Live usage time counting (updates every second)
- All tool data with full edit capabilities

═══════════════════════════════════════════════════════════════════
4. RECONNECTION BEHAVIOR
═══════════════════════════════════════════════════════════════════

If you close and reopen db_tool_manager:
-----------------------------------------
1. Launch manually: db_tool_manager /path/to/tool_database.dat
2. GUI automatically detects db_tool is running
3. Reads current tool from database header (CURRENT_TOOL, LOAD_TIME)
4. Shows machine status by checking if db_tool process exists
5. Continues real-time monitoring

The GUI ALWAYS connects to the LinuxCNC instance because:
----------------------------------------------------------
- Database file contains current state (updated by db_tool)
- GUI monitors file changes every second
- GUI checks db_tool process status
- Current tool info stored in database header

═══════════════════════════════════════════════════════════════════
5. DATABASE FILE LOCATION
═══════════════════════════════════════════════════════════════════

Recommended structure:
----------------------
~/linuxcnc_tool_data/
  ├── sim_axis2_tools.dat          # Active database
  ├── sim_axis2_tools.dat.backup   # Auto-created backup
  └── sim_axis2_tools.dat.history  # Retired tools

The GUI auto-detects database when launched without arguments:
1. Checks if db_tool is running → extracts database path
2. Falls back to ~/linuxcnc_tool_data/tool_usage.dat

═══════════════════════════════════════════════════════════════════
6. COMMAND LINE OPTIONS
═══════════════════════════════════════════════════════════════════

db_tool options:
----------------
  --launch-gui           Launch GUI on startup (DEFAULT)
  --no-launch-gui        Don't launch GUI
  --period <minutes>     Update interval (default: 1.0)
  --spindle-aware        Count only cutting time (DEFAULT)
  --no-spindle-aware     Count all time tool is loaded

db_tool_manager:
----------------
  db_tool_manager                    # Auto-detect database
  db_tool_manager /path/to/file.dat  # Specific database

═══════════════════════════════════════════════════════════════════
7. TESTING THE SETUP
═══════════════════════════════════════════════════════════════════

Test 1: Manual Launch
----------------------
$ db_tool ~/linuxcnc_tool_data/sim_axis2_tools.dat &
(GUI should launch automatically after 1-2 seconds)

Test 2: Close and Reconnect
----------------------------
1. Close the GUI window
2. Relaunch: db_tool_manager ~/linuxcnc_tool_data/sim_axis2_tools.dat
3. GUI should show current tool and machine status

Test 3: LinuxCNC Integration
-----------------------------
1. Edit your .ini file with DB_PROGRAM setting
2. Start LinuxCNC
3. GUI should appear automatically
4. Load a tool (T1 M6 G43)
5. GUI should highlight T1 in green and show live usage time

═══════════════════════════════════════════════════════════════════
8. TROUBLESHOOTING
═══════════════════════════════════════════════════════════════════

GUI doesn't launch automatically:
----------------------------------
- Check: db_tool --help (should show --launch-gui option)
- Check: which db_tool_manager (should be /usr/local/bin/)
- Check: db_tool logs in terminal for error messages
- Try: db_tool --launch-gui <database.dat> (force enable)

GUI shows wrong tool or "None":
--------------------------------
- Database file may be stale
- Click "Refresh" button to reload from disk
- Check db_tool is actually running: pgrep -x db_tool

GUI doesn't show machine status:
---------------------------------
- Machine status depends on db_tool process running
- Check: pgrep -x db_tool
- If db_tool not running, status will show "OFF"

Duplicate GUI windows:
----------------------
- db_tool checks for existing GUI before launching
- If multiple appear, check for conflicting launch scripts
- Use --no-launch-gui and launch manually

═══════════════════════════════════════════════════════════════════
9. DISABLING AUTO-LAUNCH
═══════════════════════════════════════════════════════════════════

If you prefer to launch the GUI manually:

Option 1: Use --no-launch-gui flag
-----------------------------------
  [EMCIO]
  DB_PROGRAM = db_tool --no-launch-gui ~/tools.dat

Option 2: Launch GUI manually when needed
------------------------------------------
  $ db_tool_manager ~/linuxcnc_tool_data/sim_axis2_tools.dat

═══════════════════════════════════════════════════════════════════
10. ADVANCED: MULTIPLE MACHINES
═══════════════════════════════════════════════════════════════════

If you have multiple LinuxCNC configurations:

Machine 1:
  DB_PROGRAM = db_tool ~/linuxcnc_tool_data/mill_tools.dat

Machine 2:
  DB_PROGRAM = db_tool ~/linuxcnc_tool_data/lathe_tools.dat

Each will launch its own GUI instance automatically.
The GUI detects which database to use from the db_tool instance.

═══════════════════════════════════════════════════════════════════
11. SUMMARY
═══════════════════════════════════════════════════════════════════

✓ db_tool launches GUI automatically (default behavior)
✓ GUI reconnects to LinuxCNC when reopened
✓ No manual configuration needed beyond DB_PROGRAM in .ini
✓ Current tool state persists in database file
✓ GUI always shows correct tool and machine status
✓ Multiple instances supported for multiple machines

The system is designed to "just work" - start LinuxCNC and the
GUI appears automatically, showing live tool data.

═══════════════════════════════════════════════════════════════════
