SAC is short for Servo Automation Control, and is a scripting language that can be used to control the router. The syntax is Visual Basic.

SAC Examples

A few examples can be found on the SAC Examples page.

How to use SAC

SAC, or SERVO AUTOMATION CONTROL, is a scripted language interpreted natively by the CNC interface in versions 416 and newer. To make a SAC file, either use the CNC interface Edit function, or write the code in notepad and save the file as a .SAC file. The contents of the file is normal text formatting.

How to use this document

When you encounter [variable/options], the proper syntax is to remove the [].

When you encounter "value", leave the quotes in

When you encounter (value), leave the ()s in, though you don't always need them.

When passing multiple numbers to a function that seems to take ()s, the following rule applies:

• function x,y,z
• function (x),(y),(z)
• function (x),,(z)
• function (x),y,(z)
• NEVER function (x,y,z)
• NEVER function (x),(),(z)

All established VBscript commands are also usable, use your favorite search engine with the term "vbscript functions" to get an up-to-date list of functions and examples. Currently, one such list is at http://www.w3schools.com/VBscript/vbscript_ref_functions.asp or http://msdn.microsoft.com/en-us/library/t0aew7h6(VS.85).aspx

Good VBscript Practice

Goto and gosubs are no longer available. Use public functions and subs to do your branching. If you wrap your entire program in one outer function, it is possible to "end" the program early upon finding an error, as such:

chopblock()

public function chopblock()
   'do some things here,
   if error detected then exit function
   'do some other things here
   if error detected then exit function
   'do some other things here
   if error detected then exit function
   'do some other things here
end function

In the previous example, the first line runs the function chopblock, which frequently checks for an error. When an error is encountered, the function will be exited, and the code will end prematurely.

Command Reference

System Response

messagetop "Message",[1/2]

Prints a message under the percentage bar. There are two places to print, and '1' is higher than '2'.

Examples:

messagetop "Starting...",1

x="hello"
messagetop x,2

Note that message "x" and messagetop("x",1) will do the exact same thing.

message "Hello!"

x="Winnebago"
message x

System Engagement

reset()

Reset the servos and leave the amplifiers off. Encoder telemetry will not be lost.

powerup()

Reset the servos and engage the amplifiers.

powerdown()

Engage any brakes on brakemotors and disable the amplifiers. Encoder telemetry will not be lost.

active()

Returns false if the system has stalled or if the emergency stop has been pressed. Active should be checked frequently in a loop, as movements will hang the system if the controller is emergency-stopped.

Example:

if active()=false then msgbox("inactive!")

System Trajectory and Movement

It should be noted that if the setting Setup > System > Orientation is set to +1, exchange all the X notes and Y notes in this section with each other.

speed(x)

Speed will alter the speed at which subsequent moves will be made. It will not affect speeds already in motion. Speed is in units per minute. Example: speed(100)

accel(x)

Alters the acceleration at which subsequent moves will be made. It will not affect acceleration of an axis that is already in motion.

Example:

accel(20)

moveto x,y,z,a

Start and wait for the completion of a move at the predefined speed with the predefined accel. All values are optional.

Examples:

moveto 5,4.5,7

moveto ,-9

moveto 5,,1

moveto_watchlimitswitches x,y,z,a

Will move just as the moveto command, but will break execution if a limit switch is encountered on any of the axes.

smoveto x,y,z,a

Will load and start a move to a position and continue SAC execution without waiting for the movement to be complete.

Examples:

smoveto 5,4.5,7 

smoveto ,-9

moverel x,y,z,a

Will move relative to the current position. Will wait for the movement to complete before continuing execution of the program

Examples:

moverel 5,6,-7

moverel ,-4

smoverel x,y,z,a

Will move relative to the current position. Will continue execution of the program while moving.

Examples:

smoverel 5,6,-7

smoverel ,-4

completedmove()

Will return true when all axes are not moving. Useful for waiting for the end of an smoveto command.

Example:

do
  if completedmove()=true then exit do
loop

movedone("a")

Returns true if an axis is NOT moving and false if the axis IS MOVING. Only one axis may be inquired about per run

Example:

if movedone("x") =true then msgbox("X Axis is still moving!")

rapidto x,y,z,a

Will start and wait for the completion of a move. Moves the Z axis positively first and singly if the destination Z value is higher than the current Z value, and moves the X,Y axes first if the destination Z value is lower than the current Z value.

Examples:

rapidto 1,2,3 

rapidto 1,,5

halt "a",abruptly

