Pixelblaze LED Controller Documentation

The pixel mapping system allows patterns to be aware of the physical LED layout (e.g., matrices, rings, or 3D shapes). Instead of treating LEDs as a simple 1D list, the system uses a pixel map to assign each pixel a coordinate in a 2D or 3D space.

Core Workflow

1. Define a Pixel Map: Create a map in the Mapper tab specifying coordinates for every pixel. Coordinates can be pairs [x, y] for 2D or triplets [x, y, z] for 3D.
2. Coordinate Scaling: The system automatically scales your input coordinates (whether in inches, mm, or pixels) to a normalized range of 0.0 to 1.0. This represents the position within the mapped "world."
3. Pattern Rendering: Patterns use specialized render functions to access these coordinates. Because coordinates are normalized, a single pattern can work on any physical layout by scaling to the mapped world size.

Scaling Options

When defining the map, you can choose how the world dimensions are handled:

• Fill: Stretches or squishes the map to fit every dimension.
• Contain: Maintains the aspect ratio, resizing to fit the largest dimension.

// Example of the mental model: patterns use normalized coordinates
// regardless of the physical size of the LED array.
export function render2D(index, x, y) {
  // x and y are between 0.0 and 1.0
  hsv(x, 1, y)
}

Pixelblaze uses specific exported functions to drive the pixel strip. The engine looks for these functions to determine how to generate colors and handle timing.

Core Render Functions

• render(index): The primary function called for every pixel. The index argument represents the current pixel position. Use hsv() or rgb() within this function to set the color.
• render2D(index, x, y) and render3D(index, x, y, z): Alternative render functions used if a 2D or 3D pixel map is configured in the Mapper tab.

Animation and Timing

• beforeRender(delta): Called once before a new frame is rendered. The delta argument is the elapsed time in milliseconds since the last call (with 6.25ns resolution). Use delta to ensure animations run at a consistent speed regardless of frame rate.

Global Constants

• pixelCount: A global variable representing the total number of configured LED pixels.

export function render(index) {
  hsv(0, 1, 1);
}

export function beforeRender(delta) {
  // Use delta for frame-rate independent animations
}

You can create persistent UI controls that appear when a pattern is active. These allow users to change pattern behavior without editing code. Controls are created by exporting functions with specific name prefixes.

Input Controls

These functions are called when the user interacts with the UI. You should typically store the incoming value in a variable to use in your pattern.

Output Controls

These functions are called frequently to display information in the UI. They must return a value.

Note: Controls are persistent and their settings are preserved across restarts.

var mySetting = 0.5
export function sliderMySetting(v) {
	mySetting = v
}

export function hsvPickerPrimaryColor(h, s, v) {
  // Use h, s, v to set colors
}

export function gaugeLightLevel() {
  return light / 100; // Example return
}

Pixelblaze enclosures are available in four variants based on how you intend to connect your LED strips and power. The choice depends on whether you prefer soldering or using pre-soldered connectors.

Ready-to-Run (R2R)

Designed specifically for the "no soldering required" Pixelblaze version.

• Connector: Uses a JST-XH connector pre-installed on the underside of the circuit board.
• Openings: Has an opening on the bottom for the JST-XH and a side opening for an optional USB power connection (2.1A max).

Flexible Connection

Designed for users who want to choose their connection method. You must snap out the plastic for the specific output openings you need.

• Option 1: Traditional screw terminal soldered to the top of the board.
• Option 2: JST-XH soldered to the top of the board.
• Option 3: JST-XH soldered to the bottom of the board (similar to the R2R version).
• Openings: Supports any of the above plus an optional USB power-in connection.