1  = QTvcp Libraries modules
  2  
  3  libraries are prebuilt python modules that give added features to QTvcp. +
  4  In this way you can select what features you want - yet don't have to build common ones yourself. +
  5  
  6  == STATUS
  7  
  8  STATUS is a library that sends GObject messages based on linuxcnc's current state. +
  9  It is an extension of gladevcp's GStat object. +
 10  It also has some functions to give status on such things as internal jog rate. +
 11  You connect a function call to the STATUS message you are interested in. +
 12  QTvcp will call this function when the message is sent from STATUS. +
 13  
 14  To import this modules add this python code to your import section: +
 15  [source,python]
 16  ----
 17  from qtvcp.core import Status
 18  ----
 19  To instantiate the module so you can use it add this python code to your instantiate section: +
 20  [source,python]
 21  ----
 22  STATUS = Status()
 23  ----
 24  To connect to messages use GObject syntax. For example to catch machine on and off messages, +
 25  place these commands into the INITIALIZE section: +
 26  [source,python]
 27  ----
 28          STATUS.connect('state-on', self.on_state_on)
 29          STATUS.connect('state-off', self.on_state_off)
 30  ----
 31  In this example code when linuxcnc is in machine on state the function self.on_state_on will be called. +
 32  When linuxcnc is in machine off state the function self.on_state_off will be called. +
 33  
 34  == INFO
 35  
 36  INFO is a library to collect and filters data from the INI file. +
 37  
 38  The available data and defaults: +
 39  ----
 40  inifile = linuxcnc.ini(INIPATH)
 41  MDI_HISTORY_PATH = '~/.axis_mdi_history'
 42  MACHINE_LOG_HISTORY_PATH = '~/.machine_log_history'
 43  PREFERENCE_PATH = '~/.Preferences'
 44  SUB_PATH = None
 45  PROGRAM_FILTERS = None
 46  PARAMETER_FILE = None
 47  MACHINE_IS_LATHE = False
 48  MACHINE_IS_METRIC = False
 49  MACHINE_UNIT_CONVERSION = 1
 50  MACHINE_UNIT_CONVERSION_9 = [1]*9
 51  TRAJ_COORDINATES = 
 52  JOINT_COUNT =
 53  AVAILABLE_AXES = ['X','Y','Z']
 54  AVAILABLE_JOINTS = [0,1,2]
 55  GET_NAME_FROM_JOINT = {0:'X',1:'Y',2:'Z'}
 56  GET_JOG_FROM_NAME = {'X':0,'Y':1,'Z':2}
 57  NO_HOME_REQUIRED = False
 58  
 59  JOG_INCREMENTS = None
 60  ANGULAR_INCREMENTS = None
 61  
 62  DEFAULT_LINEAR_JOG_VEL = 15 units per minute
 63  MIN_LINEAR_JOG_VEL = 60 units per minute
 64  MAX_LINEAR_JOG_VEL = 300 units per minute
 65  
 66  DEFAULT_ANGULAR_JOG_VEL = 
 67  MIN_ANGULAR_JOG_VEL = 
 68  MAX_ANGULAR_JOG_VEL = 
 69  
 70  MAX_FEED_OVERRIDE = 
 71  MAX_TRAJ_VELOCITY = 
 72  
 73  DEFAULT_SPINDLE_SPEED = 200
 74  MAX_FEED_OVERRIDE = 1.5
 75  MAX_SPINDLE_OVERRIDE = 1.5
 76  MIN_SPINDLE_OVERRIDE = 0.5
 77  
 78  # user message dialog info
 79  USRMESS_BOLDTEXT =
 80  USRMESS_TEXT =
 81  USRMESS_TYPE =
 82  USRMESS_PINNAME =
 83  USRMESS_DETAILS =
 84  USRMESS_ICON =
 85  ZIPPED_USRMESS =
 86  
 87  # embeded program info
 88  TAB_NAMES =
 89  TAB_LOCATION =
 90  TAB_CMD =
 91  ZIPPED_TABS = 
 92  
 93  MDI_COMMAND_LIST =      (heading: [MDI_COMMAND_LIST], title: MDI_COMMAND")
 94  TOOL_FILE_PATH =        (heading: [EMCIO], title:TOOL_TABLE)
 95  POSTGUI_HALFILE_PATH =  (heading: [HAL], title: POSTGUI_HALFILE)
 96  ----
 97  There are some 'helper functions' - mostly used for widget support +
 98  ----
 99  convert_metric_to_machine(data)
100  convert_imperial_to_machine(data)
101  convert_9_metric_to_machine(data)
102  convert_9_imperial_to_machine(data)
103  convert_units(data)
104  convert_units_9(data)
105  get_filter_program(fname)
106  get_qt_filter_extensions()
107  ----
108  To import this modules add this python code to your import section: +
109  [source,python]
110  ----
111  from qtvcp.core import Info
112  ----
113  To instantiate the module so you can use it in a handler file add this python code to your instantiate section: +
114  [source,python]
115  ----
116  INFO = Info()
117  ----
118  To access INFO data use this general syntax: +
119  [source,python]
120  ----
121  home_state = INFO.NO_HOME_REQUIRED
122  if INFO.MACHINE_IS_METRIC is True:
123      print 'Metric based'
124  ----
125  
126  == Action
127  
128  This library is used to command linuxcnc's motion controller. +
129  It tries to hide incidental details and add convenience methods for developers. +
130  
131  To import this modules add this python code to your import section: +
132  [source,python]
133  ----
134  from qtvcp.core import Action
135  ----
136  To instantiate the module so you can use it add this python code to your instantiate section: +
137  [source,python]
138  ----
139  ACTION = Action()
140  ----
141  To access Lcnc_Action commands use general syntax such as these: +
142  [source,python]
143  ----
144  ACTION.SET_ESTOP_STATE(state)
145  ACTION.SET_MACHINE_STATE(state)
146  
147  ACTION.SET_MACHINE_HOMING(joint)
148  ACTION.SET_MACHINE_UNHOMED(joint)
149  
150  ACTION.SET_LIMITS_OVERRIDE()
151  
152  ACTION.SET_MDI_MODE()
153  ACTION.SET_MANUAL_MODE()
154  ACTION.SET_AUTO_MODE()
155  
156  ACTION.SET_LIMITS_OVERRIDE()
157  
158  ACTION.CALL_MDI(code)
159  ACTION.CALL_MDI_WAIT(code)
160  ACTION.CALL_INI_MDI(number)
161  
162  ACTION.CALL_OWORD()
163  
164  ACTION.OPEN_PROGRAM(filename)
165  ACTION.SAVE_PROGRAM(text_source, fname):
166  
167  ACTION.SET_AXIS_ORIGIN(axis,value)
168  ACTION.SET_TOOL_OFFSET(axis,value,fixture = False)
169  
170  ACTION.RUN()
171  ACTION.ABORT()
172  ACTION.PAUSE()
173  
174  ACTION.SET_MAX_VELOCITY_RATE(rate)
175  ACTION.SET_RAPID_RATE(rate)
176  ACTION.SET_FEED_RATE(rate)
177  ACTION.SET_SPINDLE_RATE(rate)
178  
179  ACTION.SET_JOG_RATE(rate)
180  ACTION.SET_JOG_INCR(incr)
181  ACTION.SET_JOG_RATE_ANGULAR(rate)
182  ACTION.SET_JOG_INCR_ANGULAR(incr, text)
183  
184  ACTION.SET_SPINDLE_ROTATION(direction = 1, rpm = 100, number = 0)
185  ACTION.SET_SPINDLE_FASTER(number = 0)
186  ACTION.SET_SPINDLE_SLOWER(number = 0)
187  ACTION.SET_SPINDLE_STOP(number = 0)
188  
189  ACTION.SET_USER_SYSTEM(system)
190  
191  ACTION.ZERO_G92_OFFSET()
192  ACTION.ZERO_ROTATIONAL_OFFSET()
193  ACTION.ZERO_G5X_OFFSET(num)
194  
195  ACTION.RECORD_CURRENT_MODE()
196  ACTION.RESTORE_RECORDED_MODE()
197  
198  ACTION.SET_SELECTED_AXIS(jointnum)
199  
200  ACTION.DO_JOG(jointnum, direction)
201  ACTION.JOG(jointnum, direction, rate, distance=0)
202  
203  ACTION.TOGGLE_FLOOD()
204  ACTION.SET_FLOOD_ON()
205  ACTION.SET_FLOOD_OFF()
206  
207  ACTION.TOGGLE_MIST()
208  ACTION.SET_MIST_ON()
209  ACTION.SET_MIST_OFF()
210  
211  ACTION.RELOAD_TOOLTABLE()
212  ACTION.UPDATE_VAR_FILE()
213      
214  ACTION.TOGGLE_OPTIONAL_STOP()
215  ACTION.SET_OPTIONAL_STOP_ON()
216  ACTION.SET_OPTIONAL_STOP_OFF()
217  
218  ACTION.TOGGLE_BLOCK_DELETE()
219  ACTION.SET_BLOCK_DELETE_ON()
220  ACTION.SET_BLOCK_DELETE_OFF()
221  
222  ACTION.RELOAD_DISPLAY()
223  ACTION.SET_GRAPHICS_VIEW(view)
224  ----
225  There are some 'helper functions' - mostly used for this library's support +
226  ----
227  get_jog_info (num)
228  jnum_check(num)
229  ensure_mode(modes)
230  open_filter_program(filename, filter)
231  ----
232  
233  == TOOL
234  
235  This library handles tool offset file changes. +
236  Linuxcnc doesn't handle third party manipulation of the tool file well. +
237  
238  === GET_TOOL_INFO(toolnumber)
239  This will return a Python list of information on the requested tool number. +
240  
241  === GET_TOOL_ARRAY()
242  This return a single python list of python lists of tool information. +
243  This is a raw list formed from the system tool file. +
244  
245  === GET_TOOL_MODELS()
246  This will return a python tuple of two Python lists of Python lists of tool information. +
247  [0] will be real tools information +
248  [1] will be wear tool information (tool numbers will be over 10000; Fanuc style tool wear) +
249  
250  === ADD_TOOL(newtool = [-99, 0,'0','0','0','0','0','0','0','0','0','0','0','0', 0,'New Tool']) +
251  This will by default, add a black tool entry with tool number -99. +
252  You can preload the 'newtool' array with tool information. +
253  
254  === SAVE_TOOLFILE(toolarray)
255  This will parse the toolarray and save it to the file specified in the INI as the tool path. +
256  This tool array must contain all the available tools information. +
257  This array is expected to use the linuxcnc raw tool array - (doesn't have tool wear entries) +
258  it will return True if there was an error. +
259  
260  === CONVERT_TO_WEAR_TYPE(toolarray)
261  This function converts a linuxcnc raw tool array to a qtvcp tool wear array. +
262  Qtvcp's array includes entries for X and Z axis tool wear. +
263  inuxcnc covers tool wear by adding tool wear information into tool entries above 10000. +
264  This also requires remap code to add the wear offsets at tool change time.+
265  
266  === CONVERT_TO_STANDARD_TYPE(toolarray)
267  This function converts qtvcp's tool array into a linuxcnc raw tool array. +
268  Qtvcp's array includes entries for X and Z axis tool wear. +
269  linuxcnc covers tool wear by adding tool wear information into tool entries above 10000. +
270  This also requires remap code to add the wear offsets t tool change time.+
271  
272  === IS_HASH_CURRENT()
273  Each time the tool information is saved the HASH number is calculated and recorded. +
274  Calling this function will calculate the HASH number of the system tool file and +
275  if it is different will return False, otherwise returns True. +
276  Typically this function would be called regularly and if returns False, a display would be updated. +
277  
278  == aux_program_loader
279  
280  This module allows an easy way to load auxiliary programs linuxcnc often uses. +
281  To import this modules add this python code to your import section: +
282  [source,python]
283  ----
284  from qtvcp.lib.aux_program_loader import Aux_program_loader
285  ----
286  To instantiate the module so you can use it add this python code to your instantiated section: +
287  [source,python]
288  ----
289  AUX_PRGM = Aux_program_loader()
290  ----
291  
292  === HALmeter
293  Halmeter is used to display one HAL pin data.
294  load a halmeter with:
295  ----
296  AUX_PRGM.load_halmeter()
297  ----
298  
299  === classicladder user program
300  ----
301  AUX_PRGM.load_ladder()
302  ----
303  === linuxcnc status program
304  ----
305  AUX_PRGM.load_status()
306  ----
307  === HALshow configure display program
308  ----
309  AUX_PRGM.load_halshow()
310  ----
311  ==== HALscope program
312  ----
313  AUX_PRGM.load_halscope()
314  ----
315  === tooledit program
316  ----
317  AUX_PRGM.load_tooledit(TOOLEFILE_PATH)
318  ----
319  === calibration
320  ----
321  AUX_PRGM.load_calibration()
322  ----
323  === onboard/matchbox keyboard
324  ----
325  AUX_PRGM.keyboard_onboard(ARGS)
326  ----
327  == Keybindings
328  
329  This module is used to allow each keypress to control a behavior such as jogging. +
330  It's used inside the handler file to facilitate keyboard jogging etc. +
331  
332  == Messages
333  
334  This modules is used to display pop up dialog messages on the screen. +
335  These are defined in the INI file and controlled by HAL pins. +
336  'Boldtext' is generally a title. +
337  'text' is below that and usually longer. +
338  'Detail' is hidden unless clicked on. +
339  'pinname' is the basename of the HAL pins. +
340  'type' specifies whether its a yes/no, ok, or status message. +
341  Status messages will be shown in the status bar and the notify dialog. +
342  it requires no user intervention. +
343  ok messages require the user to click ok to close the dialog. +
344  ok messages have one HAL pin to launch the dialog and one to signify it's waiting 
345  for response. +
346  yes/no messages require the user to select yes or no buttons to close the dialog. +
347  yes/no messages have three hal pins - one to show the dialog, one for waiting, +
348  and one for the answer. +
349  By default it will send STATUS messages for focus_overlay anf alert sound. +
350  These will silently fail if those options are not set up. +
351  
352  Here is a sample INI code. It would be under the [DISPLAY] heading. +
353  
354  [source,{ini}]
355  ----
356  # This just shows in the status bar and desktop notify popup.
357  MESSAGE_BOLDTEXT = NONE
358  MESSAGE_TEXT = This is a statusbar test
359  MESSAGE_DETAILS = STATUS DETAILS
360  MESSAGE_TYPE = status
361  MESSAGE_PINNAME = statustest
362  
363  # This will pop up a dialog that asks a yes no question
364  MESSAGE_BOLDTEXT = NONE
365  MESSAGE_TEXT = This is a yes no dialog test
366  MESSAGE_DETAILS = Y/N DETAILS
367  MESSAGE_TYPE = yesnodialog
368  MESSAGE_PINNAME = yndialogtest
369  
370  # This pops up a dialog that requires an ok response and it shows in the status bar and
371  # the destop notify popup.
372  MESSAGE_BOLDTEXT = This is the short text
373  MESSAGE_TEXT = This is the longer text of the both type test. It can be longer then the status bar text
374  MESSAGE_DETAILS = BOTH DETAILS
375  MESSAGE_TYPE = okdialog status
376  MESSAGE_PINNAME = bothtest
377  ----
378  The screenoptions widget can automatically set up the message system. +
379  
380  == notify
381  
382  This module is used to send messages that are integrated into the desktop. +
383  it uses the pynotify library. +
384  
385  Ubuntu/Mint does not follow the standard - you can't set how long the message stays up for. +
386  I suggest fixing this with a PPA off the net +
387   https://launchpad.net/~leolik/+archive/leolik?field.series_filter=lucid +
388  
389  you can set the title, message, icon, and timeout. +
390  Notify keeps a list of all the alarm messages since starting in self.alarmpage. +
391  If you click 'show all messages' in the notify popup, it will print then to the terminal. +
392   +
393  The screenoptions widget can automatically set up the notify system. +
394  Typically STATUS messages are used to sent notify messages. +
395  
396  == preferences
397  
398  This module allows one to load and save preference data permanently to storage media. +
399   +
400  The screenoptions widget can automatically set up the preference system. +
401  qtvcp searches for the screenoption widget first and if found calls _pref_init(). +
402  This will create the preference object and return it to qtvcp to pass to all the widgets and +
403  add it to the window object attributes. In this case the preferences object would be accesable + 
404  from the handler file's initialized_ method as self.w.PREFS_ +
405  Also all widgets can have access to a specific preference file at initialization time. +
406   +
407  The screenoptions widget can automatically set up the preference file. +
408  
409  == audio player
410  
411  This module allows playing sounds using gstreamer, beep and espeak +
412  It can play sounds/music files using 'gstreamer' (non blocking) +
413  It can play sounds using the 'beep' library (currently blocks while beeping) +
414  It can speak using the 'espeak' library (non blocks while speaking) +
415  There are default alert sounds using Mint or freedesktop default sounds. +
416  You can play arbitrary sounds or even songs by specifying the path. +
417  STATUS has messages to control this module. +
418  The screenoptions widget can automatically set up the audio system. +
419  Or to import this modules manually add this python code to your import section: +
420  [source,python]
421  ----
422  from qtvcp.lib.audio_player import Player
423  ----
424  To instantiate the module so you can use it add this python code to your instantiated section: +
425  _resister_messages() function connects the audio player to the STATUS library for sounds can be played +
426  with the STATUS message system. +
427  
428  [source,python]
429  ----
430  SOUND = Player()
431  SOUND._register_messages()
432  ----
433  To play sounds using STATUS messages use these general syntax: +
434  [source,python]
435  ----
436  STATUS.emit('play-alert','LOGOUT')
437  STATUS.emit('play-alert','BEEP')
438  STATUS.emit('play-alert','SPEAK This is a test screen for Qtscreen')
439  STATUS.emit('play-sound', 'PATH TO SOUND')
440  ----
441  There are default alerts to choose from: +
442  ----
443  ERROR
444  
445  READY
446  
447  ATTENTION
448  
449  RING
450  
451  DONE
452  
453  LOGIN
454  
455  LOGOUT
456  ----
457  There are three beeps:
458  ----
459  BEEP_RING
460  
461  BEEP_START
462  
463  BEEP
464  ----
465  
466  == virtual keyboard
467  
468  This library allows you to use STATUS messages to launch a virtual keyboard. +
469  It uses Onboard or Matchbox library for the keyboard. +
470  
471  == TOOLBAR ACTIONS
472  This library supplies prebuilt submenus and actions for toolbar menus and toolbar buttons. +
473  Toolbuttons, menu and toolbar menus are built in designer and assigned actions/submenus in the handler file. +
474  
475  === Importing and Initiating
476  Here is the typical code to add to the relevant handler file sections. +
477  
478  [source,python]
479  ----
480  ############################
481  # **** IMPORT SECTION **** #
482  ############################
483  
484  from qtvcp.lib.toolbar_actions import ToolBarActions
485  
486  ###########################################
487  # **** instantiate libraries section **** #
488  ###########################################
489  
490  TOOLBAR = None
491  
492  ###################################
493  # **** HANDLER CLASS SECTION **** #
494  ###################################
495  
496  class HandlerClass:
497      ########################
498      # **** INITIALIZE **** #
499      ########################
500      # widgets allows access to  widgets from the qtvcp files
501      # at this point the widgets and hal pins are not instantiated
502      def __init__(self, halcomp,widgets,paths):
503  
504          global TOOLBAR
505          TOOLBAR = ToolBarActions(path=paths)
506  ----
507  
508  === Assigning tool actions to toolbar buttons
509  
510  [source,python]
511  ----
512      ##########################################
513      # Special Functions called from QTSCREEN
514      ##########################################
515  
516      # at this point:
517      # the widgets are instantiated.
518      # the HAL pins are built but HAL is not set ready
519      def initialized__(self):
520          TOOLBAR.configure_submenu(self.w.menuHoming, 'home_submenu')
521  
522          TOOLBAR.configure_action(self.w.actionEstop, 'estop')
523  
524          TOOLBAR.configure_action(self.w.actionQuit, 'Quit', lambda d:self.w.close())
525  
526          TOOLBAR.configure_action(self.w.actionEdit, 'edit', self.edit)
527  ----