[[cha:hal-user-interface]]

= HAL User Interface

== Introduction

Halui is a HAL based user interface for LinuxCNC, it connects HAL pins to
NML commands. Most of the functionality (buttons, indicators etc.) that
is provided by a common GUIs (axis, gscreen, etc.), is provided by HAL
pins in Halui.

The easiest way to add halui is to add the following to the [HAL]
section of the ini file.

----
[HAL]
HALUI = halui
...
----

An alternate way to invoke it is to include the following in your .hal
file. Make sure you use a correct path to your ini file.

----
loadusr halui -ini /path/to/inifile.ini
----

== MDI

Sometimes the user wants to add more complicated tasks to be performed
by the activation of a HAL pin. This is possible using the following
MDI commands method:

MDI_COMMANDs are added to the ini file in the [HALUI] section,
Example:

----
[HALUI]
MDI_COMMAND = G0 G53 Z0
MDI_COMMAND = G28
MDI_COMMAND = o<mysub>call
...
----

When halui starts it will read the MDI_COMMAND fields in the ini and
export pins from 00 to the number of MDI_COMMAND's found in the ini up
to a maximum of 64 commands.  These pins can be connected like any
hal pins.  A common method is to use buttons provided by vitual
control panels.  Example halfile connections:

----
net quill-up       <= pyvcp.quillup
net quill-up       => halui.mdi-command-00

net reference-pos  <= pyvcp.referencepos
net reference-pos  => halui.mdi-command-01

net call-mysub     <= pyvcp.callmysub
net call-mysub     => halui.mdi-command-02
----

These nets connect the halui.mdi-command-NN pins 
provided by halui:

----
$ halcmd show pin halui.mdi
Component Pins:
Owner  Type  Dir Value  Name
   10  bit   IN  FALSE  halui.mdi-command-00 <== quill-up
   10  bit   IN  FALSE  halui.mdi-command-01 <== reference-pos
   10  bit   IN  FALSE  halui.mdi-command-02 <== call-mysub
   ...
----

When a halui MDI pin is set (pulsed) true, halui will send the MDI
command defined in the ini. This will not always succeed depending on
the current operating mode (e.g., while in AUTO halui can't
successfully send MDI commands).

== Halui pin reference

All halui pins are documented in the halui man page:

----
$ man halui
----

== Example Configuration
An example sim config (configs/sim/axis/halui_pyvcp/halui.ini)
is included in the distribution.

