Last updated,
****** THIS DOCUMENT IS UNDER CONSTRUCTION, THIS IS FOR THE NEW RELEASE 4.x ******

Objects

Objects available:

Machine
Object to control the CNC Machine.
GCodeProgram
Load programs from files, 2d vectors or g-code lines.
Utils
Object with usefully methods.
Dialogs
Boxes for alert, confirm, input data.
Events
Register events: states from device, states from G-code sender

Sample JS code:

// Move your machine to X = -10
let machine = new Machine();
machine.code( "G00 X-10" );

Machine

Object to control the device connected to Ultimate CNC.

void code( string );

Send G-code to device.

Arguments
G-code. You can use semicolon if you want sent more than one G-code.
Return Value
None
Call type
Blocking
Notes
All commands will be queued; if an error or alarm occurs in the G-code sequence, the next commands will be removed. This function block the execution of your script until all commands have been sent. The G-code is sent one by one, so it is not recommended sending G-code programs.

let machine = new Machine();
machine.code( "F100; G01 X-10; Y10; X0; Y0" );

string getWorkingPosition( );

Return current working position.

Arguments
None
Call type
Synchronous
Return Value
String.

let machine = new Machine;
machine.code("G90; G21; F400; G01 X-10.5 Y-12.56 Z1; ");
let machinePosition = machine.getMachinePosition();
// machinePosition = -10.500,-12.560,1.000

double getWorkingPosition( string axis );

Return current axis working position.

Arguments
Axis. Values allowed: x, y or z
Call type
Synchronous
Return Value
Double.

let machine = new Machine;
machine.code("G90; G21; F400; G01 X-10.5 Y-12.56 Z1; ");
let xMPosition = machine.getMachinePosition('x');
let yMPosition = machine.getMachinePosition('y');
let zMPosition = machine.getMachinePosition('z');
// xMPosition = -10.500
// yMPosition = -12.568
// zMPosition = 1.000

void zeroXy();

Set coordinates XY = 0.

Arguments
None
Call type
Blocking
Return Value
None
Notes
G-code = G92 X0 Y0. (Send the g-code commands configured on GUI).

void zeroZ();

Set coordinate Z = 0.

Arguments
None
Call type
Blocking
Return Value
None
Notes
G-code = G92 Z0. (Send the g-code commands configured on GUI).

string getMachinePosition( );

Return current machine position.

Arguments
None
Call type
Synchronous
Return Value
String.

let machine = new Machine;
machine.code("G90; G21; F400; G01 X-1 Y-2 Z3; ");
machine.zeroXy();
machine.zeroZ();
machine.code("G53 G01 X0 Y0 Z0; ");
let machinePosition = machine.getMachinePosition();
let workPosition = machine.getWorkingPosition();
// machinePosition = 0.000,0.000,0.000
// workPosition = 1.000,2.000,-3.000

double getMachinePosition( string axis );

Return current axis machine position.

Arguments
Axis. Values allowed: x, y or z
Call type
Synchronous
Return Value
Double.

machine.code("G90; G21; F400; G01 X-1 Y-2 Z3; ");
machine.zeroXy();
machine.zeroZ();
machine.code("G53 G01 X0 Y0 Z0; ");
let machinePosition = machine.getMachinePosition();
let workPosition = machine.getWorkingPosition();
// machinePosition = 0.000,0.000,0.000
let xMPosition = machine.getMachinePosition('x');
let yMPosition = machine.getMachinePosition('y');
let zMPosition = machine.getMachinePosition('z');
// xMPosition = 0.000
// yMPosition = 0.000
// zMPosition = 0.000

int feedrate( );

Return current feedrate.

Arguments
None
Call type
Synchronous
Return Value
Integer. Example: 600.

int spindle( );

Return current vel. spindle.

Arguments
None
Call type
Synchronous
Return Value
Integer. Example: 1000.

int spindleDir( );

Return current spindle rotation.

Arguments
None
Call type
Synchronous
Return Value
TODO

string spindleDir( );

Return current spindle rotation.

Arguments
None
Call type
Synchronous
Return Value
TODO

bool mistCoolant( );

Return mist coolant state.

Arguments
None
Call type
Synchronous
Return Value
Bool.

bool floodCoolant( );

Return flood coolant state.

Arguments
None
Call type
Synchronous
Return Value
Bool.

bool state( );

Return device state.

Arguments
None
Call type
Synchronous
Return Value
Bool.

string getSafeZ( );

Return Z from configuration.

string setSafeZ( );

Set Z safe.

string getDevice( );

Default device to connect.

Arguments
None
Call type
Synchronous
Return Value
String. Example: COM5

string getBpsDevice( );

Default bps device to connect.

Arguments
None
Call type
Synchronous
Return Value
String. Example: 9600.

string getCurrentToolNumber();

Return current tool configured

void setCurrentToolNumber( number )

Set current tool

runToolChange()