Will stop one or more axes from moving. If abruptly is set to true, the axis will be stopped as quickly as possible (Maximum deceleration), otherwise, it will be decelerated at the same rate by which it was accelerated.

Examples:

halt "XY",TRUE

halt "Z",FALSE

toolchange x

Changes tools automatically if a toolchanger is present and configured, alternately, if no toolchanger is present, will prompt for a manual toolchange.

Example:

toolchange 4

System Telemetry

pos("x")

Returns the theoretical, desired position of the axis relative to the origin set by the user.

Example:

xposition=pos("x")

rpos("x")

Returns the real, instantaneous position of the axis relative to the origin set by the user. This differs from regular pos in that it includes any error - difference between where the axis should be and where it is.

Example:

xposition=rpos("x")

System Timing

delay(x)

Will delay for an amount of time in seconds. Decimals are permitted. Resolution is to .001s and accuracy is dependant on system performance. For very long delays, if a message about the script timing out appears, go to Setup and change the SAC timeout value (default timeout is 120 seconds)

Example:

delay 50

delay 3.423

System Inputs and Outputs

serialioout "a",["1/0"]

Control output a on the serial IO controller. "1" turns on the output and "0" turns it off.

Example:

serialioout "5","1"

serialioin("a")

Return the value of an input on the serial io controller. will return true or false.

Example:

if serialioin("4")=true then messagetop("Serial 4 is on")

ioout "#",["1/0"]

Control output # on the parallel io board. "1" turns on the output and "0" turns it off. The outputs will not return to defaults after the SAC program is done running.

Example:

ioout "3","1"

ioin (bit)

Return the value of an input on the parallel io board. The return value is boolean ("true" or "false").

The value of bit that you expect to measure is not the same as is shown on the diagnostics screen. The diagnostics screen flips the first and second bytes. So if you want to measure bit 11 on the diagnostics screen (often corresponds to the pause button on the start/stop box), you should use ioin(3) instead of ioin(11).

Example:

if ioin (4) = true then 
  messagetop "4 is ON",2 
ELSE
  messagetop "4 is OFF",2

NOTE The ()s in ioin versus the lack of () for ioout. The examples are correct, follow them.

homeinp("a")

Return true if a limit switch input is triggered. Values can be X,Y,Z,A as or 0 thru 7 (y=0,x=1,z=2,a=3, if you wish to access the "overtravel" inputs (really just inputs for whatever you want), use numbers 4-7)

Examples:

if homeinp("x") then msgbox("X is on the switch!")

if homeinp("5") =TRUE then 
    MESSAGETOP "Home input 5 is triggered!",2 
ELSE 
    MESSAGETOP "Home input 5 is NOT triggered!",2
<pre>

Note: Quotes around "X" are NECESSARY, quotes around "5" are not. When you use a number, you are checking the number, when you pass an axis letter, the script interprets x as a variable and not an axis name. 

==== routeron ====
Turns on the spindle output of the system

Example:
<pre>routeron

routeroff

Similar to routeron but this function turns off the spindle output.

routerauto

Sets the spindle mode to auto, which will be most useful when running gcode files which turn the spindle on and off from within.

