SYNOPSIS

linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

DESCRIPTION

The command linuxcncrsh is a fully-functional text-based user interface for LinuxCNC. Instead of popping up a GUI window like AXIS(1) and Touchy(1) do, it processes text-mode commands that it receives via the network. A human (or a program) can interface with linuxcncrsh using telnet(1), nc(1) or similar programs.

It cannot be stressed enough that all features of LinuxCNC are available via the linuxcncrsh interface. It can substitute a graphical UI or be started in addition to it. If your environment needs to control/monitor more than one machine from a single location, this text interface may raise your interest. Also, a speech to text interface may be easier to adapt to this text-based interface than to a graphical one.

OPTIONS

-d,--path PATH[:PATH…]

Specify a colon separated list of paths used when opening files. The search path is used for both nc files and tool table files. The default search path is set to "$HOME/nc_files" if this option is not specified.

-e,--enablepw PASSWORD

Specify the password required to enable LinuxCNC via linuxcncrsh. Note that the password is sent in the clear, so it can be read by anyone who can read packets on the network between the server and the client. Defaults to EMCTOO if omitted.

-h,--help

Prints a brief description of the command line options and exits.

-n,--name SERVER_NAME

Sets the server name that linuxcncrsh will use to identify itself during handshaking with a new client. Defaults to EMCNETSVR if omitted.

-p,--port PORT_NUMBER

Specify the port for linuxcncrsh to listen on. Defaults to 5007 if omitted.

-q,--quiet

Suppress informational messages to stdout like (dis)connecting clients and client’s enable state.

-s,--sessions MAX_SESSIONS

Specify the maximum number of simultaneous connections. Defaults to 0 (zero) (no limit) if not specified.

-w,--connectpw PASSWORD

Specify the connection password to use during handshaking with a new client. Note that the password is sent in the clear, so it can be read by anyone who can read packets on the network between the server and the client. Defaults to EMC if omitted.

In addition to the options listed above, linuxcncrsh accepts an optional special LINUXCNC_OPTION at the end:

-ini LINUXCNC_INI_FILE

LinuxCNC INI file to use. The -ini option must be preceded by two dashes: "--". Defaults to emc.ini if omitted.

RUNNING LINUXCNCRSH

To use linuxcncrsh instead of a normal LinuxCNC GUI like AXIS or Touchy, specify it in your INI file like this:

[DISPLAY]

DISPLAY=linuxcncrsh

# You can also add options like this:
# DISPLAY=linuxcncrsh -n BigMachine

To use linuxcncrsh in addition to a normal GUI, you can either 1) start it at the end of your HAL file, or 2) run it by hand in a terminal window.

To start it from HAL, add a line like this to the end of your HAL file:

loadusr linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

To start it from the terminal, run linuxcncrsh manually like this:

linuxcncrsh [OPTIONS] [-- LINUXCNC_OPTIONS]

CONNECTING

Once LinuxCNC is up and linuxcncrsh is running, you can connect to it using telnet or nc or similar:

telnet HOST PORT

HOST is the hostname or IP address of the computer running linuxcncrsh, and PORT is the port it’s listening on (5007 if you did not give linuxcncrsh the --port option).

NETWORK PROTOCOL

The linuxcncrsh server accepts TCP connections on the port specified by the --port option, or 5007 if not specified.

The client sends requests, and the linuxcncrsh server returns replies. Requests consist of a command word followed by optional command-specific parameters. Requests and most request parameters are case insensitive. The exceptions are passwords, file paths and text strings.

Requests to linuxcncrsh are terminated with line endings, any combination of one or more \r and \n characters. Replies from linuxcncrsh are terminated with the sequence \r\n.

COMMANDS

The supported commands are as follows:

hello <password> <client> [<version>]

<password> must match linuxcncrsh's connect password, or "EMC" if no --connectpw was supplied. The three arguments may not contain whitespace. If a valid password was entered the server will respond with:
HELLO ACK <ServerName> <ServerVersion>
If an invalid password or any other syntax error occurs then the server responds with:
HELLO NAK
The <version> argument is optional and defaults to "1.1". It is compared to the [EMC]VERSION field of the INI file. An older INI file version than the requested version will result in a warning.

get <subcommand> [<parameters>]

The GET command takes one of the LinuxCNC sub-commands (see SUBCOMMANDS below) and zero or more additional subcommand-specific parameters.

set <subcommand> [<parameters>]

The SET command takes one of the LinuxCNC sub-commands (see SUBCOMMANDS below) and zero or more additional parameters.

quit

The QUIT command disconnects the associated socket connection but does not change the state of the machine. You can connect later to continue work on the machine, but you must again pass HELLO and SET ENABLE if you want control the machine again.