Open manual tool change utility.

Arguments
None
Return Value
None.

bool endToolChange()

Used to know if tool change procedure is done.

Arguments
None
Return Value
Bool. Return true if M6 isn't on g-code parser.

string getConfig( string );

Get the config parameter on your firmware.

let machine = new Machine();
let param100 = machine.getConfig( "100" );

void setConfig( string id, string value)

Set parameter on your firmware. Example:

let machine = new Machine();
machine.setConfig( "100", "1280" );

string getAllConfig();

Return all configuration parameters on your device. These parameters are saved on Ultimate CNC, so don't query it to your device.

Example:

// Get all configuration from your firmware
let machine = new Machine();
let params = machine.getAllConfig( );

void probeZ();

Run probe.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

void goZeroZ();

Run goZeroZ.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

void goHome();

Run goHome.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

void goUpZ();

Run goZup.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

void spindleOn();

Turn on spindle.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

void spindleOff();

Turn off spindle.

Arguments
None
Call type
Blocking
Return Value
None
Notes
Send the g-code commands configured on GUI.

Object Utils

void sleep( int )

Sleep your script.

Arguments
Integer. Second to sleep.
Call type
Blocking
Return Value
None

let utils = new Utils();
let machine = new Machine();
machine.command("$$");
utils.sleep(5);
let params = machine.getAllConfig();

void kill( )

Kill your script.

Arguments
None.
Call type
Blocking
Return Value
None

let utils = new Utils();
let machine = new Machine;
machine.goUpZ();
utils.kill( );
machine.goHome();
// goHome() is never reached

Object Dialog

alert( string )

Show message in a popup window.

Arguments
String. Message to show.
Call type
Blocking
Return Value
Bool. Return true if press Ok button, otherwise false;
Notes
Blocking until press Ok/Cancel button

let dialog = new Dialog();
dialog.alert( "Hi! alert" );

info( string )

Show message in a popup window.

Arguments
String. Message to show.
Call type
Non-blocking
Return Value
None
Notes
Multiple calling to this method, the message will be updated, without message history.

let dialog = new Dialog();
dialog.info( "My info message" );

bool confirm( string )

Show message in a popup window and return response for user.

Arguments
String. Message to show.
Call type
Blocking
Return Value
Bool. Indicate if user press on OK (true) or Cancel (false).

let confirm = dialog.confirm( "Go home ?" );
if ( confirm ) {
     machine.goHome();
}

array getCoord ( string )

Show you a input for coordinates [X,Y,Z] in a popup window and return response for user.

Arguments
String. Descriptive message to show.
Call type
Blocking
Return Value
None

let dialog = new Dialog();
let machine = new Machine();
machine.code("G90; G21; F400");
let init = [ 0, 0 ];
let status = dialog.getCoord( "Select init coordinates", init );
if ( status ) {
     machine.code("G01 X" + init[0] + "Y" + init[1] + "Z" + init[2]);
}
let confirm = dialog.confirm( "Do you want triangle wave ?" );
if ( confirm ) {
     let triangle = [];
     triangle[0] = [ 0, 0 ];
     triangle[1] = [ 25, 25 ];
     triangle[2] = [ 50, 0 ];
     triangle[3] = [ 75, 25 ];
     triangle[4] = [ 100, 0 ];
     let gCode = "";
     for (let coordinate of triangle) {
         gCode += "G01 X" + (coordinate[0] + init[0]) + "Y" + (coordinate[1] + init[1]) + ";";
     }
     machine.code( gCode );
}

void busy ( bool )

Show popup window to inform that script is working.

Arguments
Bool. Open / Hide popup.
Call type
Non-blocking
Return Value
None
Notes
If you call to another method of Dialog object, automatically, this popup will be closed.

let machine = new Machine();
machine.code( "G90; G21; F300" );
let dialog = new Dialog();

dialog.busy( true );

let commands = "";
for ( let x=0; x <= 100; x += 10 ) {
     commands += "G01 X" + x + ';' ;
}
machine.code( commands );

dialog.busy( false );

Object Events

Receive events in your script.

stateMachine ( function )

Register your handler function to recipe changes in the state of your device.

Arguments
function. Function that recipe state's changes
Return Value
None
Call type
Synchronous
Notes
State: IDE, RUN, ALARM, ... (upper case)

let dialog = new Dialog();

function statesHandler( state ) {
     if ( state == "ALARM") {
         dialog.alert( "Machine, alert: " + state );
     } else {
         dialog.info( "Machine, info:" + state );
     }
}

let mEvent = new Events;
mEvent.stateMachine( statesHandler );

let machine = new Machine;
machine.code("G90; G21; F400; G01 X-10;");
machine.goHome();

stateGcodeProgram ( function )

Register your handler function to recipe changes in the G-code sender.

