Configuration

Buttons, layout, and other behavior are configured with the config.json file.

The cost of high customizability is unfortunately high complexity. The configuration documentation here is for reference, but it is strongly recommended that you just start with the default config and modify it as you go, rather than starting from scratch.

You can use the Config Validator to verify your configuration changes.

The top level configuration object has the following keys:

cncjs

Used to configure connection to the cncjs server, and controller serial port

example

{
  "cncjs": {
    "accessTokenExpiration": "30d",
    "baudRate": 115200,
    "controllerType": "Grbl",
    "port": "/dev/ttyACM0",
    "socketAddress": "localhost",
    "socketPort": 8000
  }
}

machine

Machine axes and per-axis speed modifiers

{
  "machine": {
    "axes": ["x", "y", "z"],
    "axisSpeeds": {
      "x": 1,
      "y": 1,
      "z": 0.25
    }
  }
}

machine/axisSpeeds

Override smooth jog speeds on a per-axis basis. Allows moving specific axes slower or faster than the current smooth jog travel speed.

ui

Configuration for global interface settings.

{
  "ui": {
    "bgColor": 0,
    "brightness": 60,
    "columns": 5,
    "font": "monospace",
    "fontSize": 16,
    "lineHeight": 1.2,
    "gcodeColors": {
      "G0": "#52ff2e",
      "G1": "#9a96ff",
      "G2G3": "#9a96ff"
    },
    "lineHeight": 1.1,
    "palette": [
      "#181818",
      "#bdc3c7",
      "#b71138",
      "#efa021",
      "#06D6A0",
      "#2a88c5",
      "#EF476F",
      "#02535e",
      "#1F2D3A"
    ],
    "pageColor": 0,
    "progressColor": 3,
    "rows": 3,
    "textColor": "#fff",
    "textSize": 1.2,
    "timeout": 180
  }
}

ui/gcodeColors

Gcode preview can use different colors for rapid travel, straight and curved cuts. Colors may use rgb(0, 50, 200), hex #001122 etc. Palette colors are not supported here.

The following variables are available to button conditions (like if and disabled), and templated text.

ui/palette

Palette colors are an array of color strings (of any length). You can refer to these colors in most places that expect a color by referencing their array index.

This helps keep your color choices consistent, and allows changing many colors at once if needed.

example

{
  "palette": [
    "#ccc",
    "rgb(0, 100, 255)",
    "salmon"
  ]
}

scenes

The scenes configuration controls the layout of buttons (from the buttons object), and is used to create individual pages. A scene represents a single page of visible buttons. It must have a unique name, so that it can be referred to by button actions for navigation.

example

{
  "scenes": {
    "myScene": {
      "buttons": [
        ["row1_button", null, null, "row1_button"],
        [],
        ["row3_button"]
      ]
    }
  }
}

scenes/<unique scene name>

Individual scenes contain a single key: buttons.

The buttons value is a nested array of button IDs, with each inner array representing a row of buttons.

null values represent an empty space, and can be used in place of button IDs to space later buttons in the row.

Scenes should not contain more than the configured row or column count, and this behavior is considered undefined. However, scenes can have fewer items than the row or column.

The following would display eight buttons in a 3x3 grid, with the center square empty.

example

{
  "buttons": [
    ["b1", "b2", "b3"],
    ["b4", null, "b5"],
    ["b6", "b7", "b8"]
  ]
}

Instead of a button ID, another nested array (containing button IDs) can be used in a row. In this case, only the last visible button in the array will be displayed. This is useful for making toggle buttons (technically two different buttons), or other conditional buttons that occupy the same space.

example

{
  "buttons": [
    [
      "row1_button",
      [
        "conditional_button1",
        "conditional_button2"
      ]
    ],
    ["row2_button"],
    ["row3_button"]
  ]
}

Several scenes have special meaning:

• The home scene must exist, as it is used when the webpage or process first loads.
• The numpad scene must exist if any buttons use the enterWcs or enterPosition button actions.
• The gcodeList scene should not exist in your scenes list, but is always available for navigation events anyway.

Gcode File list

The file list scene layout is not configurable, since it is dynamically generated. However, the buttons used in this scene can have their appearance customized.

It is recommended that configuration of these buttons be limited background color and image only.

streamdeckUi

This section has the exact same structure as the ui configuration. Properties in streamdeckUi will override those of the ui section, when using a Stream Deck, and are ignored in the web version.

This allows the use of smaller fonts, brighter colors, or more aggressive throttling/rendering limits.

All properties are optional.

buttons

The buttons configuration defines buttons, their appearance details, and what (if anything) happens when buttons are pressed, released or held. Scenes will refer to these buttons by their unique ID to display them their layout.

example

{
  "buttons": {
    "my_button": {
      "bgColor": "#ffccaa",
      "icon": "custom/my_icon.png",
      "text": "Oh no!",
      "textAlignment": "top right",
      "actions": [
        {
          "action": "navigate",
          "arguments": ["home"],
          "event": "hold"
        }
      ]
    }
  }
}

buttons/<unique button name>

button/actions

A button’s actions value defines what happens when a button is activated. Buttons can take multiple actions when pressed, or when released, or when held down for a few moments, or a combination of those.

When a hold action is defined, any following up action will be skipped. This allows buttons to perform an action when pressed briefly, and perform a different action if pressed for a longer period, exclusively.