LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org

This page describes the proposed new tool database structure. The content was current as of 21st June 2013. Written by Andy Pugh at the Wichita Fest.

The current default tool table structure (stored in a plain-text file) is too rigid and limiting for many applications. Furthermore the method by which the tool data is conveyed to the various parts of the LinuxCNC components that need the data limits the system to no more than 56 tools.

This proposed system is too flexible and capable for most applications, but the intention is to cover all eventualities.

The minimal execution of the structure will duplicate the same capability as the existing tooltable. The maximal execution is intended to support a common, shared, tool database for a complete factory of machine tools.

The starting point is a "machineID". This is a unique machine identifier (probably actually a LinuxCNC instance identifier). This is the long-established "MACHINE" entry in the INI file.

The "spindles" table in the database maps all available spindles to machine IDs. It is assumed that any machine that needs to use a tool database has at least one, and possibly many, spindles.

The tool data is stored in an SQLite database. Access to the database is expected to be via an API that performs canned queries to return the data required. As it is a conventional database it is possible for system owners to add extra data fields as they require, as long as they leave the entries required by the LinuxCNC system available.

Some of the relations between tables may appear to be "backwards" in the hierarchy, this is to support the one-to-many mapping that the structure needs to support. For example each tool magazine has an entry for which spindle is is associated with, rather than the spindle table having a list of associated magazines.

1) The "Spindles" table.

CREATE TABLE spindles (

    spindleID     INTEGER PRIMARY KEY,
    description   TEXT,
    machineID     TEXT DEFAULT "MachineID?",
    offsetID      INTEGER,
    spindle_hrs   REAL DEFAULT 0.0

The spindleID is a unique identifier for every "spindle" that has access to the tools in the database. An optional text "description" is available to clarify things for the user, but is not used by the system. "machineID" indicates which machine the spindle is mounted on, and "active" shows whether the spindle is the currently-active one (as G-code has no way to differentiate between spindles in multi-spindle machines). "toolID" shows which tool is currently mounted in the spindle. A value of zero indicates that no tool is loaded. The "offsetID" is a key to an optional spindle offset which will be added to each tool offset. The purpose of this is to compensate for any differences in engagement depth for the same tool in multiple spindles. This is probably only relevant to situations where multiple spindles share an axis, as typically this delta would be subsumed into the axis offsets. It is intended that the "spindle_hrs" timer will be automatically updated by LinuxCNC.

2) The "Magazines" table.

The concept of a tool magazine is a new introduction in this iteration of the tool table. It is a way to indicate which subset of all tools are currently available to any particular spindle. This may refer to an actual physically-interchangable tool carousel, or could also be used to encode job-specific setups in a single carousel. In the latter case switching between tool selections only involves changing the magazine number, rather than editing the entire tool table.

CREATE TABLE magazines (

    description TEXT DEFAULT "",
    spindleID   INTEGER DEFAULT 0,
    type        mag_type DEFAULT "rotary",
    num_pockets INTEGER DEFAULT 1,
    base_pos    INTEGER

As well as encoding tool-to-spindle availability this table contains data of use to toolchanger code. The "base" position is a key to a position where the base tool can be found (q.v. "offsets")

3) The "pockets" table. This table links individual physical tools to spindles via the magazines.

CREATE TABLE pockets (

    magazineID  INTEGER DEFAULT 0,
    pocketID    INTEGER DEFAULT 0,
    pocket_offs INTEGER DEFAULT NULL,
    slot_pos    INTEGER DEFAULT NULL,
    PRIMARY KEY (magazineID, pocketID, toolID)

This structure is keyed on magazine/pocket/tool to support the possibility of the same physical tool appearing several times in a number of setups, either in the same or different physical pockets. The "slot_pos" is an offset from the base position for the physical pocket for use by such systems as rack toolchangers, or as the A-position, if for example, a rotary axis was being used as a tool turret. The pocket_offs is intended to encode the fact that individual slots in a turret-style changer on a lathe might place the same physical tool in a slightly different location.

4) The "geom_groups" table. This table groups together an arbitrary number of tool, spindle, turret or slot offsets to allow compound offsets to be defined. This allows for G-code to refer to composite offsets by a single integer value (for example in G43 Hnn or G10 L2 Pnn). The intention is that when searching for an offset by name, that the initial search will be of the ID numbers in this table, and then if the ID number is not found, then the individual offsets will be searched. Thus if the individual offsets have ID numbers distinct from the offset groups, is it possible to also access individual sub-offsets, such as wear.

CREATE TABLE geom_groups (

    groupID     INTEGER,
    description TEXT DEFAULT "",
    PRIMARY KEY (groupID, description)

The table is keyed on both groupID and description. For example 16/basic, 16/wear. The offset selection query will sum together all offsets sharing an offsetID. An unlimited number of both offsets and geometries may be defined, though it is hard to think of a use-case for more than one tool geometry set to be associated with any group.

5) The "geometries" table This table holds the non motion-related aspects of a given tool, such as the physical tool shape. The data in this table is likely to be only used by GUIs or visualisation tools.

CREATE TABLE geometries (

    description TEXT DEFAULT "",
    orientation INTEGER DEFAULT NULL,
    frontangle  REAL DEFAULT NULL,
    backangle   REAL DEFAULT NULL

6) The "offsets" table. This table contains the list of physical offsets. The numbers in this table are in the units defined in the "metadata" table.

CREATE TABLE offsets (

    description TEXT DEFAULT "",
    X           REAL DEFAULT 0.0,
    Y           REAL DEFAULT 0.0,
    Z           REAL DEFAULT 0.0,
    A           REAL DEFAULT 0.0,
    B           REAL DEFAULT 0.0,
    C           REAL DEFAULT 0.0,
    U           REAL DEFAULT 0.0,
    V           REAL DEFAULT 0.0,
    W           REAL DEFAULT 0.0,
    D           REAL DEFAULT 0.0

7) The "tools" table. This table associates a physical tool with its offsets and geometry. It also defines what T-number the tool can be called up by. One feature of this tool table schema is that it is possible to have several physical tools all of the same type, and the system (by means of sql search queries) can choose between them on the basis of such factors as least-wear, closest in the tool-chain or other factors.


    T_number	INTEGER,
    spindle_hrs REAL DEFAULT 0.0,
    distance    REAL DEFAULT 0.0,
    in_use      BOOLEAN DEFAULT 1
    max_rpm     REAL DEFAULT -1

The toolID is a unique identifier for a physical tool. It might conceivably be related to anything from the concept of "the 10mm end mill" to an RFID chip embedded in the toolholder. In the typical simple situation the ToolID? and T-number are likely to be the same integer, but the toolID can be alphanumeric if preferred. The T-number refers to a tool type, and is directly equivalent to the T number in G-code. The "geom" entry is a key to the geom_group that defines the tool offsets and shape. It is acceptable for this number to refer directly to a an "offset" if there is no requirement to store tool shape data, or support compound offsets (for example base and wear). max_rpm (added 20200224) is intended to limit the speed of unbalanced cutters. Set to zero for no rotation allowed (a probe, for example). -1 indicates no limit.

The expectation is that in the default case much of the complexity of the database structure would be concealed by the tool-table editor.

Examples: 1: Simple three-tool setup


LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
This page is read-only. Follow the BasicSteps to edit pages. | View other revisions
Last edited February 24, 2020 8:33 am by Andypugh (diff)
Published under a Creative Commons License