Arguments
function. Function that recipe state's changes
Return Value
None
Call type
Synchronous
Notes
State: NEW (new g-code program is loaded), END (g-code program end), ERROR (error in your g-code program), ... (upper case)

let dialog = new Dialog();
let utils = new Utils();
    
function statesHandler( state ) {
    if ( state == "ALARM") {
        utils.kill( );
    } else {
        dialog.info( "Machine, info:" + state );
    }
}
    
function stateGcodeProgramHandler( state ) {
    if ( state == "ERROR") {
        utils.kill( );
    }
}
    
let events = new Events;
events.stateMachine( statesHandler );
events.stateGcodeProgram( stateGcodeProgramHandler );
    
let machine = new Machine;
machine.goUpZ();
machine.code("G90; G21; F400;SOME_ERROR!; G01 X-10;");
machine.goHome();
machine.code("G90; G21; F400;G01 X-50;");
// G01 X-10; is not executed and goHome is never reached

stateMCodes ( function )

Register your handler function to recipe M-Codes from G-code sender. TODO

Arguments
function. Function that recipe M-Codes defined on configuration
Return Value
None
Call type
Synchronous

stateGCodes ( function )

Register your handler function to recipe some G-Codes from G-code sender. TODO

Arguments
function. Function that recipe G-code defined on configuration.
Return Value
None
Call type
Synchronous

GCodeProgram

This Object allows load G-code from files, G-code list or 2D vectors array.

bool file( string )

Load a G-code program from file.

Arguments
Bool. Open / Hide popup.
Call type
Blocking
Return Value
Bool

bool code( array )

Load a G-code program from a array (it is a list of G-code).

You must use this function to load G-code programs. Machine.code does not load G-code programs. This function does not generate any movement like Machine.code does.

Arguments
Array. List of G-code
Call type
Blocking
Return Value
Bool

// Sine wave
// From coordinates to G-code Program

const A = 10;
const CC = 5;
const SAMPLES = 1000;
const WIDTH = 100;

let lines = [];
lines.push("G21");
lines.push("G90");
lines.push("F300");

let angle = 0.0;
for ( let i = 0; i < SAMPLES; i++ )
{
        let y = (A * Math.sin(angle) + CC);
        let x = i * WIDTH / SAMPLES;
        lines.push ( "G01 X" + x.toFixed(3) + "Y" + y.toFixed(3) + "\n" );
        angle += (2 * Math.PI) / SAMPLES;
}

let program = new GCodeProgram();
program.code( lines );

bool vectors( array, array, double, double )

Load 2D vectors, and it will be converted to G-code Program.

Arguments
Axis XY, Depth, Step
Call type
Blocking
Return Value
Bool
Notes
This function mill your vectors using the parameters on the configuration.

// Draw ellipse
// Ultimate CNC will create G-code Program

const SAMPLES = 1000;
const STEP = 2 * Math.PI/SAMPLES;
const RADIUS = 50.0;
const DEPTH = 1.0;
const DEPTH_STEPS = 0.5;

let axis = [];

for( let angle = 0; angle <= 2 * Math.PI; angle += STEP ) {
    var point = [
        RADIUS * Math.cos(angle),
        -0.5 * RADIUS * Math.sin(angle)
    ];
    axis.push( point );
}

let program = new GCodeProgram();
program.vectors( axis, DEPTH, DEPTH_STEPS );

void getSize ( &object )

Get size of the G-code Program loaded.

Arguments
Array.
Call type
Blocking
Return Value
Object.width, Object.height, Object.xmin, Object.xmax, Object.ymin, Object.ymax.

// Create a G-code program from XY coordinates.
// In this case, a simple triangle.
// P0 = (0,0) P1 (-20,20) P2 (20,20)
// Show message with size of triangle

const SAMPLES = 1000;
const STEP = 2*Math.PI/SAMPLES;
const RADIUS = 50.0;
const DEPTH = 1.0;
const DEPTH_STEPS = 0.5;

let program = new GCodeProgram();
let axis = [ [0,0], [-20,20], [20,20] ];
program.vectors( axis, DEPTH, DEPTH_STEPS );

let frame = {};
program.getSize( frame );

let dialog = new Dialog();
dialog.alert( JSON.stringify(frame) );
// {"xmin":-20,"xmax":20,"ymin":0,"ymax":20,"width":40,"height":20}

Simple CAD

This Object allows load a lot of shapes or drills into Simple CAD.

Later, you will be able to use Simple CAD to generate the G-code program.

void drill ( float x, float y )

Load a drill in SimpleCAD

void polygon ( object )

Load a polygon in SimpleCAD

Arguments
Object
Call type
Blocking
Return Value
None

void rectangle ( float x, float y, float height, float width )

Load a rectangle in SimpleCAD

void circle ( float x, float y, float radius )

Load a circle in SimpleCAD

void triangle ( float x, float y, float width )

Load a triangle in SimpleCAD

void square ( float x, float y, float width )

Load a square in SimpleCAD