routerrpm(#)

Changes the RPM of the spindle if the appropriate speed-changing hardware is present.

Example:

routerrpm(15000)

auxon

Turns on the aux output, usually reserved for coolant.

auxoff

Similar to auxon, this function turns off the aux/coolant output.

auxauto

Sets the aux/coolant output to auto, useful for when running gcode which triggers the coolant output on its own.

G-code

gcodefile("full filename")

Load a gcode file into memory. Requires the full path to be specified. Will not run the file (see gcoderun).

Example:

gcodefile("c:\sac\makecheese.sac") 

gcoderun

Runs the gcode file

gcodepreprocess

Preprocesses the gcodefile loaded by gcodefile(). Preprocessing a file is required to run, but only when trajectory or speed is changed in the file. If a file has been preprocessed before (not even necessarily in sac), and nothing has changed as far as speed or file geometry, preprocessing is unnecessary. Note that the file will run relative to the origin, and that a change in origin does not require preprocessing again.

gcodecutspeed(#)

Sets the override speed for the X, Y and A axes in a gcode file. The file will have to be preprocessed for these numbers to take effect.

Example:

gcodecutspeed(500)

gcodeplungespeed(#)

Similar to gcodecutspeed, this value only changes the Z speed in a file. The file must be preprocessed for this number to take effect.

Example:

gcodeplungespeed(100)

sac_focus_loss

When running G-code normally, clicking elsewhere with the mouse or interacting with other software will cause the system to pause. In the case of Library Functionality, the system may need to run other software and not pause the G-code. To implement this ability, set the variable SAC_FOCUS_LOSS to true in the beginning of the SAC file. To restore the functionality, set the value to false. The value is reset on restart of the CNC interface but is NOT reset on re-running of the SAC or G-code files.

Example:

SAC_FOCUS_LOSS("true")

get_sac_reset

If a G-code file run from SAC is reset or halted, this variable gets set to TRUE. This is useful when handling an unanticipated reset of a G-code file.

Example:

DO

GCODEFILE("E:\NC FILES\LINE.NC")
GCODERUN
CTR=CTR+1

IF ACTIVE=FALSE THEN EXIT DO
IF CTR>10 THEN EXIT DO
IF GET_SAC_RESET()=TRUE THEN EXIT DO

LOOP

System Origin Reference

zero "x"

Set the current position to be the origin relative to which movements will be made.

Examples:

zero "x"

zero "xy"

zero "all"

home "x"

Move the machine to the reference position in any axes. Will always follow the order Z,A,X,Y. If a different order is desired, home axes singly.

Example:

home "x"

home "xy"

home "all"

setpos x,y,z,a

Adjust the origin to make the current position equal to the values passed to the function.

Example:

setpos 5,6,7

setpos ,2

saveorigin #

Temporarily save the origin to a temporary list of 0-99. This will not survive a software restart.

Example:

saveorigin 3

loadorigin #

Loads an origin from the saveorigin list.

Example:

loadorigin 3

storeorigin #,"name",method

Will permanently store an origin in the same slots as seen in SETUP->Offsets. The '#' marker is the position to store in, 'Name' is the name to give the offset.

• Method 0 will store the current position (location of all the axes)
• Method 1 will store the current origin, regardless of the position of the axes.

The machine must be properly homed before this will work.

Example:

storeorigin 3,"Jig F",1

retrieveorigin #

Will retrieve an origin stored with storeorigin

Example:

retrieveorigin 3

shiftorigin x,y,z,a

Will adjust the current origin by the amount specified. Changes the values for origin without moving the machine.

Example:

shiftorigin 4,5,6

shiftorigin ,5

touchoffz(method)

Uses the touchpad to determine the new Z origin. If a dedicated touchoff spot is stored in Setup > Advanced > Touchpad and Remote, the machine will move to that spot first if method =1.

Example:

touchoffz(0)

touchoffa(method)

Uses the touchpad to determine the new A origin. If a dedicated touchoff spot is stored in Setup > Advanced > Touchpad and Remote, the machine will move to that spot first if method is 1. Be careful: the dedicated spot for touching off will be the same for Z and A.

Example:

touchoffa(0)

Errors

errorlimit "a",#

Change the error value at which the machine returns a position error and stalls. Changing this value is not recommended. It can result in increased motor wear, or premature stalling. The standard value is 3000.

Example:

errorlimit "XYZ",3000

axiserror "a"

Returns true if the axis has experienced an error, false if everything is okay. Only one axis may be checked per instance of the function. Since an axis error causes the program to stop, it is not likely that this function will be useful.

Example:

if axiserror("X") =true then msgbox("ERROR!")

File Operations

openfile handle,filename,mode

Opens a file for reading or writing to. You can have more than one file open, and the handle will control what file you are referring to. The handle should be a number, like 52.

Modes:

• i = input, or read a file
• o = output, or write to a file (this will erase the file if it already exists)
• a = append, or write to the end of an already existing file

Example:

openfile 91,"C:\file.txt","O"

closefile handle

Use the same handle number and close the file previously opened. If this is not done before a program is finished, it is possible that all the data will not be written to the file.

Example:

closefile 91

readfile handle,destination

Reads the file referenced by handle and puts it in string destination. Also returns the string.

Example:

lineoffile=readfile (91,alsolineoffile)<pre>

openfile 91,"C:\file.txt","I"
DO
    lineoffile=readfile (91,alsolineoffile)
    MSGBOX LINEOFFILE
    IF EOFFILE (91) THEN EXIT DO
LOOP

closefile 91

writefile handle, text

Write text to the file referenced by handle.

Examples:

writefile 91,"I like text!"+vbcrlf

writefile 91,gathereddata+vbcrlf

eoffile (handle)

Return true if the file is at its end.

Example:

if eoffile (91) then closefile 91