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;"
CUBE4 RGB Cube Custom Firmware
The 4x4x4 RGB Cube is Arduino compatible, and has the same ATmega32u4 MCU as found in the Arduino Leonardo and the Freetronics LeoStick. The Cube ships with test pattern firmware already loaded, but you can replace it with one of our example sketches or write your own.
Download And Install Arduino IDE
If you don't have the Arduino IDE already installed, download and install the current version to suit your operating system from www.arduino.cc/en/Main/Software.
Install The Cube4 Library
Download the Cube4 library from the Freetronics repository on GitHub and install it in your Arduino IDE. Visit the following repository in your browser, and click the "ZIP" button near the top left to download it as a ZIP archive:
https://github.com/freetronics/Cube4/
Uncompress the archive and rename the folder to "Cube4", then move it into your sketchbook/libraries/ folder. Restart the IDE.
For more detailed instructions, see How To Install Arduino Libraries.
Install the LeoStick Board Profile
It is possible to use the Arduino Leonardo option (Tools -> Board -> Arduino Leonardo in the Arduino IDE) to upload to the Cube4.
However if you install the LeoStick Board Profile by following the LeoStick Getting Started Guide then you can choose "Tools -> Board -> Freetronics LeoStick V2.0" instead and the Cube4 will then correctly identify itself as a Freetronics device.
On Windows you will also need to install the Freetronics Windows driver file.
Example Sketches
After installing the Cube4 library and restarting the IDE, you will now have new entries in the examples menu at File -> Examples -> Cube4. Look through them for examples of different patterns you can run on your Cube4.
The examples are also a good way to learn how to write your own sketches to run on your Cube4. Look at the sketch source code to see how they address and update LEDs.
Library API
The library API follows a similar structure to the serial command API.
More information to come.