CUBE4 RGB Cube Command List

The 4x4x4 RGB LED Cube driver library supports direct commands sent to the Cube via USB. Using the Arduino IDE, open the serial console and set the speed to 115,200bps. You can then type commands into the input box at the top, and press ENTER to send them to the Cube.

All commands must end with a semicolon, ";".

You can use a combination of commands, location identifiers, and colours to specify different results on the Cube. To get started, try typing in the following commands to see what happens. Later you can read the explanation below to understand how the commands work, and how to create your own.

help;
all red;
all green;
setplane X0 red;
set 300 blue;
set 333 pink;
copyplane X 3 2;
moveplane X 2 0 green;

Defining Locations

You can reference different locations within the matrix in several ways, depending on whether you want to specify anything from a single LED to the entire Cube.

Select A Specific LED

The Cube uses X, Y, and Z coordinates to identify each individual LED within the matrix. The values in each axis can range from position 0 to position 3, and the X/Y/Z values are stated together so it looks like a 3-digit number. All axes begin with their "0" position in the front bottom left corner of the Cube, which is referred to as position "000".

The X axis projects horizontally towards the right. The higher the X value, the further right you go.

The Y axis projects horizontally towards the back. The higher the Y value, the further back you go.

The Z axis projects vertically towards the top. The higher the Z value, the further up you go.

For example, to specify the LED in the front bottom right corner, you move across the X axis to position 3 but leave the Y and Z axis unchanged so the coordinates are "300". To get to the top right front corner you move across the X axis and up the Y axis, to coordinates "330". And for the back top left position you leave X unchanged, move back on the Y axis, and move up on the Z axis to "033".

Select A Plane / Layer

The "plane" location applies to a slice of 16 LEDs within the cube, at a specified location and orientation. It uses a combination of the axis that you want to address, and the position within the axis.

For example, to select all the LEDs on the bottom layer of the Cube, you need to specify the Z axis (which defines the vertical position) and position 0. The bottom layer is therefore "Z0". Likewise, the top layer is "Z3".

To select all the LEDs on the front face of the Cube, you need to specify the Y axis (which defines the front-to-back position) and position 0, therefore "Y0". The back face of the Cube is "Y3", and so on.

Select The Entire Cube

As a convenient shorthand for applying a command to the entire cube, you can simply specify the "all" location.

Defining Colours

Colours can be specified using either RGB (red green blue) hexadecimal values just like in HTML, or by using predefined names.

For example, you can specify a strong red by setting a high R value with low G and B values, such as "FF0000".

Bright white requires setting the R, G, and B values all to their maximum value, ie: "FFFFFF".

Turning an LED off entirely is done by setting all values to 0, ie: "000000".

Currently supported predefined colour names are BLACK, BLUE, GREEN, ORANGE, PINK, PURPLE, RED, WHITE, and YELLOW.

Available Commands

The location and colour definitions are combined with commands to generate different displays.

Entire Cube

all <colour>;

Set the entire cube to the specified colour. Eg: "all red;"

shift <axis> <direction>;

Move all LED colours in the specified direction. Eg: "shift X +;", or "shift Y -;"

Single LED

set <location> <colour>;

Set a single LED to the colour specified. Eg: "set 223 green;", or "set 011 6600aa;"

next <colour>;

Go to the next LED after the last one used and set it to the specified colour. Eg: "next blue;", or "next 0000ff;"

One Axis

setplane <axis> <offset> <colour>;

Set one plane of LEDs to the colour specified. Eg: "setplane X 2 orange;", or "setplane Y 3 00ff00;"

copyplane <axis> <from offset> <to offset>;

Copy all the LED settings from one plane to another. Eg: "copyplane X 2 1;"

moveplane <axis> <from offset> <to offset> <colour>;

Move all the LED settings from one plane to another, and fill in the LEDs left behind using the specified colour. Eg: "moveplane Z 1 3 black;", or "moveplane X 3 0 green;"