shutdown

The SHUTDOWN command tells LinuxCNC to shutdown and disconnect the session. This command may only be issued if the HELLO has been successfully negotiated and the connection has control of the CNC (see SET ENABLE sub-command in the SUBCOMMANDS section below).
Note that LinuxCNC will only shutdown automatically if linuxcncrsh is the DISPLAY program set in the INI file.

help

The HELP command will return help information in text format over the connection. If no parameters are specified, it will itemize the available commands. If a command is specified, it will provide usage information for the specified command. Help will respond regardless of whether a HELLO has been successfully negotiated.

SUBCOMMANDS

Commands and parameters are not case sensitive, except for the password to SET ENABLE. Notes on the format of the parameters:

  • {on,off} values may be:

    • on 1, true, yes

    • off, 0, false, no

  • <spindle> is the spindle number as specified in the INI file, starting with 0 (zero) and up to the number of available spindles. A value of -1 (minus one) indicates "all spindles". An error will be emitted if <spindle> is not configured in the INI file.

  • <joint> is the joint number as specified in the INI file, starting with 0 (zero) and up to the number of available joints. A value of -1 (minus one) indicates "all joints". An error will be emitted if <joint> is not configured in the INI file.

  • <axis> is one of the letters XYZABCUVW or numbers 0 (zero) through 8 (eight) respectively. A value of -1 (minus one) indicates "all configured axes". An error will be emitted if <axis> is not configured in the INI file.

Subcommands for GET and SET are:

set abort

Abort program or MDI execution.

get abs_cmd_pos [<axis>|-1]

Returns the specified axis' commanded position in absolute coordinates. If no axis is specified, returns all axes' commanded absolute position. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

get abs_act_pos [<axis>|-1]

Returns the specified axis' actual position in absolute coordinates. If no axis is specified, returns all axes' actual absolute position. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

get angular_unit_conversion
set angular_unit_conversion {deg|rad|grad|auto}

With get, the active unit conversion is returned. With set, sets the units to be displayed. If it’s AUTO, the units to be displayed match the program units.

get axis_velocity [<axis>|-1]

Returns the current velocity of the specified axis. If no axis is specified, returns all axes' velocity. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

get brake [<spindle>|-1]
set brake {on|off} [<spindle>]

With get, the current brake setting is returned. With set, the brake is set as specified. If <spindle> is omitted, spindle 0 is selected. If <spindle> is -1, all spindles are selected.

get clients

Get the list of all connected clients and information which is in the linked and enabled state.

get comm_prot

DEPRECATED - API versioning is too complicated.
Shows the version from the HELLO.

get debug
set debug <value>

With get, the current integer value of EMC_DEBUG is returned. Note that the value of EMC_DEBUG returned is the from the UI’s INI file, which may be different than emc’s INI file. With set, sends a command to the EMC to set the new debug level, and sets the EMC_DEBUG global here to the same value. This will make the two values the same, since they really ought to be the same.

set disable [<client>|-1]

Force <client> to relinquish the enabled state. All clients will be searched and the enabled client is forced to relinquish the enabled state if <client> is not present or -1.

get display_angular_units

Returns DEG, RAD, GRAD, or CUSTOM, for the angular units that are active in the display. This is effectively the value of angularUnitConversion.

get display_linear_units

Returns INCH, MM, CM, or CUSTOM, for the linear units that are active in the display. This is effectively the value of linearUnitConversion.

get echo
set echo {on|off}

With get, any on/off parameter is ignored and the current echo state is returned. With set, sets the echo state as specified. Echo defaults to on when the connection is first established. When echo is on, all commands will be echoed upon receipt. This state is local to each connection.

get enable
set enable <passwd>|off

The session’s enable state indicates whether the current connection is enabled to perform control functions. With get, the current enable state is returned. With set, the current connection is enabled for control functions and a valid (case sensitive) password matching linuxcncrshs --enablepw (EMCTOO if not specified). A password of 'OFF (case insensitive) can not be used as a password and disables control functions for this connection.

get error

Returns the current LinuxCNC error string, or OK if no error.

get estop
set estop {on|off}

With get, returns the current estop setting as ON or OFF. With set, sets the estop as specified. E-stop ON means the machine is in the estop state and won’t run.

get feed_override
set feed_override <percent>

With get, the current feed override is returned (as a percentage of commanded feed). With set, sets the feed override as specified.

get flood
set flood {on|off}

With get, returns the current flood coolant setting. With set, sets the flood setting as specified.

set home [<joint>|-1]

Alias for joint_home.

get ini <var> <section>

Return the string value of <var> in section <section> of the INI file.

get inifile

Returns the INI file’s name set at startup.

set jog <joint>|<axis> <speed>

Jog the specified joint or axis at <speed>; sign of speed is direction. If TELEOP_ENABLE is OFF, use <joint> number. If TELEOP_ENABLE is ON, use <axis> letter (XYZABCUVW) or index 0..8.

set jog_incr <joint>|<axis> <speed> <incr>

Jog the indicated joint or axis by increment <incr> at the <speed>; sign of speed is direction. If TELEOP_ENABLE is OFF, use <joint> number. If TELEOP_ENABLE is ON, use <axis> letter (XYZABCUVW).

set jog_stop <joint>|<axis>

Stop any in-progress jog on the specified joint or axis. If TELEOP_ENABLE is OFF, use <joint> number. If TELEOP_ENABLE is ON, use <axis> letter (XYZABCUVW) or index 0..8.

get joint_fault [<joint>|-1]

Returns the fault status of the specified joint as OK or FAULT. Returns the fault status of all joints if no <joint> is specified or is -1.

set joint_home [<joint>|-1]

Homes the indicated joint or, if not specified or -1, homes all joints.

get joint_homed [<joint>|-1]

Returns the homed status of the specified joint as YES or NO. Returns the homed status of all joints if no <joint> is specified or is -1.

get joint_limit [<joint>|-1]

Returns limit status of the specified joint as OK, MINSOFT, MINHARD, MAXSOFT, or MAXHARD. Returns the limit status of all joints if no <joint> is specified or is -1.

get joint_pos [<joint>|-1]

Returns the specified joint’s actual position in absolute coordinates, excluding tool length offset. If no joint is specified or -1, returns all joints' actual absolute position.

get joint_type [<joint>|-1]

Returns LINEAR, ANGULAR, or CUSTOM for the type of the specified <joint> or for all joints if not specified or is -1.

set joint_unhome [<joint>|-1]

Unhomes the indicated <joint> or unhomes all joints if -1 or not specified. If <joint> is -2, then all joints marked as "VOLATILE_HOME" are unhomed. Note that TELEOP_ENABLE must be OFF for unhoming.

get joint_units [<joint>|-1]

Returns INCH, MM, CM, OR DEG, RAD, GRAD, or CUSTOM, for the corresponding native units of the specified <joint> or all joints if not specified or is -1. The type of the joint (linear or angular) is used to resolve which type of units are returned. The units are obtained heuristically, based on the EMC_AXIS_STAT::units numerical value of user units per mm or deg. For linear joints, something close to 0.03937 is deemed INCH, 1.000 is MM, 0.1 is CM, otherwise it’s CUSTOM. For angular joints, something close to 1.000 is deemed DEG, PI/180 is RAD, 100/90 is GRAD, otherwise it’s CUSTOM.

get joint_velocity [<joint>|-1]

Returns the specified joint’s current velocity. If no joint is specified or -1, returns all joints' velocities.

set joint_wait_homed [<joint>|-1] [<timeout>]

Wait and stall until <joint> is homed. The joint must be currently homing or be homed. The <timeout> can be used to set the wait period maximum and is 10 seconds if not specified. If <joint> is not present or -1, then it waits for all non-homed joints currently in the process of homing.
Note: executing joint_wait_homed will currently cause the entire linuxcncrsh process to wait and input will not be read or processed from any connected client while it is running. The function will run until homing is finished or a timeout happens. This function cannot be interrupted. On timeout it will print SET JOINT_WAIT NAK.

get kinematics_type

Returns the type of kinematics functions used (identity=1, serial=2, parallel=3, custom=4).

get linear_unit_conversion
set linear_unit_conversion {inch|mm|cm|auto}

With get, returns the active unit conversion. With set, sets the unit to be displayed. If it’s AUTO, the units to be displayed match the program units.

set load_tool_table <filename>

Loads the tool table specified by <filename>.

get machine
set machine {on|off}

With get, returns the current machine power setting as ON or OFF. With set, sets the machine on or off as specified.

set mdi <string>

Sends <string> as an MDI command.

get mist
set mist {on|off}

With get, returns the current mist coolant setting. With set, sets the mist setting as specified.

get mode
set mode {manual|auto|mdi}

With get, returns the current machine mode. With set, sets the machine mode as specified.

get open set open <filename>:: With get, returns the last filename opened or NONE if no file was ever opened in this session. With set, opens the named file. The <filename> is opened by linuxcncrsh, so it should either be an absolute path or a relative path. A relative path filename is searched on a list of paths as set by the -d command line option.

get operator_display

Returns the current operator display string, or OK if none.

get operator_text

With get, returns the current operator text string, or OK if none.

get optional_stop
set optional_stop {on|off}

With get, the current "optional stop on M1" setting is returned. With set, the setting is set as specified.

get override_limits
set override_limits {on|off}

With get, the override_limits setting is returned. With set, the override_limits parameter is set as specified. If override_limits is on, disables end of travel hardware limits to allow jogging off of a limit. If parameters is off, then hardware limits are enabled.

set pause

Pause program execution.
WARNING: You must SET WAIT_MODE RECEIVED in order to run pause. If you don’t then SET PAUSE will fail with an error. The reason behind this is that pausing execution will cause the internal pause command never to be done until you SET RESUME.

get plat

With get, returns the string Linux.

get pos_offset [<axis>|-1]

Returns the position offset associated with the world coordinate provided. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

set probe <x> <y> <z>

Move toward a certain location. If the probe is tripped on the way stop motion, record the position and raise the probe tripped flag.
Important: the SET PROBE command is run as an MDI command by sending and executing "G38.2 X<x> Y<y> Z<z>". This is necessary because probing requires velocity, acceleration and jerk parameters to be specified that are only available in the LinuxCNC internal canon interface. Additionally, many sanity and boundary condition checks are performed that are hard to duplicate outside of the canon interface.
The SET PROBE command can only be run in MDI mode (use SET MODE MDI). Additionally, SET PROBE never returns a SET PROBE NAK if the probe fails to make contact. However, an error is produced (use GET ERROR) and the GET PROBE_TRIPPED returns NO in that case.
If you need more control over probing, then you should send the appropriate MDI command (G38.2, G38.3, G38.4 or G38.5) via the SET MDI … command. You can still use the other probe functions to determine whether the probe value, if it tripped and clearing it.

set probe_clear

Clear the probe tripped flag.

get probe_tripped

Return the probe state - has the probe tripped since the last clear?

get probe_value

Return the current value of the probe signal.

get program

Returns the name of the currently opened program, or NONE.

get program_angular_units

Always returns DEG.

get program_codes

Returns the string for the currently active program codes.

get program_line

Returns the currently executing line of the program.

get program_linear_units

Returns INCH, MM, CM, or CUSTOM, for the corresponding linear units that are active in the program interpreter.

get program_status

Returns IDLE, RUNNING, or PAUSED.

get program_units

Synonym for program_linear_units.

get rel_act_pos [<axis>|-1]

Returns the specified axis' actual position in relative coordinates, including tool length offset. If no axis is specified, returns all axes' actual relative position. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

get rel_cmd_pos [<axis>|-1]

Returns the specified axis' commanded position in relative coordinates, including tool length offset. If no axis is specified, returns all axes' commanded relative position. The <axis> can be specified as a letter (XYZABCUVW), an index 0..8 or -1.

set resume

Resume program execution.
WARNING: You should SET WAIT_MODE DONE before you run resume. If you don’t then SET RESUME may return too early before the system is actually resumed. See also SET PAUSE.

set run [<startline>]

Runs the opened program. Runs from the beginning if no <startline> is specified and from the <startline> if specified. A <startline> of -1 runs in verify mode.

get spindle [<spindle>|-1]
set spindle {forward|reverse|increase|decrease|constant|off} [<spindle>]

With get, the current spindle state is returned as FORWARD, REVERSE, INCREASE, DECREASE, or OFF. With set, sets the spindle as specified. Note that INCREASE and DECREASE will cause a speed change in the corresponding direction until a CONSTANT command is sent. If <spindle> is omitted, spindle 0 is selected. If <spindle> is -1, all spindles are selected.

get spindle_override
set spindle_override <percent> [<spindle>|-1]

With get, the current spindle override is returned (as a percentage of commanded speed). With set, sets the spindle override as specified. If <spindle> is omitted, spindle 0 is selected. If <spindle> is -1, all spindles are selected.

set step

Step the program one line.

set task_plan_init

Initializes the program interpreter.

get teleop_enable
set teleop_enable {on|off}

With get, the current teleop mode is returned. With set, sets the teleop mode as specified.
Note on GET TELEOP_ENABLE: There is a possible race condition on activation of teleop mode just after all joints are homed. The teleop mode will automatically switch to TELEOP_ENABLE ON after homing, but that is done while the motion controller is run in the servo-thread. It may therefore take one [EMCMOT]SERVO_PERIOD time period for the automatic mode switch.
Using SET JOINT_WAIT_HOMED will automatically add a one servo-thread delay to prevent the race in normal use-cases. However, if you do not call SET JOINT_WAIT_HOMED, then you can use SET WAIT_HEARTBEAT if you just ran a homing process, ensuring the servo-thread has run at least once and updated the status.

