Actions

If a button has any arguments available, they are document below.

Button arguments are always an array of strings, like:

{
  "arguments": ["argument 1", "argument 2", "argument 3"]
}

Navigation actions

There are several different actions used for navigating between scenes. The difference between these is what happens when navigating back with backScene.

navigate

Change to the selected scene. backScene will return to the previous scene where the navigation was triggered.

example

{
  "actions": [
    {
      "action": "navigate",
      "event": "up",
      "arguments": ["home"]
    }
  ]
}

setScene

Change to the selected scene, clearing all back button history. This can be used to return “home” without allowing a backScene action afterward

swapScene

Replace the current scene with the selected scene. backScene will return to the scene before the scene where the action was triggered. This can be used to apparently change several button states at once invisibly.

backScene

Returns to the previous scene.

Jogging actions

jog

Jog in the given direction, based on jogDistance

startSmoothJog

Start smooth jogging in the given direction

Based on jogSpeed and the machine.axisSpeeds config. Multiple jog directions may be active at the same time.

example

{
  "actions": [
    {
      "action": "startSmoothJog",
      "arguments": ["+", "x"]
    },
    {
      "action": "stopSmoothJog",
      "arguments": ["+", "x"],
      "event": "up"
    }
  ]
}

stopSmoothJog

Stop smooth jogging in the given direction.

jogDistance

Change the current jog distance, which affects future jog distances.

jogSpeed

Change the current smooth jog speed, which affects future smoothjog speeds.

Interface actions

brightness

Change the current screen brightness. Stream Deck only

fullscreen

Toggle fullscreen web only

Override actions

increaseFeedrate

Increase the feedrate override based on feedrate interval

decreaseFeedrate

Decrease the feedrate override based on feedrate interval

toggleFeedrateInterval

Toggle how much the feedrate is changed by the feedrate action, either 1% or 10%.

resetFeedrate

Reset the feedrate override to 100%

increaseSpindle

Increase the spindle speed override based on the spindle interval

decreaseSpindle

Increase the spindle speed override based on the spindle interval

toggleSpindleInterval

Toggle how much the spindle speed is changed by the spindle action, either 1% or 10%.

resetSpindle

Reset the spindle speed override to 100%

setRapids

Change the rapid speed override

enterSpindleSpeed

Opens the special numpad scene for the selected axis. When a number has been entered and confirmed with the completeInput action, the spindle rotation will be set to the selected value and configured direction using M3 or M4 gcode.

User flag actions

User flags are arbitrary, temporary variables that can be displayed as dynamic text in buttons, or used as conditions for changing a button’s visibility or enabled/disabled status. They can be set, removed, or toggled.

These variables are not persisted, and will be reset when the page is reloaded, or when the Stream Deck process is restarted.

setUserFlag

Associate an arbitrary name with a string value

clearUserFlag

Remove an existing user flag

toggleUserFlag

Toggle a user flag.

The user flag does not need to exist before toggling. It will be set to true on the first toggle

Numeric input actions

input

Adds one or more characters to the end of the current numeric input

inputCommand

Input commands modify the current input value.

Commands:

• toggleSign: Flip the current input value from positive to negative, or negative to positive
• backspace: Remove the last character from the end of the current input value

completeInput

Save the current value and return to the previous scene

Positioning actions

absoluteMachinePosition

Move to a specific position, relative to the machine zero position.

Accepts a single string which will be used as arguments to a G53 G0 move.

example

{
  "actions": [
    {
      "action": "absoluteMachinePosition",
      "arguments": ["X-100 Y-20"]
    }
  ]
}

absoluteWorkPosition

Move to a specific position, relative to the current work zero position.

Accepts a single string which will be used as arguments to a G0 move.

example

{
  "actions": [
    {
      "action": "absoluteWorkPosition",
      "arguments": ["X10 Y20 A5"]
    }
  ]
}

goto

Move to a specific absolute machine position on one or more axes.

When an argument is given as a percentage (ex: "25%"), the position will be calculated based on machine dimensions.

Previously, goto also supported non-percentage movement. However, this has been deprecated in favor of absoluteMachinePosition and absoluteWorkPosition, and the previous functionality will be removed in a later version.

example

In the below example, the machine will be moved to 10% of the maximum Y range, 30 Z, and 50% of the maximum C axis range.

{
  "actions": [
    {
      "action": "goto",
      "arguments": [null, "10%", 30, null, null, "50%"]
    }
  ]
}

homing

Home all axes

enterPosition

Opens the special numpad scene for the selected axis. When a number has been entered and confirmed with the completeInput action, the machine will be moved to selected position on the axis.

enterWcs

Opens the special numpad scene for the selected axis. When a number has been entered and confirmed with the completeInput action, the selected axis’s work coordinate offset will be changed to the selected value

Gcode actions

refreshWatchFolder

Refresh the cncjs watch folder and open the file list

sortDetails

Change the sort order of the file list

clearGcode

Clears cncjs’s loaded gcode, if a gcode file has been loaded

gcode

Run arbitrary gcode

macro

Run a cncjs macro. Macros run from this pendant do not currently have access to some cncjs variables, like [ymin] and [xmax]. Macros which require these should not be used.

Macros can either be identified by their UUID using the first argument, or (less efficiently) by their exact name, using the second argument.

If the first argument (the UUID) is not provided, the second one (the name) must be instead, and vice-versa.

example

{
  "actions": [
    {
      "action": "macro",
      "arguments": [null, "My Macro"]
    }
  ]
}

outline

Parses the currently loaded gcode and jogs around its perimeter.

Limitations: gcode parsing and perimeter building is not 100% accurate. Some types of arcs (like those on 3 planes), may not be processed, resulting in straight line paths between their outermost points. All other arcs will be split into small straight line movements which can be misleading for small curves.

loadDetailFile

Used on the file details scene to load the gcode file being inspected. Not usable outside of this scenario.

Utility actions

command

Run a cncjs custom command. Commands are defined in the cncjs interface in Settings > Commands.

Commands can either be identified by their UUID using the first argument, or (less efficiently) by their exact title, using the second argument. The UUID can be found in your .cncrc config file.

If the first argument (the UUID) is not provided, the second one (the title) must be instead, and vice-versa.

example

{
  "actions": [
    {
      "action": "command",
      "arguments": [null, "My Restart Command"]
    }
  ]
}

CNC state actions

These actions relate to the current feed and run state

connect

If disconnected, connect will attempt to open the serial port using the cncjs` serial configuration.

run

Start running the loaded gcode

stop

Stop running the current gcode job

pause

Pause the currently running gcode job

hold

Feed hold. Decelerate axes and pause the current job

unhold

Cycle start. Resume cutting after a feed hold

reset

Soft reset the controller, maintaining machine position.

unlock

Issue an Alarm Unlock command

stopFeed

Stop cncjs’s feeder queue

startFeed

Start cncjs’s feeder queue if stopped