[[cha:running-emc]]

= Running LinuxCNC

== Invoking LinuxCNC

After installation, LinuxCNC starts just like any other Linux program: 
run it from the <<faq:terminal,terminal>> by issuing the command 'linuxcnc',
or select it in the Applications - CNC menu.

[[sec:config-launcher]] (((Configuration Launcher)))

== Configuration Launcher

When starting LinuxCNC from the CNC menu or from the command line without
specifying an ini file the Configuration Selector dialog starts.

The Configuration Selector dialog allows the user to pick one of their
existing configurations (My Configurations) or select a new one (from the Sample
Configurations) to be copied to their home directory. Copied configurations
will appear under My Configurations on the next invocation of the Configuration
Selector.

The Configuration Selector offers a selection of configurations
organized:

* 'My Configurations' - User configurations located in ~/linuxcnc/configs

* 'Sample Configurations' - Sample configurations, when selected are copied to
    ~/linuxcnc/configs. Once you copy a sample configuration if you use the
    launcher pick it from 'My Configurations'

** 'sim' - Configurations that include simulated hardware. These can be used
   for testing or learning how LinuxCNC works.

** 'by_interface' - Configurations organized by GUI.

** 'by_machine' - Configurations organized by machine.

** 'apps' - Applications that do not require starting linuxcnc but may be
   useful for testing or trying applications like <<cha:pyvcp,PyVCP>> or
   <<cha:glade-vcp,GladeVCP>>.

** 'attic' - Obsolete or historical configurations.


The sim configurations are often the most useful starting point for
new users and are organized around supported guis:

* axis - Keyboard and Mouse Gui
* gmoccapy - Touch Screen Gui
* gscreen - Touch Screen Gui
* low_graphics - Keyboard Gui
* tklinuxcnc - Keyboard and Mouse Gui(no longer maintained)
* touchy - Touch Screen Gui

A gui configuration directory may contain subdirectories with
configurations that illustrate special situations or the embedding
of other applications.

The by_interface configurations are organized around common, supported
interfaces like:

* general mechatronics
* mesa
* parport
* pico
* pluto
* servotogo
* vigilant
* vitalsystems

Related hardware may be required to use these configurations as
starting points for a system.


The by_machine configurations are organized around complete, known
systems like:

* boss
* cooltool
* sherline
* smithy
* tormach

A complete system may be required to use these configurations.

The apps items are typically 1) utilities that don't require
starting linuxcnc or 2) demonstrations of applications that can
be used with linuxcnc:

* info - creates a file with system information that may be useful for
  problem diagnosis.
* gladevcp - Example gladevcp applications.
* halrun  - Starts halrun in an <<faq:terminal,terminal>>.
* latency - Applications to investigate latency
** latency-test - standard test
** latency-plot - stripchart
** latency-histogram - histogram
* parport - Applications to test parport.
* pyvcp - Example pyvcp applications.
* xhc-hb04 - Applications to test an xhc-hb04 USB wireless MPG

[NOTE]
Under the Apps directory, only applications that are usefully modified
by the user are offered for copying to the user's directory.

.LinuxCNC Configuration Selector[[cap:LinuxCNC-Configuration-Selector]]

image::images/configuration-selector.png[alt="LinuxCNC Configuration Selector"]

Click any of the listed configurations 
to display specific information about it. 
Double-click a configuration or click OK 
to start the configuration. 
Select 'Create Desktop Shortcut' and then click OK 
to add an icon on the Ubuntu desktop 
to directly launch this configuration 
without showing the Configuration Selector screen. 

When you select a configuration from the Sample Configurations section, 
it will automaticly place a copy of that config in the
linuxcnc/configs directory.

== Next steps in configuration

After finding the sample configuration that uses 
the same interface hardware as your machine (or a simulator
configuration), and saving a copy to your home directory, 
you can customize it according to the details of your machine. 
Refer to the Integrator Manual for topics on configuration.

== Simulator Configurations

All configurations listed under Sample Configurations/sim
are intended to run on any computer.  No specific hardware is
required and real-time support is not needed.

These configurations are useful for studying indivdual
capabilities or options.  The sim configurations are organized
according to the graphical user interface used in the
demonstration.  The directory for axis contains the most
choices and subdirectories because it is the most tested GUI.
The capabilities demonstrated with any specific GUI may be
available in other GUIs as well.

== Configuration Resources

The Configuration Selector copies all files needed for
a configuration to a new subdirectory of ~/linuxcnc/configs
(equivalently: /home/username/linuxcnc/configs).  Each
created directory will include at least one ini file (iniflename.ini)
that is used to describe a specific configuration.

File resources within the copied directroy will typically
include one or more ini file (filename.ini) for related
configurations and a tool table file (toolfilename.tbl).
Additionally, resources may include halfiles (filename.hal,
filename.tcl), a README file for describing the directory, and
configuration specific information in a text file named after
a specific configuration (inifilename.txt).  That latter two
files are displayed when using the Configuration Selector.

The supplied sample configurations may specify HALFILEs
in the configuration ini file that are not present in the
copied directory because they are found in the system
Halfile library.  These files can be copied to the user
configuration directory and altered as required by the
user for modification or test.  Since the user configuration
directory is searched first when finding Halfiles, local
modifications will then prevail.

The Configuration selector makes a symbolic link in the
user configuration directory (named hallib) that points to
the system Halfile library.  This link simplifies copying
a library file.  For example, to copy the library core_sim.hal
file in order to make local modifications:

====
  cd ~/linuxcnc/configs/name_of_configuration
  cp hallib/core_sim.hal core_sim.hal
====

// vim: set syntax=asciidoc:


