Mach4 CNC Controller

Screen Editing Guide

10/26/22
Copyright © 2014 Newfangled Solutions, Artsoft USA, All Rights Reserved

The following are registered trademarks of Microsoft Corporation: Microsoft, Windows. Any other trademarks
used in this manual are the property of the respective trademark holder.

Table of Contents
Chapter 1Introduc on............................................................................................................................................ 4
1.1About this Manual......................................................................................................................................... 4
1.2A Note About Lua........................................................................................................................................... 4
1.3Where is My Screen?..................................................................................................................................... 4
Chapter 2The Editor................................................................................................................................................ 5
2.1Open the Editor............................................................................................................................................. 5
2.2Save the Current Screen................................................................................................................................ 5
2.3Load a New Screen........................................................................................................................................ 5
2.4Close the Editor............................................................................................................................................. 5
Chapter 3General Layout........................................................................................................................................ 6
3.1Menu Bar....................................................................................................................................................... 6
3.1.1Screen Menu........................................................................................................................................... 6
3.2Tool Bar.......................................................................................................................................................... 6
3.3Controls......................................................................................................................................................... 7
3.4Screen Tree Manager..................................................................................................................................... 9
3.5Proper es and Events..................................................................................................................................10
3.6Update and Modify Event Scripts.................................................................................................................12
3.6.1Update Event Script..............................................................................................................................12
3.6.2Modify Event Script...............................................................................................................................12
Chapter 4Create a Basic Screen............................................................................................................................12
4.1Create A New Blank Screen.......................................................................................................................... 13
4.2Tab Controls................................................................................................................................................. 14
4.3GCode Window............................................................................................................................................16
4.4Digital Readouts (DROs)............................................................................................................................... 17
4.5Aligning Controls..........................................................................................................................................18
4.6Bu ons........................................................................................................................................................20
 4.7LEDs.............................................................................................................................................................23
4.8Edi ng Completed Screen............................................................................................................................ 24
4.9Sta c Text Controls......................................................................................................................................26
4.10Sliders........................................................................................................................................................27
4.11Manual Jog Bu ons...................................................................................................................................28
4.12Manual Data Input (MDI)...........................................................................................................................29
4.13Completed Screen...................................................................................................................................... 30
Chapter 5Screen Scripts........................................................................................................................................32
5.1Screen Script Overview................................................................................................................................32
5.1.1Screen Load Script ................................................................................................................................32
5.1.2Screen Unload Script.............................................................................................................................32
5.1.3PLC Script.............................................................................................................................................. 32
5.1.4 Signal Script.......................................................................................................................................... 32
5.1.5Timer Script .......................................................................................................................................... 32
5.1.6Control Event Scripts.............................................................................................................................32
5.2Debugging ...................................................................................................................................................33
5.2.1Debug Prepara on................................................................................................................................ 33
5.2.2Star ng The Debug Session................................................................................................................... 33
5.2.3Ending The Debug Session.................................................................................................................... 34
 Chapter 1 Introduc on
About this Manual
This manual is intended to provide beginners with enough informa on to start building and edi ng their own
screens and provide a quick reference for advanced users. A er a concise descrip on of all the controls
available in the hobby and industrial versions of Mach4, there is a tutorial for beginner users. This tutorial will
teach you how to use the most common controls and help you build a founda on on which you can construct
more complex screens.

A Note About Lua

Although many, if not all, screen controls can be augmented with the use of Lua scripts, however, Lua
programming is outside the scope of this manual. If you are unfamiliar with the Lua scrip ng language, please
reference the Mach4 Scrip ng manual for further informa on. When applicable, this manual will indicate
where Lua scripts can be used with various controls.

Where is My Screen?
The screen files (extension .set) are stored in the …/Mach4/Screens/ folder. This is the only place Mach4 will
look for the defined screen. Place your screen file in this folder to access it from Mach4.
The Editor
Open the Editor
Open the screen editor by naviga ng to the “Operator” Menu and selec ng “Edit Screen”. The screen editor will
be launched in the current Mach4 window.

Save the Current Screen

You can save your current edits by selec ng the “Save Screen” op on in the “Screen” Menu. Another op on is
to select the “Save Screen As” op on to save your screen with a different name. The screen will also ask to save
any changes when you close the editor.

Load a New Screen

A new screen cannot be loaded from the screen editor interface. Before entering the editor, you can load your
preferred screen from Mach4’s “View” menu (See the Mach4 Opera on Guide for more informa on on
Mach4’s menu bar and controls).

Close the Editor

To exit the editor, follow the same procedure as opening it. Unselect the “Edit Screen” op on, you can do this
by clicking on it in the menu.
General Layout
Menu Bar
The menu bar spans the top of the Mach4 window. You will no ce that in the editor it is slightly different than
the standard Mach4 menu bar. Two items have been added that are specific to the editor, “Screen” and
“Format”. You can use these to menu items to do things like add controls or images, or align mul ple screen
items to each other.

Screen Menu
o Save Screen: Click on this item to save the current screen. If no changes have been made, it will be
grayed out.

o Save Screen As: Click on this to save the current screen with a different name.

o Manage Images: Use the manage images tool to add or remove images from the screen set. You can
use these images as backgrounds, image bu ons or sta c images.

o Add: You can use the add menu item to add controls to the screen, an alterna ve to using the tool bar.

Tool Bar
The tool bar is where you select the controls to add to the screen. There are a variety of controls from bu ons
to DRO’s and panels. Figures 3.2-1 and 3.2-2 show you the controls available in the Hobby and Industrial
versions of Mach4. As you can see Industrial includes a few extra controls. Clicking on a control icon adds it to
the currently selected container in the screen.

Figure 31 Mach4 Hobby Screen Editor Tool Bar

Figure 32 Mach4 Industrial Screen Editor Tool Bar

Controls

Control Placement Type: Select how you want to place controls on the screen, “Free
Hand” or “Snap to Grid”.
Grid Size: Set the grid size for “Snap to Grid” control placement type.

Delete: Removes the currently selected control from the screen.

Add Page: Adds a page to tabs or the screen. Must have a tab control or screen
selected to enable this tool.
Group: Groups are containers for mul ple controls, useful for keeping related
controls together.
Bu on: You can use bu ons to trigger events in Mach4 or program them with Lua
scripts
Image Bu on: Func onally the same as the standard bu on. Instead of only
displaying text, you can use images to create custom bu ons. You must first add the
images to the screen with the image manager.
Toggle Bu on: Toggle bu ons trigger events the same as a standard bu on, but they
stay on when clicked and turn off when clicked again. You can use these to turn on
and off inputs or outputs, or run custom Lua scripts.
DRO: Digital Read Outs (DRO) are used to display numerical informa on from a
variety of sources including axis posi ons and registers.
LED: You can use LEDs to show the state of inputs, outputs and more.

G-Code: The currently loaded G-Code file will be shown in this control.

Toolpath: When you load a program the toolpath is generated and displayed in the
toolpath control.
Sta c Text: Used to display text, sta c or from another source, for example Mach
status, registers, and other variables.
Text Box: You can use text boxes to get alphanumerical text input from users.

Sta c Image: Sta c images are pictures on the screen, you can display any image
that has been added to the screen with the image manager.
Tab Control: A tab control can contain one or more tabs, or pages, to display
different sets of controls or informa on to the user. Add tabs to a tab control with
the “Add Page” tool bu on.
Slider: Sliders provide you with an easy way to adjust a value, for example feedrate
or rapid override.
Gauge: You can use gauges to display the status of variables that have an upper and
lower limit, for example spindle override.
MDI: A Manual Data Input (MDI) control allows you to manually enter GCode to be
executed.
Line: You can use lines to visually separate sec ons of the screen.
*Controls only ac ve in Mach4 Industrial
 Screen Tree Manager
On the le side of the screen editor window you will find the “Screen Tree Manager”. All of the screen elements
are displayed in a tree according to their hierarchy in the screen. Each page in the screen will be listed by its
name, by default there is one page tled “Default”, with all the controls contained within it shown under it in
the tree. If you don’t see controls listed under the page name either there are no controls to show or you need
to click on the box with the “+” to expand the tree (“-“ to collapse it). Containers such as tabs or groups will also
have a branch in the tree that shows the controls contained within.

Figure 33 Screen Tree Manager

A right click on any control in the screen tree manager displays a menu allowing you to delete, cut, copy or
paste the object. For certain containers, there is also the op on to import or export. For example, this allows
you to easily transfer a tab with all its contents to a new screen.
 Proper es and Events
On the le side of the editor, under the screen tree manager, you will find the proper es window. This window
displays all the editable proper es of the currently selected control.

Figure 34 Proper es

There are two views of proper es, selectable at the top of the proper es window. The default view, shown in
figure 3-4 is the property view. This view shows you basic proper es such as name, dimensions, posi on,
enable type, value, label, etc. The other view is the event view, selectable by clicking on the lightning bolt at the
top of the window, figure 3-5.
 Figure 35 Event Proper es

The event proper es window is where you can define the events, or ac ons, of bu ons and other controls.
Figure 3-5 shows the events for a standard bu on. For the bu on control, there are mul ple events to choose
from. The first two op ons, “Le Down Ac on” and “Le Up Ac on”, give you a list of ac ons to choose from.
These are predefined func ons in Mach4, opening the drop-down menu will show you a list of all the ac ons to
choose from. A le -down event is triggered when the le mouse bu on is pushed on the bu on, when the le
mouse bu on is released the le -up ac on is triggered. In Figure 3-5 you can see the ac on “Feed Hold” is
assigned to the “Le Up Ac on”. So, when the bu on is released, feed hold will be ac vated.

If you desire a more complex ac on, the “Le Up Script”, “Le Down Script” and “Clicked Script” op ons allow
you to add a Lua script that will be executed on that event. For more informa on on Lua scrip ng please see
the Lua Scrip ng Manual.

Many controls have events that can increase the func onality of your screen. Explore each control and see
what can be done.
 Update and Modify Event Scripts
Some controls, such as DROs, sta c text labels, and text entry boxes have update and (possibly) modify event
script(s) associated with them. These allow for the contents of the control to differ from the value that drives
them. For example, a DRO may be driven from an encoder register. But the register's count value may not be
in a form that is presentable to the operator as they may wish to see a measurement unit.

Update Event Script

The update event script is run whenever the system updates the control's value. If the update script exists, the
script must return the (possibly modified) value. The value from the system is passed as the first argument to
the script and the control's screen name is passed as the second argument.

Modify Event Script

The modify event scripts is run whenever the user modifies the control's contents. If the modify script exists,
the script must return the (possibly modified) value. The value that the user put in the control is passed as the
first argument to the script and the control's screen name is passed as the second argument.

Create a Basic Screen

Some mes it makes sense to start with an exis ng screen, like wx4.set, where all the controls are already
placed. Some mes a screen should be created from scratch, if it is going to be something completely different.
For clarity, this manual will be showing you examples on a blank screen. There are a few screens included with
Mach4, including a blank one. To start building your own screen copy one of these stock screens and start
building.

NOTE! If you modify one of the stock screens and don’t save it under a different name, it will be over wri en
the next me you update Mach4 and any edits you’ve made will be lost. Always create your screens with a
different file name.
 Create A New Blank Screen

Figure 46 Mach4 Screen Folder

To Follow along with this manual, create a copy of the Blank.set screen set, see figure 4-1. Name it something
memorable (for this manual I will be using EditorManual.set) and then start up Mach4 with the profile you want
to use. When Mach4 finishes loading go to the “View” menu and select “Load Screen”. Pick your new blank
screen from the folder and open it. The new screen will load and you will be returned to the Mach4 window.
The Mach4 screen will be completely blank, don’t panic, this is a blank screen set so that is normal.

Now we can start adding controls! Open the screen editor (go to the “Operator” menu and select “Edit
Screen”). With the editor open the first thing to do is set up the screen size. Select the screen name from the
screen tree manager and the screen proper es will be displayed in the proper es window, figure 4-2.
 Figure 47 Screen Proper es

In the “Proper es” window you will see two op ons to set the size, “Design Width” and “Design Height”. The
blank screen set is set up for a 1024x768 screen. These values are in pixels and should be set to match the
resolu on of your desired screen. If this height and width does not match the screen then the Mach4 window
will be stretched to fit, contents included, so your screen may not display exactly as intended.

Now you can start adding controls to the screen. You’ll no ce when the screen is selected as in figure 4-2 most
of the controls in the tool bar will be unavailable, this is because controls need to be added to containers. There
are three container types available, pages, groups and tabs. In the blank screen, there is already a page added
for you, named “Default”. You can select by clicking on default in the screen tree manager or by clicking on
blank space in the main window. When the default page is selected all the controls in the tool bar will ac vate.

Tab Controls
You want to have a couple different views in this screen so start by adding a tab control. The new tab control
will be added to the top le corner of the page and you’ll see the control added to the screen tree manager
with a single tab. In figure 4-3 you can see the tab control named “nob” and the single tab named “nbp”. These
names do have some meaning, “nob” is short for notebook and “nbp” short for notebook page. These are the
programming names for this type of control.
 Figure 48 Add a Tab Control

Now let’s make the tab control fill the top half of the screen, select “nob” on the screen tree manager and set
the height to 500 and the width to 1004. No ce the tool bar, there are only two op ons available, “Delete” and
“Add Page”. Click the add page bu on to add another tab to the control. Click on the tabs (“nbp” and “nbp(1)”)
in the screen tree manager and change the label proper es to “GCode” and “Tool Path”, see figure 4-4.
 Figure 49 Renamed Tabs

The label is the displayed name of the control, this is true for tabs, bu ons, sta c text, etc. The name field is the
name that will be displayed in the screen tree manager and the name that can be used to access the control
from a Lua script.

GCode Window
Now let’s add a GCode window to the new “GCode” tab, and a tool path display to the “Tool Path” tab. Click on
the GCode tab, or select “nbp” from the screen tree manager, then click on the “Add GCode Display” bu on in
the toolbar. A window will appear at the top le corner of the tab. If the new control appears at the top corner
of the page, or behind the tab, then you had the page selected and not the desired tab. Now resize the GCode
display to fit the tab. Hover your mouse over the bu on right corner and the pointer should change to a double
headed and angled arrow. Click and drag the corner to set the desired size. Repeat these steps with a tool path
display on the tool path tab.
 Figure 410 Tool Path Display

Digital Readouts (DROs)

Next let’s add some bu ons and DROs to the bo om of the screen. Select the page (either in the main window
or from the screen tree manager) and add a DRO. it will be added at the top le corner of the page, behind the
tab control. The easiest way to move it is to select it in the screen tree manager and type in the desired posi on
or some posi on (0,0 for example) where you can see the control to click and drag it to posi on. For this
example, we know we want the values we want, Top = 518, Le = 514, Height = 65, Width = 500. At the same
me change the border to “Sta c”. Now to add two more. Right click on the DRO and select Copy, the right click
again and select Paste. Then right click and select Paste again, there are now 3 DROs all in the same place. You
can move them around by clicking and dragging them, by selec ng them and then holding control and using the
arrow keys on the keyboard, or typing in posi ons. Just roughly drag the two new ones so they are stacked as in
figure 4-6. They do not need to be perfectly aligned, you will fix that in the next step.
 Figure 411 DROs Added

Aligning Controls
Now, you can align them. Move the lowest DRO close to the bo om of the screen and then hold control and
select the other two DROs, middle and then top. The order of selec on is important! Now go to the “Format”
menu and move the mouse over “Spacing…” and then select ver cal. The three DROs will be evenly spaced
keeping the top and bo om DROs in their current posi on. Next go back to the “Format” menu and move your
mouse over the “Align…” op on and select “Rights”. This will align the right edges of all the selected control to
the LAST selected control, this is the reason the selec on order is important. You should be le with a screen
that looks like figure 4-7. Next you will add some func onality to the DROs.
 Figure 412 Aligned DROs

Click on the first DRO, we will make this the X axis posi on DRO. In the property window find the item named
DRO Code and open the drop-down menu, select “X Mul ple Pos”. The middle one should be set to “Y Mul ple
Pos” and the bo om one “Z Mul ple Pos”. The mul ple posi on op on allows you to display absolute, machine
and distance-to-go data in the same DRO. Later you will add bu ons to toggle between these func ons. Right
now, let’s add some labels so we don’t forget which is which. Follow the same basic procedure as for adding the
DROs but add sta c text controls instead. Use the format tools to align the labels with the DROs. You should
end up with a screen that looks like figure 4-8.
 Figure 413 Sta c Text Labels

Bu ons
To make this screen useful you need to add a few bu ons to load a program, enable, start and stop a program,
etc. Let’s start with the enable bu on. We’ll make this a large toggle bu on on the bo om le side of the
screen. Select the default page and click “Add Toggle Bu on” on the tool bar. Once again it will show up on the
screen at the top le corner under our tab control. Move the control to Top = 701, Le = 18 and resize it to
Height = 50, Width = 400. You also want to change the test displayed on the bu on and the color. For toggle
bu ons, there are two states, up and down. For the enable bu on you want the “Text Up” to be “Enable” and
“Text Dn” to be “Disable”. Change the “Bu on Color Up” property to green and the “Bu on Color Dn” to red. To
change the color, click on the property in the property window and then select the color from the pale e.
Figure 4-9 shows the proper es se ngs for the new bu on.
 Figure 414 Enable Toggle Bu on Proper es

Now you need to add the ac ons to the bu on that will enable and disable Mach4. In the proper es window
click on the lightning bolt and for the “Down Ac on” select “Enable On” from the drop-down list. Then set the
“Up Ac on” to “Enable Off”, see figure 4-9. You should have a bu on on the screen that looks like figure 4-10.

Figure 415 Enable Toggle Bu on

Next you will be adding some standard bu ons to the screen and some LEDs to show the home status of the
axes. Add 9 standard bu ons and set the Height = 40, Width = 90 and label and posi on them as shown in
figure 4-11. Add three LEDs and posi on them as shown.

Figure 416 Control Bu ons and LEDs

At this point you should be comfortable adding the controls, posi oning them and changing the displayed text.
Now we need to add the ac ons. All the bu ons will have predefined ac ons for their func on, except for the
“Home All” bu on, which we’ll get to later. For example, click on the “Cycle Start” bu on and then go to the
events proper es. The first op on is “Le Down Ac on”. Select “Cycle Start” from the drop-down menu to
define the func on. Repeat for “Feed Hold”, “Stop”, “Reset”, “Load GCode”, and “Edit”, selec ng the
appropriate func on from the drop-down menu.

For the “Machine Pos” and “Dist-To-Go” bu ons, select “Machine Coordinates Toggle” (or “Distance To Go
Toggle” for both the le down and le up ac ons, figure 4-12. Now when you push the bu on down the DROs
will display the machine or distance-to-go coordinates, when you release the bu on they will go back to the
absolute coordinates.

Figure 417 Machine coordinate bu on ac ons

Now for that special “Home All” bu on. There is no op on for home all from the drop-down list. You must add
a Lua script to that bu on. Select the “Le Down Script” ac on to open the script editor and copy the following
text:
Close the Lua editor and save the changes.

LEDs
The LEDs also need to be assigned to signals to turn them on and off. In this screen, you want them to display
the homed state of each axis. Select the X axis led to display its proper es in the proper es window, shown in
figure 4-13.

Figure 418 LED Proper es

Input and output signals can be assigned to an LED, see the bo om two proper es in the window. Assign the
LED to the “X Homed” signal. Don’t get “X Homed” confused with “X Home”. “X Home” is a different signal and
will only display the status of the home switch, not the homed state of the axis. Set the Y and Z LEDs to display
those home states as well

Edi ng Completed Screen

You have now completed a very basic screen. It should look like figure 4-14. Exit the editor by going to
Operator>Edit Screen and save the screen. Try changing tabs, loading a program, etc.
 Figure 419 Finished Example Screen

Immediately you’ll no ce this screen works for running a program, but it is missing a couple key features. There
are a few things we will want to add, sliders for feed rate and rapid override, a status bar to display messages
and some jog controls. Start with the status bar. A good place to put it is across the top. Start by resizing the tab
control, select it and drag the top edge down to get enough room to put a sta c text control across the top,
with another for a label and a history bu on, figure 4-15.
 Sta c Text Controls

Figure 420 Add status bar at the top

Figure 4-15 shows the addi on of the status bar at the top. There is one sta c text control to display the
“Status:” label, a second one to display the last or current message and finally a bu on to show the message
history. To set a sta c text control to display the data like the current message you need to select a label code in
the control’s proper es, figure -16. Select the sta c text control that will become your status bar and select
“Last Gcode Message” from the drop-down menu in the “Label Code” property. Lastly, you need a history
bu on to see previous messages. Add a bu on, name it “History” and set the le down ac on to “Show
Message History”.
 Figure 421 Sta c text proper es

Sliders
Now let’s introduce some new controls, sliders. Sliders are useful for dynamically varying the value of
something, like feedrate override. Add a couple sliders in the empty space between the bu ons. In the
proper es set the “Code” to “Rapid Rate Override” and “Feed Rate Override”. Generally, the upper and lower
limits of the rapid override should be 0-100, and the feedrate override 0-200. These se ngs allow you to stop
the mo on and increase the feed rate if needed. See the proper es in figure 4-17.
 Figure 422 Add override sliders

Exit the editor and play with the sliders. Click and drag the pointer to adjust the value anywhere in between the
Min and Max value you set in the proper es.

Manual Jog Bu ons

Lastly, add some controls for manually jogging the machine. A good place to put these is on another tab. Enter
the editor and add a page to the tab control. Next add some standard bu ons, two for each axis, and arranged
in a way that makes sense to you, see figure 4-18 for an example layout.

Figure 423 Jog bu on tab

Once the bu ons are added you need to assign ac ons to make the machine jog. Jogging is a bit tricky, there
are two ac ons that need to be used to get a bu on to do what you expect. The first ac on, which you will
assign to the down ac on, starts the jog command. The second ac on, which you will assign to the up ac on
will end the jog command. For an example see figure 4-19 for the event proper es of the Y+ bu on.

Figure 424 Y + job bu on ac ons

If you forget to add the “Jog Off” ac on, then the axis jog will start and not stop. This is a very important thing
to remember. With these ac ons defined, when the bu on is pushed the machine will jog un l it is released.

Manual Data Input (MDI)

The last thing that will be added as a part of this manual is an MDI (manual data input) window. Let’s put this
on yet another tab, named MDI. An MDI window allows you to manually enter blocks of GCode to be executed.
Adding the MDI window is straight forward, execu ng it is where it gets a bit tricky. So, add a tab and insert an
MDI window, size it to fit the tab, figure 4-20.

Figure 425 MDI tab added

There are a couple op ons for execu ng the contents of the MDI window. One is to add a new bu on to only
execute the contents of the MDI window. There is an event property on standard bu ons named “Run MDI”,
select the name of the MDI window you want this bu on to execute and that is it. The other way, which will be
covered in this manual is to have the “Cycle Start” bu on run either the currently loaded GCode file or the MDI
window depending on what the user is looking at. This way the screen is simplified and avoids unintended
automa c opera on. Start by clicking on the “Cycle Start” bu on and navigate to the event proper es. Remove
the “Cycle Start” event from the “Le Down Ac on”. Next you can add a “Le Down Script”. The following Lua
code can be copied and pasted into the Lua editor:

Close the Lua editor and save the code. Exit the screen editor and test your new controls. Pay a en on to the
status bar, the “mc.mcCntlSetLastError()” statements write to the status bar. It’s a good way to know what your
custom events are doing. Try some MDI code, try to cycle start the program when the Jogging tab is ac ve.

Completed Screen
That concludes the crea on of a basic example screen. This screen is only meant as an example of how to edit
and create screens. There is s ll plenty to add to this screen, on the Jog screen alone you could add sliders for
jog speed, bu ons to toggle between con nuous and incremental jog and DROs and bu ons for the increment
amount. There are many func ons available in Mach4, far more than fit into the scope of this manual. However,
armed with the basics learned in this example you can explore the rest of the controls and their ac ons to build
the rest of your screen. And remember, if a predefined ac on is not available, nearly anything can be done
using the Lua interface, more informa on on that can be found in the Lua Scrip ng Manual.
Figure 426 Completed example screen
Screen Scripts
Screen Script Overview
The GUI has a LUA script that is comprised of several script “snippets”. All of these script snippets are
concatenated into one LUA script in the order describe below. This facilitates the use of global variables that all
of the script snippets can access.

Screen Load Script

The screen load script is run when the screen is ini ally shown or a er the screen is edited. Global
variables, if used, should be defined in the Screen Load Script. These global variables will be available
to all of the scripts below the Screen Load Script. Global variables can be used as control variables that
dictate what other parts of the script do, for example.

Screen Unload Script

The screen unload script is run when the screen is unloaded, whether by closing the GUI, loading
another screen set, or by edi ng the screen. This script can be used to perform housekeeping du es
like cleaning up processes, stop mers, etc.

PLC Script
The PLC script is run on a me interval that is defined by the “PLC Interval” property of the screen. It
allows, as the script’s name implies, for Programmable Logic Controller type func onality.

The PLC script snippet is wrapped in a LUA func on named Mach_PLC_Script and has no parameters.

Signal Script
The signal script is fired when any core signal is changed.

The signal script is wrapped in a LUA func on named Mach_Signal_Script with parameters sig (number)
and state (number). The sig parameter contains the signal ID of the changing signal and the state
parameter contains the new state of the signal (1 on, 0 off).

Timer Script
The mer script is fired when a screen mer expires. It allows for mers that run independent of the
PLC script interval.

The mer script is wrapped in a LUA func on named Mach_Timer_Script with a parameter of mer
(number). The mer parameter contains the ID of the mer that expired (0-9).

Control Event Scripts

Many controls have event scripts which can be populated with script code to perform ac ons when
their respec ve events are fired.
 Debugging
Since the screen script is run behind the scenes, and in some cases, as a result of external events, it requires a
special debugging technique called Remote Debugging. Remote Debugging is where one process is running the
script and another process is debugging it. In the normal case, the GUI will be running the script (client) and
the LUA editor will be debugging it (server). The scripts running on the client will need to contain some special
commands to ini al debugging. This is accomplished with the “mobdebug” LUA module.

Debug Preparation
Screen scripts do not have debugging enabled by default. Since they are expected to run, in the normal
case, at full speed, including the debugging module might impact speed in a produc on environment.
Follow the steps below to prepare the screen script for debugging.

 Open the screen editor (Operator->Edit Screen).

 Navigate to the Screen Load Script and edit it by pressing the ellipse bu on.

 Insert the following lines at the very top of the Screen Load Script:
mobdebug = require('mobdebug')
mobdebug.onexit = mobdebug.done
mobdebug.start()

 Close the editor. This is important, as the script modifica ons will not take effect unless the
editor is closed.

 Save the screen, but do not exit the screen editor. This is also important because exi ng the
screen editor at this point will start the script!

Starting The Debug Session

The debug session needs to be started before the screen edi ng is finished for the reason stated above.

 In the GUI menu, open the LUA editor (Operator->Open Script Editor)

 Once the editor is open, in the editor’s menu, start the debug server (Project->Start Debug
Server)

 Back to the GUI, exit the screen editor (Operator->Edit Screen).

Once the screen editor is exited, the LUA editor will pop up with a copy of the en re screen script and
break right a er the line that contains “mobdebug.start()”. The script is read only and cannot be
edited.

At this point, you can step through and debug the screen load por on of the script, if needed.
Otherwise, you can set break points in other areas of the script that are of interest. Say you want to
 debug the PLC script. Simply put a breakpoint on a line in the Mach_PLC_Script func on. Then
con nue the debug session by pressing the play bu on on the LUA editor’s tool bar or by pressing F5.

Once the PLC script processes the line with your break point, the LUA editor will pop back up allowing
you to inspect variables and step through the script. This can be done as many mes as needed. Keep
in mind that strategic placement of breakpoints can help make the debugging process smoother.

If an error is found, you can’t really edit it in place. This is because the script that is displayed is not the
actual script that is running, but rather a copy of it. You will have to exit the LUA editor and edit the
screen to apply changes. Repeat as necessary un l the desired func onality is achieved.

Ending The Debug Session

Once you are done debugging the screen script, you simply close the LUA editor. If you do not want to
do anymore further debugging, edit the screen load script and either remove the debugger commands
or remark them out and save the screen.