get time

Returns the time, in seconds, from the start of the epoch. The starting time depends on the platform.

get timeout
set timeout <timeout>

With set, set the timeout for commands functions send to LinuxCNC’s core to return to <timeout> seconds. <timeout> is a real number. If it’s <= 0.0, it means wait forever. Default is 0.0, wait forever.

get timestamp
set timestamp {on|off} [{on|off}]

Enable or disable printing of a timestamp on messages sent back from the server to the user. The optional format argument selects human readable date/time format when the format is on and seconds since epoch when off or not specified.

get tool

Returns the id of the currently loaded tool.

get tool_offset
set tool_offset <tool> <length> <diameter>

With get, returns the currently applied tool length offset. With set, sets the specified <tool> to <length> and <diameter>.

get update
set update {none|auto}

DEPRECATED - Don’t use, it breaks things.
The update mode controls whether to return fresh or stale values for GET requests. When the update mode is NONE it returns stale values, when it’s AUTO it returns fresh values. Defaults to AUTO for new connections.
WARNING: Only set this to NONE if you really know what you are doing. Things will break when you do.

set update_status

DEPRECATED - You should use automatic status updates (the default).
Manually read and update the machine status as seen by linuxcncrsh. This necessary when SET UPDATE is set to NONE. WARNING: when this is required, it will break things.

get user_angular_units

Returns DEG, RAD, GRAD, or CUSTOM for the corresponding native user angular units of the LinuxCNC trajectory level. Like with linear units, this is obtained heuristically.

get user_linear_units

Returns INCH, MM, CM, or CUSTOM, for the corresponding native user linear units of the LinuxCNC trajectory level. This is obtained heuristically, based on the EMC_TRAJ_STAT::linearUnits numerical value of user units per mm. Something close to 0.03937 is deemed INCH, 1.000 is MM, 0.1 is CM, otherwise it’s CUSTOM.

get verbose
set verbose {on|off}

With get the current verbose state is returned. With set, sets the verbose state as specified. When verbose mode is on all set commands return positive acknowledgement in the form
SET <COMMAND> ACK
The verbose state is local to each connection, and starts out OFF on new connections.

set wait {received|done}

Force a wait for the previous command to be received, or done.

set wait_heartbeat [<periods>]

Wait for the motion-controller function in the servo-thread to run at least for <periods> times before returning. It sleeps [EMCMOT]SERVO_PERIOD nanoseconds between checks to ensure other processes can run unimpeded. The value of <periods> must be 1 or larger and defaults to 1 when not specified. The maximum value of <periods> depends on the value of [EMCMOT]SERVO_PERIOD. The number of periods waiting may not result in a wait longer than 1.0 seconds. This function will wait and return with a failure if it times out. If the functions times out you probably have a non-functional LinuxCNC.

get wait_mode
set wait_mode {received|done}

The wait_mode setting controls the wait after receiving a command. It can be RECEIVED (after the command was sent and received) or DONE (after the command was done). With get, the current WAIT_MODE setting is returned. With set, set the WAIT_MODE setting to the specified value.

EXAMPLE SESSION

This section shows an example session to the local machine (localhost). Bold items are typed by you, non-bold is machine output. Default values are shown for --port PORT_NUMBER (5007), --conectpw PASSWORD (EMC), and --enablepw PASSWORD (EMCTOO).

The user connects to linuxcncrsh, handshakes with the server (HELLO), enables machine commanding from this session (SET ENABLE), brings the machine out of E-stop (SET ESTOP OFF) and turns it on (SET MACHINE ON), homes all the axes, switches the machine to mdi mode, sends an MDI G-code command, then disconnects and shuts down LinuxCNC.

$ telnet localhost 5007
Trying 127.0.0.1...
Connected to 127.0.0.1
Escape character is '^]'.
hello EMC user-typing-at-telnet 1.2
HELLO ACK EMCNETSVR 1.2
set echo off
set verbose on
SET VERBOSE ACK
set enable EMCTOO
SET ENABLE ACK
set wait_mode done
SET WAIT_MODE ACK
set estop off
SET ESTOP ACK
set machine on
SET MACHINE ACK
set mode manual
SET MODE ACK
set joint_home -1
SET JOINT_HOME ACK
set joint_wait_homed -1
SET JOINT_WAIT_HOMED ACK
set mode mdi
SET MODE ACK
set mdi g0x1
SET MDI ACK
...
set shutdown
  Connection closed by foreign host.

SEE ALSO

linuxcnc(1), axis(1)