[[cha:qtdragon-gui]](((SilverDragon)))


:ini: {basebackend@docbook:'':ini}
:hal: {basebackend@docbook:'':hal}

= SilverDragon GUI

== Introduction
SilverDragon is built with the QTVCP framework.
Much of it is based on the excellent work of others in the LinuxCNC community.
[NOTE]
SilverDragon and QtVcp are new programs added into linuxcnc.
Bugs and oddities are possible. Please test carefully when using a 
dangerous machine. Please forward reports to the forum or maillist.

.qtdragon - 3 or 4 Axis Sample
image::images/silverdragon.png["QTDragon Router",scale="25%"]

== Getting Started

If your configuration is not currently set up to use SilverDragon, 
you can change it by editing the INI file. +
In the section '[DISPLAY]' change the 'DISPLAY' line to read: +
<<sec:display-section,Display Section>>
[source,{ini}]
----
[DISPLAY]
DISPLAY = qtvcp qtdragon
----

To keep track of preferences, qtdragon looks for a preference text file. +
add the following entry under the '[DISPLAY]' heading. 
(other options are possible see the qtvcp's screenoption widget docs.) +

[source,{ini}]
----
PREFERENCE_FILE_PATH = WORKINGFOLDER/qtdragon.pref
----

You can specify where to save history/logs. +
In the section '[DISPLAY]' add: +

[source,{ini}]
----
MDI_HISTORY_FILE = mdi_history.dat
MACHINE_LOG_PATH = machine_log.dat
LOG_FILE = qtdragon.log
----

For the basicprobe routines to work the SUBROUTINE_PATH must be set properly. +
(Your path may be different then this sample) +
<<sec:rs274ngc-section,RS274ngc Section>>
[source,{ini}]
----
[RS274NGC]
SUBROUTINE_PATH = ../../../../nc_files/probe/basic_probe/macros
----

It also requires extra analog I/O pins for probing. +
Make sure this line in the HAL file has the 'num_aio=13' entry: +
The rest of the line depends on your setup and could be different and should not be changed. +
[source,{hal}]
----
loadrt motmod servo_period_nsec = [EMCMOT] SERVO_PERIOD num_joints = 4 num_aio = 13
----

SilverDragon has custom INI entries: +
[source,{ini}]
----
[TOOLSENSOR]
MAXPROBE = 40
SEARCH_VEL = 200
PROBE_VEL = 50
TOUCH = 29.7

[LASER]
X = 106.9
Y = -16.85
----

The sample configuration
'sim/qtvcp_screens/qtdragon/qtdragon_xyza.ini' is already configured to use SilverDragon as its front-end. +
There are several others, to demonstrate different machine configurations.

== Key Bindings
SilverDragon is not intended to primarily use a keyboard for machine control. +
There are several key presses that will control the machine for convenience. +
----
F1 - Estop on/off
F2 - Machine on/off
F12 - Style Editor
Home - Home All Joint of the Machine
Escape - Abort Movement
Pause -Pause Machine Movement
----

== Buttons

Buttons that are checkable will change their text colour when checked.

== Virtual Keyboard
QtDragon includes a virtual keyboard for use with touchscreens. +
To enable the keyboard, check the Use Virtual Keyboard checkbox in the Settings page. +
Clicking on any input field, such as probe parameters or tool table entries, will show the keyboard. +
It can also be shown by clicking the KEYBD button on the top of the screen, +
unless the machine is in AUTO mode. To hide the keyboard, do one of the following: +
  -  click the MAIN page button +
  - click the KEYBD button 
  - go into AUTO mode +

It should be noted that keyboard jogging is disabled when using the virtual keyboard. +

== HAL Pins
These pins are specific to the qtDragon screen, There are of course are many more HAL pins +
that must be connected for linuxcnc to function. +

If you need a manual tool change prompt, add these lines in your postgui file.
[source,{hal}]
----
net tool-change      hal_manualtoolchange.change   <=  iocontrol.0.tool-change 
net tool-changed     hal_manualtoolchange.changed  <=  iocontrol.0.tool-changed
net tool-prep-number hal_manualtoolchange.number   <=  iocontrol.0.tool-prep-number
----

These pins must be connected in the postgui file for probing to work:
[source,{hal}]
----
net xwidth           motion.analog-out-00 => qtdragon.x_width
net ywidth           motion.analog-out-01 => qtdragon.y_width
net avg_dia          motion.analog-out-02 => qtdragon.avg_diameter
net edge_angle       motion.analog-out-03 => qtdragon.edge_angle
net edge_delta       motion.analog-out-04 => qtdragon.edge_delta
net xminus           motion.analog-out-05 => qtdragon.x_minus
net yminus           motion.analog-out-06 => qtdragon.y_minus
net zminus           motion.analog-out-07 => qtdragon.z_minus
net xplus            motion.analog-out-08 => qtdragon.x_plus
net yplus            motion.analog-out-09 => qtdragon.y_plus
net xcenter          motion.analog-out-10 => qtdragon.x_center
net ycenter          motion.analog-out-11 => qtdragon.y_center
net cal_offset       motion.analog-out-12 => qtdragon.cal_offset
----

This input pin should be connected to indicate probe state: 
[source,{hal}]
----
qtdragon.hal_led_probe
----

These pins can be connected to indicate home switch states:
[source,{hal}]
----
qtdragon.hal_led_home_x
qtdragon.hal_led_home_y
qtdragon.hal_led_home_z
----

These pins are inputs related to spindle VFD indicating:
[source,{hal}]
----
qtdragon.modbus-errors
qtdragon.spindle_amps
qtdragon.spindle_fault
qtdragon.spindle_volts
----

This pin is an output to the spindle control to pause it:
[source,{hal}]
----
qtdragon.spindle_pause
----

This output pins can be connected to turn on a laser:
[source,{hal}]
----
qtdragon.btn_laser_on
----

These output pins indicate buttons that were pushed, 
they are probably of limited use:
[source,{hal}]
----
qtdragon.btn_dimensions
qtdragon.btn_gcode_edit
qtdragon.btn_home_x
qtdragon.btn_home_y
qtdragon.btn_home_z
qtdragon.btn_jog_a_slow
qtdragon.btn_jog_l_slow
qtdragon.btn_keyboard
qtdragon.btn_probe_help
qtdragon.btn_probe_mode
qtdragon.btn_select_log
qtdragon.btn_tool_add
qtdragon.btn_tool_delete
----

These pins are related to external offsets if they are used:
[source,{hal}]
----
qtdragon.eoffset_clear
qtdragon.eoffset_count
qtdragon.eoffset_enable
qtdragon.eoffset_value
qtdragon.led_eoffset_limit
----

== HAL files

The HAL files supplied are for simulation only. A real machine needs its own custom HAL files. The qtdragon screen
works with 3 or 4 axes with one joint per axis or 3 or 4 axes in a gantry configuration. (2 joints on 1 axis)

== Manual Tool Changes
If your machine requires manual tool changes, SilverDragon can pop a message box to direct you. +
You must connect the proper HAL pin in the post_gui file.
For example:
[source,{hal}]
----
net tool-change      hal_manualtoolchange.change   <=  iocontrol.0.tool-change 
net tool-changed     hal_manualtoolchange.changed  <=  iocontrol.0.tool-changed
net tool-prep-number hal_manualtoolchange.number   <=  iocontrol.0.tool-prep-number
----

== Spindle

The screen is intended to interface to a VFD, but will still work without it. There are a number of VFD drivers included 
in the linuxcnc distribution. It is up to the end user to supply the appropriate driver and HAL file connections according
to his own machine setup.

== Probing

The probe screen has been through basic testing but there could still be some minor bugs.
When running probing routines, use extreme caution until you are familiar
with how everything works. Probe routines run without blocking the main GUI. This gives the operator the opportunity 
to watch the DROs and stop the routine at any time.

[NOTE]
Probing is very unforgiving to mistakes; be sure to check settings before using.

.qtdragon - Probe Sample
image::images/silverdragon_probe.png["QTDragon Probe",scale="25%"]

== Run from Line

A gcode program can be started at any line by clicking on the desired line in the gcode display while in AUTO mode. +
It is the operator's responsibility to ensure the machine is in the desired operational mode. +
A dialog will be shown allowing the spindle direction and speed to be preset. +
The start line is indicated in the box labelled LINE, next to the CYCLE START button. +
The run from line feature can be disabled in the settings page.

[NOTE]
Linuxcnc's run-from-line is not very user friendly. eg. It does not start the spindle or confirm the proper tool.
It does not handle subroutines well. If used it is best to start on a rapid move.

== Laser buttons

The LASER ON/OFF button in intended to turn an output on or off which is connected to a small laser crosshair projector.
When the crosshair is positioned over a desired reference point on the workpiece, the REF LASER button can be pushed which then sets
the X and Y offsets to the values indicated by the LASER OFFSET fields in the Settings page and the INI file.

== Setup Tab
It's possible to load Html file (.html ending) with setup notes. They will be displayed in the setup tab. +
Some program, such as Fusion and Aspire will create this files for you.

.qtdragon - Setup Tab Sample
image::images/silverdragon_setup.png["QTDragon Setup Tab",scale="25%"]

== Styles

Nearly all aspects of the GUI appearance are configurable via the qtdragon.qss stylesheet file. The file can be edited manually or 
through the stylesheet dialog widget in the GUI. To call up the dialog, press F12 on the main window. New styles can be applied
temporarily and then saved to a new qss file, or overwrite the current qss file.

.qtdragon - Two Style Examples
image::images/style-comparison.png["QTDragon stlyes",scale="25%"]

== Screen resolution

This GUI was initially developed for a screen with 1440 x 900 resolution. It is not resizable. It will work in window mode on
any monitor with higher resolution but not on monitors with lower resolution.

== Customization

All aspects of the GUI are fully customizable through qtdesigner. This is included with the qtvcp development environment.
The extensive use of qtvcp widgets keeps the amount of required python code to a minimum, allowing relatively easy modifications.
The LinuxCNC website has extensive documentation on the installation and use of qtvcp libraries.
<<cha:qtvcp,QtVCP Overview>> for more information

.qtdragon - Customized Silverdragon
image::images/silverdragon_custom.png["QTDragon customized",scale=25]

