Libraries are prebuilt Python modules that give added features to QtVCP. In this way you can select what features you want - yet don’t have to build common ones yourself.

1. Status

Status is a library that sends GObject messages based on LinuxCNC’s current state. It is an extension of GladeVCP’s GStat object.

It also has some functions to report status on such things as internal jog rate.

You connect a function call to the STATUS message you are interested in, and QtVCP will call this function when the message is sent from STATUS.

1.1. Usage

  • Import Status modules
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.core import Status

  • Instantiate Status module
    Add this Python code to your instantiate section: 

    STATUS = Status()

  • Connect to STATUS messages
    Use GObject syntax.

1.2. Example

For example, you can catch machine on and off messages.

Note
 The example below shows the two common ways of connecting signals, one of them using lambda. lambda is used to strip off or manipulate arguments from the status message before calling the function. You can see the difference in the called function signature: The one that uses lambda does not accept the status object - lambda did not pass it to the function.

  • Place these commands into the [INITIALIZE] section of the Python handler file: 

    STATUS.connect('state-on', self.on_state_on)
STATUS.connect('state-off', lambda: w, self.on_state_off())

    In this example code, when LinuxCNC is in "machine on" state the function self.on_state_on will be called.
    When LinuxCNC is in "machine off" state the function self.on_state_off will be called.

  • These would call functions that looks like these: 

    def on_state_on(self, status_object):
    print('LinuxCNC machine is on')
def on_state_off(self):
    print('LinuxCNC machine is off')

2. Info

Info is a library to collect and filter data from the INI file.

2.1. Available data and defaults

LINUXCNC_IS_RUNNING
LINUXCNC_VERSION
INIPATH
INI = linuxcnc.ini(INIPATH)
MDI_HISTORY_PATH = '~/.axis_mdi_history'
QTVCP_LOG_HISTORY_PATH = '~/qtvcp.log'
MACHINE_LOG_HISTORY_PATH = '~/.machine_log_history'
PREFERENCE_PATH = '~/.Preferences'
SUB_PATH = None
SUB_PATH_LIST = []
self.MACRO_PATH = None
MACRO_PATH_LIST = []
INI_MACROS = self.INI.findall("DISPLAY", "MACRO")

IMAGE_PATH = IMAGEDIR
LIB_PATH = os.path.join(HOME, "share","qtvcp")

PROGRAM_FILTERS = None
PARAMETER_FILE = None
MACHINE_IS_LATHE = False
MACHINE_IS_METRIC = False
MACHINE_UNIT_CONVERSION = 1
MACHINE_UNIT_CONVERSION_9 = [1]*9
TRAJ_COORDINATES =
JOINT_COUNT = int(self.INI.find("KINS","JOINTS")or 0)
AVAILABLE_AXES = ['X','Y','Z']
AVAILABLE_JOINTS = [0,1,2]
GET_NAME_FROM_JOINT = {0:'X',1:'Y',2:'Z'}
GET_JOG_FROM_NAME = {'X':0,'Y':1,'Z':2}
NO_HOME_REQUIRED = False
HOME_ALL_FLAG
JOINT_TYPE = self.INI.find(section, "TYPE") or "LINEAR"
JOINT_SEQUENCE_LIST
JOINT_SYNC_LIST

JOG_INCREMENTS = None
ANGULAR_INCREMENTS = None
GRID_INCREMENTS

DEFAULT_LINEAR_JOG_VEL = 15 units per minute
MIN_LINEAR_JOG_VEL = 60 units per minute
MAX_LINEAR_JOG_VEL = 300 units per minute

DEFAULT_ANGULAR_JOG_VEL =
MIN_ANGULAR_JOG_VEL =
MAX_ANGULAR_JOG_VEL =

MAX_FEED_OVERRIDE =
MAX_TRAJ_VELOCITY =

AVAILABLE_SPINDLES = int(self.INI.find("TRAJ", "SPINDLES") or 1)
DEFAULT_SPINDLE_0_SPEED = 200
MAX_SPINDLE_0_SPEED = 2500
MAX_SPINDLE_0_OVERRIDE = 100
MIN_SPINDLE_0_OVERRIDE = 50

MAX_FEED_OVERRIDE = 1.5
MAX_TRAJ_VELOCITY

2.2. User message dialog info

USRMESS_BOLDTEXT = self.INI.findall("DISPLAY", "MESSAGE_BOLDTEXT")
USRMESS_TEXT = self.INI.findall("DISPLAY", "MESSAGE_TEXT")
USRMESS_TYPE = self.INI.findall("DISPLAY", "MESSAGE_TYPE")
USRMESS_PINNAME = self.INI.findall("DISPLAY", "MESSAGE_PINNAME")
USRMESS_DETAILS = self.INI.findall("DISPLAY", "MESSAGE_DETAILS")
USRMESS_ICON = self.INI.findall("DISPLAY", "MESSAGE_ICON")
ZIPPED_USRMESS =

self.GLADEVCP = (self.INI.find("DISPLAY", "GLADEVCP")) or None

2.3. Embedded program info

TAB_NAMES = (self.INI.findall("DISPLAY", "EMBED_TAB_NAME")) or None
TAB_LOCATION = (self.INI.findall("DISPLAY", "EMBED_TAB_LOCATION")) or []
TAB_CMD = (self.INI.findall("DISPLAY", "EMBED_TAB_COMMAND")) or None
ZIPPED_TABS =

MDI_COMMAND_LIST =      (heading: [MDI_COMMAND_LIST], title: MDI_COMMAND")
TOOL_FILE_PATH =        (heading: [EMCIO], title:TOOL_TABLE)
POSTGUI_HALFILE_PATH =  (heading: [HAL], title: POSTGUI_HALFILE)

2.4. Helpers

There are some helper functions - mostly used for widget support:

get_error_safe_setting(_self_, _heading_, _detail_, default=_None_)
convert_metric_to_machine(_data_)
convert_imperial_to_machine(_data_)
convert_9_metric_to_machine(_data_)
convert_9_imperial_to_machine(_data_)
convert_units(_data_)
convert_units_9(_data_)
get_filter_program(_fname_)
get_qt_filter_extensions()

Get filter extensions in Qt format.

2.5. Usage

  • Import Info module
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.core import Info

  • Instantiate Info module.
    Add this Python code to your instantiate section: 

    ###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

INFO = Info()

  • Access INFO data Use this general syntax: 

    home_state = INFO.NO_HOME_REQUIRED
if INFO.MACHINE_IS_METRIC is True:
    print('Metric based')

3. Action

Action library is used to command LinuxCNC’s motion controller.

It tries to hide incidental details and add convenience methods for developers.

3.1. Helpers

There are some helper functions, mostly used for this library’s support:

get_jog_info (_num_)
jnum_check(_num_)
ensure_mode(_modes_)
open_filter_program(_filename_, _filter_)

Open G-code filter program.

3.2. Usage

  • Import Action module
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.core import Action

  • Instantiate Action module
    Add this Python code to your instantiate section: 

    ###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

ACTION = Action()

  • Access ACTION commands
    Use general syntax such as these: 

    ACTION.SET_ESTOP_STATE(state)
ACTION.SET_MACHINE_STATE(state)

ACTION.SET_MACHINE_HOMING(joint)
ACTION.SET_MACHINE_UNHOMED(joint)

ACTION.SET_LIMITS_OVERRIDE()

ACTION.SET_MDI_MODE()
ACTION.SET_MANUAL_MODE()
ACTION.SET_AUTO_MODE()

ACTION.SET_LIMITS_OVERRIDE()

ACTION.CALL_MDI(code)
ACTION.CALL_MDI_WAIT(code)
ACTION.CALL_INI_MDI(number)

ACTION.CALL_OWORD()

ACTION.OPEN_PROGRAM(filename)
ACTION.SAVE_PROGRAM(text_source, fname):

ACTION.SET_AXIS_ORIGIN(axis,value)
ACTION.SET_TOOL_OFFSET(axis,value,fixture = False)

ACTION.RUN()
ACTION.ABORT()
ACTION.PAUSE()          # Toggles pause/resume
ACTION.PAUSE_MACHINE()
ACTION.RESUME()

ACTION.SET_MAX_VELOCITY_RATE(rate)
ACTION.SET_RAPID_RATE(rate)
ACTION.SET_FEED_RATE(rate)
ACTION.SET_SPINDLE_RATE(rate)

ACTION.SET_JOG_RATE(rate)
ACTION.SET_JOG_INCR(incr)
ACTION.SET_JOG_RATE_ANGULAR(rate)
ACTION.SET_JOG_INCR_ANGULAR(incr, text)

ACTION.SET_SPINDLE_ROTATION(direction = 1, rpm = 100, number = 0)
ACTION.SET_SPINDLE_FASTER(number = 0)
ACTION.SET_SPINDLE_SLOWER(number = 0)
ACTION.SET_SPINDLE_STOP(number = 0)

ACTION.SET_USER_SYSTEM(system)

ACTION.ZERO_G92_OFFSET()
ACTION.ZERO_ROTATIONAL_OFFSET()
ACTION.ZERO_G5X_OFFSET(num)

ACTION.RECORD_CURRENT_MODE()
ACTION.RESTORE_RECORDED_MODE()

ACTION.SET_SELECTED_AXIS(jointnum)

ACTION.DO_JOG(jointnum, direction)
ACTION.JOG(jointnum, direction, rate, distance=0)

ACTION.TOGGLE_FLOOD()
ACTION.SET_FLOOD_ON()
ACTION.SET_FLOOD_OFF()

ACTION.TOGGLE_MIST()
ACTION.SET_MIST_ON()
ACTION.SET_MIST_OFF()

ACTION.RELOAD_TOOLTABLE()
ACTION.UPDATE_VAR_FILE()

ACTION.TOGGLE_OPTIONAL_STOP()
ACTION.SET_OPTIONAL_STOP_ON()
ACTION.SET_OPTIONAL_STOP_OFF()

ACTION.TOGGLE_BLOCK_DELETE()
ACTION.SET_BLOCK_DELETE_ON()
ACTION.SET_BLOCK_DELETE_OFF()

ACTION.RELOAD_DISPLAY()
ACTION.SET_GRAPHICS_VIEW(view)

ACTION.UPDATE_MACHINE_LOG(text, option=None):

ACTION.CALL_DIALOG(command):

ACTION.HIDE_POINTER(state):

ACTION.PLAY_SOUND(path):
ACTION.PLAY_ERROR():
ACTION.PLAY_DONE():
ACTION.PLAY_READY():
ACTION.PLAY_ATTENTION():
ACTION.PLAY_LOGIN():
ACTION.PLAY_LOGOUT():
ACTION.SPEAK(speech):

ACTION.BEEP():
ACTION.BEEP_RING():
ACTION.BEEP_START():

ACTION.SET_DISPLAY_MESSAGE(string)
ACTION.SET_ERROR_MESSAGE(string)

ACTION.TOUCHPLATE_TOUCHOFF(search_vel, probe_vel, max_probe,
       z_offset, retract_distance, z_safe_travel, rtn_method=None, error_rtn = None)

4. Qhal

A library for HAL component interactions.

4.1. Attributes

These are the functions that can be called on the Qhal object:

newpin(name, pin type constant, pin direction constant)

returns a new QPin object

getpin(name)

returns an existing named QPin object

getvalue(name)

returns the named pin’s value, use the full component/pin name.

setp(name,value)

sets the named pin’s value, use the full component/pin name.

makeUniqueName(name)

returns an unique HAL pin name string by adding -x (a number) to the base name

exit()

kills the component

4.2. Constants

Here are the available constants:

  • HAL_BIT

  • HAL_FLOAT

  • HAL_S32

  • HAL_U32

  • HAL_IN

  • HAL_OUT

  • HAL_IO

  • HAL_RO

  • HAL_RW

4.3. References

Available object references:

  • comp the component object

  • hal the hal library object

5. QPin

A wrapper class around HAL pins

5.1. Signals

There are 3 Qt signals that the QPin pin can be connect to:

  • value_changed will call a named function with an argument of the current value

  • pinValueChanged will call a named function with arguments of the pin object and the current value

  • isDrivenChanged will call a named function with arguments of the pin object and current state when the pin is (un)connected to a driving pin

5.2. Attributes

These are the functions that can be called on a QPin object:

  • <Pin object>.get() returns the current value of the pin object

  • <Pin object>.set(X) sets the value of the pin object to the value X

  • <Pin object>.text() returns the pin name string

5.3. References

Available object references:

  • hal the hal library object

5.4. Example

Add a function that gets called when the pin state changes
from qtvcp.core import Qhal
QHAL = Qhal()

##########################################
# Special Functions called from QtVCP
##########################################

# at this point:
# the widgets are instantiated.
# the HAL pins are built but HAL is not set ready
def initialized__(self):
    self.pin_button_in = QHAL.newpin('cycle-start-in',QHAL.HAL_BIT, QHAL.HAL_IN)
    self.pin_button_in.pinValuechanged.connect(self.buttonChanged)
    self.pin_button_in.isDrivenChanged.connect(lambda p,s: self.buttonDriven(p,s))

def buttonChanged(self, pinObject, value):
    print('Pin name:{} changed value to {}'.format(pinObject.text(), value))

def buttonDriven(self, pinObject, state):
    message = 'not driven by an output pin'
    if state:
        message = 'is driven by an output pin'
    print('Pin name:{} is {}'.format(pinObject.text(), message))

6. Tool

This library handles tool offset file changes.

Warning
 LinuxCNC doesn’t handle third party manipulation of the tool file well.

6.1. Helpers

GET_TOOL_INFO(_toolnumber_)

This will return a Python list of information on the requested tool number.

GET_TOOL_ARRAY()

This return a single Python list of Python lists of tool information.

This is a raw list formed from the system tool file.

ADD_TOOL(_newtool_ = [_-99, 0,'0','0','0','0','0','0','0','0','0','0','0','0', 0,'New Tool'_])

This will return a Python tuple of two Python lists of Python lists of tool information:

  • [0] will be real tools information

  • [1] will be wear tools information (tool numbers will be over 10000; Fanuc style tool wear)

By default, adds a blank tool entry with tool number -99.
You can preload the newtool array with tool information.

DELETE_TOOLS(_toolnumber_)

Delete the numbered tool.

SAVE_TOOLFILE(_toolarray_)

This will parse the toolarray and save it to the tool file specified in the INI file as the tool path.

This tool array must contain all the available tools information.

This array is expected to use the LinuxCNC raw tool array, i.e. it does not feature tool wear entries.

It will return True if there was an error.

CONVERT_TO_WEAR_TYPE(_toolarray_)

This function converts a LinuxCNC raw tool array to a QtVCP tool array.

QtVCP’s tool array includes entries for X and Z axis tool wear.

LinuxCNC supports tool wear by adding tool wear information into tool entries above 10000.

Note
 This also requires remap code to add the wear offsets at tool change time.
CONVERT_TO_STANDARD_TYPE(_toolarray_)

This function converts QtVCP’s tool array into a LinuxCNC raw tool array.

QtVCP’s array includes entries for X and Z axis tool wear.

LinuxCNC supports tool wear by adding tool wear information into tool entries above 10000.

Note
 This also requires remap code to add the wear offsets t tool change time.

7. Path

Path module gives reference to important files paths.

7.1. Referenced Paths

PATH.PREFS_FILENAME

The preference file path.

PATH.WORKINGDIR

The directory QtVCP was launched from.

PATH.IS_SCREEN

Is this a screen or a VCP?

PATH.CONFIGPATH

Launched configuration folder.

PATH.RIPCONFIGDIR

The Run-in-place config folder for QtVCP screens.

PATH.BASEDIR

Base folder for LinuxCNC.

PATH.BASENAME

The Qt Designer files name (no ending).

PATH.IMAGEDIR

The QtVCP image folder.

PATH.SCREENDIR

The QtVCP builtin Screen folder.

PATH.PANELDIR

The QtVCP builtin VCP folder.

PATH.HANDLER

Handler file Path.

PATH.HANDLERDIR

Directory where the Python handler file was found.

PATH.XML

QtVCP UI file path.

PATH.HANDLERDIR

Directory where the UI file was found.

PATH.QSS

QtVCP QSS file path.

PATH.PYDIR

LinuxCNC’s Python library.

PATH.LIBDIR

The QtVCP library folder.

PATH.WIDGET

The QtVCP widget folder.

PATH.PLUGIN

The QtVCP widget plugin folder.

PATH.VISMACHDIR

Directory where prebuilt Vismach files are found.

Not currently used:

PATH.LOCALEDIR

Locale translation folder.

PATH.DOMAIN

Translation domain.

7.2. Helpers

There are some helper functions available:

file_list = PATH.find_vismach_files()
directory_list = PATH.find_screen_dirs()
directory_list = PATH.find_panel_dirs()

7.3. Usage

  • Import Path module
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.core import Path

  • Instantiate Path module
    Add this Python code to your instantiate section: 

    ###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

PATH = Path()

8. VCPWindow

VCPWindow module gives reference to the MainWindow and widgets.

Typically this would be used for a library (e.g., the toolbar library uses it) as the widgets get a reference to the MainWindow from the _hal_init() function.

8.1. Usage

  • Import VCPWindow module
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.qt_makegui import VCPWindow

  • Instantiate VCPWindow module+ Add this Python code to your instantiate section: 

    ###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

WIDGETS = VCPWindow()

9. Aux_program_loader

Aux_program_loader module allows an easy way to load auxiliary programs LinuxCNC often uses.

9.1. Helpers

load_halmeter()

Halmeter is used to display one HAL pin data.
Load a halmeter with: 

AUX_PRGM.load_halmeter()
load_ladder()

Load ClassicLadder PLC program: 

AUX_PRGM.load_ladder()
load_status()

Load LinuxCNC status program: 

AUX_PRGM.load_status()
load_halshow()

Load HALshow, configure display program: 

AUX_PRGM.load_halshow()
load_halscope()

Load HALscope program: 

AUX_PRGM.load_halscope()
load_tooledit()

Load Tooledit program: 

AUX_PRGM.load_tooledit(<TOOLEFILE_PATH>)
load_calibration()

Load Calibration program: 

AUX_PRGM.load_calibration()
keyboard_onboard()

Load onboard/Matchbox keyboard 

AUX_PRGM.keyboard_onboard(<ARGS>)

9.2. Usage

  • Import Aux_program_loader module
    Add this Python code to your import section: 

############################
# **** IMPORT SECTION **** #
############################

from qtvcp.lib.aux_program_loader import Aux_program_loader

  • Instantiate Aux_program_loader module
    Add this Python code to your instantiate section: 

###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

AUX_PRGM = Aux_program_loader()

10. Keylookup

Keylookup module is used to allow keypresses to control behaviors such as jogging.

It’s used inside the handler file to facilitate creation of key bindings such as keyboard jogging, etc.

10.1. Usage

Import Keylookup module

To import this modules add this Python code to your import section:

############################
# **** IMPORT SECTION **** #
############################

from qtvcp.lib.keybindings import Keylookup
Instantiate Keylookup module

To instantiate Keylookup module* so you can use it, add this Python code to your instantiate section:

###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

KEYBIND = Keylookup()
Note
Add Key Bindings
Keylookup requires code under the processed_key_event function to call KEYBIND.call().
Most handler files already have this code.

In the handler file, under the initialized function use this general syntax to create keybindings:

KEYBIND.add_call("DEFINED_KEY","FUNCTION TO CALL", USER DATA)

Here we add a keybinding for F10, F11 and F12:

##########################################
# Special Functions called from QtVCP
##########################################

# at this point:
# the widgets are instantiated.
# the HAL pins are built but HAL is not set ready
def initialized__(self):
    KEYBIND.add_call('Key_F10','on_keycall_F10',None)
    KEYBIND.add_call('Key_F11','on_keycall_override',10)
    KEYBIND.add_call('Key_F12','on_keycall_override',20)

And then we need to add the functions that get called.
In the handler file, under the KEY BINDING CALLS section, add this:

#####################
# KEY BINDING CALLS #
#####################

def on_keycall_F12(self,event,state,shift,cntrl,value):
    if state:
        print('F12 pressed')

def on_keycall_override(self,event,state,shift,cntrl,value):
    if state:
        print('value = {}'.format(value))

10.2. Key Defines

Here is a list of recognized key words. Use the quoted text.
Letter keys use Key_ with the upper or lower letter added.
e.g., Key_a and Key_A.

keys = {
    Qt.Key_Escape: "Key_Escape",
    Qt.Key_Tab: "Key_Tab",
    Qt.Key_Backtab: "Key_Backtab",
    Qt.Key_Backspace: "Key_Backspace",
    Qt.Key_Return: "Key_Return",
    Qt.Key_Enter: "Key_Enter",
    Qt.Key_Insert: "Key_Insert",
    Qt.Key_Delete: "Key_Delete",
    Qt.Key_Pause: "Key_Pause",
    Qt.Key_Print: "Key_Print",
    Qt.Key_SysReq: "Key_SysReq",
    Qt.Key_Clear: "Key_Clear",
    Qt.Key_Home: "Key_Home",
    Qt.Key_End: "Key_End",
    Qt.Key_Left: "Key_Left",
    Qt.Key_Up: "Key_Up",
    Qt.Key_Right: "Key_Right",
    Qt.Key_Down: "Key_Down",
    Qt.Key_PageUp: "Key_PageUp",
    Qt.Key_PageDown: "Key_PageDown",
    Qt.Key_Shift: "Key_Shift",
    Qt.Key_Control: "Key_Control",
    Qt.Key_Meta: "Key_Meta",
    # Qt.Key_Alt: "Key_Alt",
    Qt.Key_AltGr: "Key_AltGr",
    Qt.Key_CapsLock: "Key_CapsLock",
    Qt.Key_NumLock: "Key_NumLock",
    Qt.Key_ScrollLock: "Key_ScrollLock",
    Qt.Key_F1: "Key_F1",
    Qt.Key_F2: "Key_F2",
    Qt.Key_F3: "Key_F3",
    Qt.Key_F4: "Key_F4",
    Qt.Key_F5: "Key_F5",
    Qt.Key_F6: "Key_F6",
    Qt.Key_F7: "Key_F7",
    Qt.Key_F8: "Key_F8",
    Qt.Key_F9: "Key_F9",
    Qt.Key_F10: "Key_F10",
    Qt.Key_F11: "Key_F11",
    Qt.Key_F12: "Key_F12",
    Qt.Key_F13: "Key_F13",
    Qt.Key_F14: "Key_F14",
    Qt.Key_F15: "Key_F15",
    Qt.Key_F16: "Key_F16",
    Qt.Key_F17: "Key_F17",
    Qt.Key_F18: "Key_F18",
    Qt.Key_F19: "Key_F19",
    Qt.Key_F20: "Key_F20",
    Qt.Key_F21: "Key_F21",
    Qt.Key_F22: "Key_F22",
    Qt.Key_F23: "Key_F23",
    Qt.Key_F24: "Key_F24",
    Qt.Key_F25: "Key_F25",
    Qt.Key_F26: "Key_F26",
    Qt.Key_F27: "Key_F27",
    Qt.Key_F28: "Key_F28",
    Qt.Key_F29: "Key_F29",
    Qt.Key_F30: "Key_F30",
    Qt.Key_F31: "Key_F31",
    Qt.Key_F32: "Key_F32",
    Qt.Key_F33: "Key_F33",
    Qt.Key_F34: "Key_F34",
    Qt.Key_F35: "Key_F35",
    Qt.Key_Super_L: "Key_Super_L",
    Qt.Key_Super_R: "Key_Super_R",
    Qt.Key_Menu: "Key_Menu",
    Qt.Key_Hyper_L: "Key_HYPER_L",
    Qt.Key_Hyper_R: "Key_Hyper_R",
    Qt.Key_Help: "Key_Help",
    Qt.Key_Direction_L: "Key_Direction_L",
    Qt.Key_Direction_R: "Key_Direction_R",
    Qt.Key_Space: "Key_Space",
    Qt.Key_Any: "Key_Any",
    Qt.Key_Exclam: "Key_Exclam",
    Qt.Key_QuoteDbl: "Key_QuoteDdl",
    Qt.Key_NumberSign: "Key_NumberSign",
    Qt.Key_Dollar: "Key_Dollar",
    Qt.Key_Percent: "Key_Percent",
    Qt.Key_Ampersand: "Key_Ampersand",
    Qt.Key_Apostrophe: "Key_Apostrophe",
    Qt.Key_ParenLeft: "Key_ParenLeft",
    Qt.Key_ParenRight: "Key_ParenRight",
    Qt.Key_Asterisk: "Key_Asterisk",
    Qt.Key_Plus: "Key_Plus",
    Qt.Key_Comma: "Key_Comma",
    Qt.Key_Minus: "Key_Minus",
    Qt.Key_Period: "Key_Period",
    Qt.Key_Slash: "Key_Slash",
    Qt.Key_0: "Key_0",
    Qt.Key_1: "Key_1",
    Qt.Key_2: "Key_2",
    Qt.Key_3: "Key_3",
    Qt.Key_4: "Key_4",
    Qt.Key_5: "Key_5",
    Qt.Key_6: "Key_6",
    Qt.Key_7: "Key_7",
    Qt.Key_8: "Key_8",
    Qt.Key_9: "Key_9",
    Qt.Key_Colon: "Key_Colon",
    Qt.Key_Semicolon: "Key_Semicolon",
    Qt.Key_Less: "Key_Less",
    Qt.Key_Equal: "Key_Equal",
    Qt.Key_Greater: "Key_Greater",
    Qt.Key_Question: "Key_Question",
    Qt.Key_At: "Key_At",
    Qt.Key_BracketLeft: "Key_BracketLeft",
    Qt.Key_Backslash: "Key_Backslash",
    Qt.Key_BracketRight: "Key_BracketRight",
    Qt.Key_AsciiCircum: "Key_AsciiCircum",
    Qt.Key_Underscore: "Key_Underscore",
    Qt.Key_QuoteLeft: "Key_QuoteLeft",
    Qt.Key_BraceLeft: "Key_BraceLeft",
    Qt.Key_Bar: "Key_Bar",
    Qt.Key_BraceRight: "Key_BraceRight",
    Qt.Key_AsciiTilde: "Key_AsciiTilde",

}

11. Messages

Messages module is used to display pop up dialog messages on the screen.

These messages are:

  • defined in the INI file under the [DISPLAY] heading, and

  • controlled by HAL pins.

Use this style if you need independent HAL pins for each dialog message.

11.1. Properties

BOLDTEXT

Generally is a title.

TEXT

Text below title, and usually longer.

DETAIL

Text hidden unless clicked on.

PINNAME

Basename of the HAL pin(s).

TYPE

Specifies whether it is a (can have dialog and status options together):

  • status - shown in the status bar and the notify dialog.
    Requires no user intervention.

  • nonedialog - specifically does not show a dialog.

  • okdialog - requiring the user to click OK to close the dialog.
    OK messages have two HAL pins:

    • One HAL pin to launch the dialog, and

    • One to signify it’s waiting for response.

  • yesnodialog - requiring the user to select yes or no buttons to close the dialog.
    Yes/No messages have three HAL pins:

    • One to show the dialog,

    • One for waiting, and

    • one for the answer.

  • okcanceldialog - requiring the user to select ok or cancel
    Ok/Cancel messages have _three HAL pins    :

    • One to show the dialog,

    • One for waiting, and

    • one for the answer.

  • closepromptdialog - requiring the user to select

By default, STATUS messages for focus_overlay and alert sound will be sent when the dialog shows.
This allows screen focus dimming/blurring and sounds to be added to alerts.

11.2. HAL Pins

The HAL pin names would use these patterns:

<SCREEN BASENAME>.<PINNAME>

invoking s32 pin

<SCREEN BASENAME>.<PINNAME>-waiting

Waiting for the user’s response output bit pin

<SCREEN BASENAME>.<PINNAME>-response

The user response output bit pin

<SCREEN BASENAME>.<PINNAME>-response-s32

The user response output s32 pin

11.3. Examples

Here are sample INI message definition code blocks that would be found under the [DISPLAY] heading:

  • Status bar and desktop notify pop up message: 

    MESSAGE_BOLDTEXT = NONE
MESSAGE_TEXT = This is a statusbar test
MESSAGE_DETAILS = STATUS DETAILS
MESSAGE_TYPE = status
MESSAGE_PINNAME = statustest

  • Pop up dialog asking a Yes/No question: 

    MESSAGE_BOLDTEXT = NONE
MESSAGE_TEXT = This is a yes no dialog test
MESSAGE_DETAILS = Y/N DETAILS
MESSAGE_TYPE = yesnodialog
MESSAGE_PINNAME = yndialogtest

  • Pop up dialog asking an OK answer + Status bar and desktop notification: 

    MESSAGE_BOLDTEXT = This is the short text
MESSAGE_TEXT = This is the longer text of the both type test. It can be longer then the status bar text
MESSAGE_DETAILS = BOTH DETAILS
MESSAGE_TYPE = okdialog status
MESSAGE_PINNAME = bothtest

The ScreenOptions widget can automatically set up the message system.

12. multimessages

Messages module is used to display pop up dialog messages on the screen.

These messages are:

  • defined in the INI file under the [DISPLAY] heading, and

  • controlled by one s32 HAL pin per defined id.

  • each message is called by a corresponding number on the s32 pin.

Use this style of user messages for instance when a VFD sends error messages encoded as numbers.
It uses common invoke/response/wait HAL pins for all (per ID name) multimessage dialogs. The HAL pin names would use these patterns:

<SCREEN BASENAME>.<ID NAME>

invoking s32 pin

<SCREEN BASENAME>.<ID NAME>-waiting

Waiting for the user’s response output bit pin

<SCREEN BASENAME>.<ID NAME>-response

The user response output bit pin

<SCREEN BASENAME>.<ID NAME>-response-s32

The user response output s32 pin

12.1. Properties

TITLE

This is the title shown on the dialog window.

TEXT

Text below title, and usually longer.

DETAIL

Text hidden unless clicked on.

TYPE

Specifies type of message the user sees (can have dialog and status options together):

  • status - shown in the status bar and the notify dialog.
    Requires no user intervention.

  • nonedialog - specifically does not show a dialog.

  • okdialog - requiring the user to click OK to close the dialog.
    OK messages use two HAL pins:

    • One HAL pin to launch the dialog, and

    • One to signify it’s waiting for response.

  • yesnodialog - requiring the user to select yes or no buttons to close the dialog.
    Yes/No messages use three HAL pins:

    • One to show the dialog,

    • One for waiting, and

    • one for the answer.

By default, STATUS messages for focus_overlay and alert sound will be sent when the dialog shows.
This allows screen focus dimming/blurring and sounds to be added to alerts.

12.2. Examples

Here are sample INI message definition code blocks that would be found under the [DISPLAY] heading:

[DISPLAY]
MULTIMESSAGE_ID = VFD

MULTIMESSAGE_VFD_NUMBER = 1
MULTIMESSAGE_VFD_TYPE = okdialog status
MULTIMESSAGE_VFD_TITLE = VFD Error: 1
MULTIMESSAGE_VFD_TEXT = This is the longer text FOR MESSAGE NUMBER 1
MULTIMESSAGE_VFD_DETAILS = DETAILS for VFD error 1
MULTIMESSAGE_VFD_ICON = WARNING

MULTIMESSAGE_VFD_NUMBER = 2
MULTIMESSAGE_VFD_TYPE = nonedialog status
MULTIMESSAGE_VFD_TITLE = VFD Error: 2
MULTIMESSAGE_VFD_TEXT = This is the longer text FOR MESSAGE NUMBER 2
MULTIMESSAGE_VFD_DETAILS = DETAILS for VFD error 2
MULTIMESSAGE_VFD_ICON = INFO

13. Notify

Notify module is used to send messages that are integrated into the desktop.

It uses the pynotify library.

Ubuntu/Mint does not follow the standard so you can’t set how long the message stays up for.
I suggest fixing this with the notify-osd package available from this PPA (DISCONTINUED due to move of Ubuntu to Gnome).

Notify keeps a list of all the alarm messages since starting in self.alarmpage.
If you click 'Show all messages' in the notify popup, it will print them to the terminal.

The ScreenOptions widget can automatically set up the notify system.

Typically STATUS messages are used to sent notify messages.

13.1. Properties

You can set the:

title

Notification message title text.

message

Notification message content text.

icon

Notification message icon.

timeout

How long the message stays up for.

14. Preferences

Preferences module allows one to load and save preference data permanently to storage media.

The ScreenOptions widget can automatically set up the preference system.

QtVCP searches for the ScreenOptions widget first and, if found, calls _pref_init().
This will create the preferences object and return it to QtVCP to pass to all the widgets and add it to the window object attributes.
In this case the preferences object would be accessible from the handler file’s initialized_ method as self.w.PREFS_.

Also all widgets can have access to a specific preferences file at initialization time.

The ScreenOptions widget can automatically set up the preference file.

15. Player

This module allows playing sounds using Gstreamer, beep and Espeak.

It can:

  • play sound/music files using Gstreamer (non blocking),

  • play sounds using the beep library (currently blocks while beeping),

  • speak words using the espeak library (non blocking while speaking).

There are default alert sounds using Mint or FreeDesktop default sounds.

You can play arbitrary sounds or even songs by specifying the path.

STATUS has messages to control Player module.

The ScreenOptions widget can automatically set up the audio system.

15.1. Sounds

Alerts

There are default alerts to choose from:

  • ERROR

  • READY

  • ATTENTION

  • RING

  • DONE

  • LOGIN

  • LOGOUT

Beeps

There are three beeps:

  • BEEP_RING

  • BEEP_START

  • BEEP

15.2. Usage

  • Import Player module
    Add this Python code to your import section: 

    ############################
# **** IMPORT SECTION **** #
############################

from qtvcp.lib.audio_player import Player

  • Instantiate Player module
    Add this Python code to your instantiated section: 

    ###########################################
# **** INSTANTIATE LIBRARIES SECTION **** #
###########################################

SOUND = Player()
SOUND._register_messages()

    The _register_messages() function connects the audio player to the STATUS library so sounds can be played with the STATUS message system.

15.3. Example

To play sounds upon STATUS messages, use these general syntaxes:

STATUS.emit('play-alert','LOGOUT')
STATUS.emit('play-alert','BEEP')
STATUS.emit('play-alert','SPEAK This is a test screen for Q t V C P')
STATUS.emit('play-sound', 'PATH TO SOUND')

16. Virtual Keyboard

This library allows you to use STATUS messages to launch a virtual keyboard.

It uses Onboard or Matchbox libraries for the keyboard.

17. Toolbar Actions

This library supplies prebuilt submenus and actions for toolbar menus and toolbar buttons.

Toolbuttons, menu and toolbar menus are:

  • built in Qt Designer, and

  • assigned actions/submenus in the handler file.

17.1. Actions

estop
power
load
reload
gcode_properties
run
pause
abort
block_delete
optional_stop
touchoffworkplace
touchofffixture
runfromline
load_calibration
load_halmeter
load_halshow
load_status
load_halscope
about
zoom_in
zoom_out
view_x
view_y
view_y2
view_z
view_z2
view_p
view_clear
show_offsets
quit
system_shutdown
tooloffsetdialog
originoffsetdialog
calculatordialog
alphamode
inhibit_selection
show_dimensions

Toggles dimensions display.

17.2. Submenus

recent_submenu
home_submenu
unhome_submenu
zero_systems_submenu
grid_size_submenu

Menu to set graphic grid size

17.3. Usage

Here is the typical code to add to the relevant handler file sections:

############################
# **** IMPORT SECTION **** #
############################

from qtvcp.lib.toolbar_actions import ToolBarActions

###########################################
# **** instantiate libraries section **** #
###########################################

TOOLBAR = ToolBarActions()

17.4. Examples

  • Assigning Tool Actions To Toolbar Buttons 

    ##########################################
# Special Functions called from QtVCP
##########################################

# At this point:
#   * the widgets are instantiated,
#   * the HAL pins are built but HAL is not set ready.
def initialized__(self):
    TOOLBAR.configure_submenu(self.w.menuHoming, 'home_submenu')
    TOOLBAR.configure_action(self.w.actionEstop, 'estop')
    TOOLBAR.configure_action(self.w.actionQuit, 'quit', lambda d:self.w.close())
    TOOLBAR.configure_action(self.w.actionEdit, 'edit', self.edit)
    # Add a custom function
    TOOLBAR.configure_action(self.w.actionMyFunction, 'my_Function', self.my_function)

  • Add a custom toolbar function: 

    #####################
# GENERAL FUNCTIONS #
#####################

def my_function(self, widget, state):
    print('My function State = ()'.format(state))

18. Qt Vismach Machine Graphics library

Qt_vismach is a set of Python functions that can be used to create and animate models of machines.

Vismach:

  • displays the model in a 3D viewport

  • animates the model parts as the values of associated HAL pins change.

This is the Qt based version of the library, there is also a tkinter version available in LinuxCNC.

The Qt version allows embedding the simulation in other screens.

18.1. Builtin Samples

There are included sample panels in QtVCP for:

  • a 3-Axis XYZ mill,

  • a 5-Axis gantry mill,

  • a 3-Axis mill with an A axis/spindle, and

  • a scara mill.

Most of these samples, if loaded after a running LinuxCNC configuration (including non-QtVCP based screens), will react to machine movement.
Some require HAL pins to be connected for movement.

From a terminal (pick one):

qtvcp vismach_mill_xyz
qtvcp vismach_scara
qtvcp vismach_millturn
qtvcp vismach_5axis_gantry

18.2. Primitives Library

Provides the basic building blocks of a simulated machine.

Collection

A collection is an object of individual machine parts.

This holds a hierarchical list of primitive shapes or STL objects that operations can be applied to.

Translate

This object will perform an OpenGL translation calculation on a Collection object.

Translation refers to moving an object in straight line to a different position on screen.

Scale

This object will perform an OpenGL scale function on a collection object.

HalTranslate

This object will perform an OpenGL translation calculation on a Collection object, offset by the HAL pin value.

Translation refers to moving an object in straight line to a different position on screen.

You can either:

  • read a pin from a component owned by the Vismach object, or

  • read a HAL system pin directly if the component argument is set to None.

Rotate

This object will perform an OpenGL rotation calculation on a Collection object.

HalRotate

This object will perform an OpenGL rotation calculation on a Collection object, offset by the HAL pin value.

You can either:

  • read a pin from a component owned by the vismach object, or

  • read a HAL system pin directly if the component argument is set to None.

HalToolCylinder

This object will build a CylinderZ object that will change size and length based on loaded tool dimensition (from the tool table)

It reads the halui.tool.diameter and motion.tooloffset.z HAL pins.

Example from mill_xyz sample:

toolshape = CylinderZ(0)
toolshape = Color([1, .5, .5, .5], [toolshape])
tool = Collection([
    Translate([HalTranslate([tooltip], None, "motion.tooloffset.z", 0, 0, -MODEL_SCALING)], 0, 0, 0),
    HalToolCylinder(toolshape)
])
Track

Move and rotate an object to point from one capture() 'd coordinate system to another.

Base object to hold coordinates for primitive shapes.

CylinderX, CylinderY, CylinderZ

Build a cylinder on the X, Y or Z axis by giving endpoint (X, Y, or Z) and radii coordinates.

Sphere

Build a sphere from center and radius coordinates.

TriangleXY, TriangleXZ, TriangleYZ

Build a triangle in the specified plane by giving the corners Z coordinates for each side.

ArcX

Build an arc by specifying

Box

Build a box specified by the 6 vertex coordinates.

BoxCentered

Build a box centered on origin by specifying the width in X and Y, and the height in Z.

BoxCenteredXY

Build a box centered in X and Y, and running from Z=0, by specifying the width in X and Y, and running up or down to the specified height in Z.

Capture

Capture current transformation matrix of a collection.

Note
 This transforms from the current coordinate system to the viewport system, NOT to the world system.
Hud

Heads up display draws a semi-transparent text box.

Use:

  • HUD.strs for things that must be updated constantly,

  • HUD.show("stuff") for one-shot things like error messages.

Color

Applies a color to the parts of a collection.

AsciiSTL, AsciiOBJ

Loads a STL or OBJ data file as a Vismach part.

18.3. Usage

Import a simulation

Here is how one might import the XYZ_mill simulation in a QtVCP panel or screen handler file.

############################
# **** IMPORT SECTION **** #
############################

import mill_xyz as MILL
Instantiate and use the simulation widget

Instantiate the simulation widget and add it to the screen’s main layout:

##########################################
# Special Functions called from QtVCP
##########################################

# At this point:
#   * the widgets are instantiated,
#   * the HAL pins are built but HAL is not set ready.
def initialized__(self):
    machine = MILL.Window()
    self.w.mainLayout.addWidget(machine)

18.4. More Information

More information on how to build a custom machine simulation in the Qt Vismach chapter.