Pixelblaze

https://electromage.com/docs
Admin
Pixelblaze is an LED controller and pattern engine that enables creation of synchronized LED...
Tokens:25,562
Snippets:322
Trust Score:7.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Controls

Source: https://electromage.com/docs/websockets-api

Retrieve a list of all UI controls for a given pattern ID and their current values.

```APIDOC
## Get Controls

### Description
Retrieves the current values of all UI controls associated with a specific pattern.

### Method
Websocket Message (JSON)

### Request Body
```json
{
  "getControls": "<pattern_id>"
}
```

### Response Example
```json
{
  "controls":{
      "<pattern_id>":{
          "<control_name_1>": <value_1>,
          "<control_name_2>": <value_2>
      }
  }
}
```

### Parameters
- **getControls** (string) - Required - The ID of the pattern for which to retrieve controls.
```

--------------------------------

### Get Pixelblaze Controls by ID

Source: https://electromage.com/docs/websockets-api

Request a list of UI controls and their current settings for a specific pattern ID. This can be used for any pattern, not just the active one.

```json
{
  "getControls": "<id>"
}
```

--------------------------------

### Check for 3D Pixel Map

Source: https://electromage.com/docs/language-reference

Returns true if a 3D pixel map is currently installed, false otherwise.

```javascript
has3DMap()
```

--------------------------------

### Pixelblaze Variable Response

Source: https://electromage.com/docs/websockets-api

Example response format when requesting exported variables. It includes the current state of all exported variables.

```json
{
vars: {
    "myVar": 3.14159,
    "var2": 42,
    "untouched": -1.1,
    ...
}
}
```

--------------------------------

### Check for 2D Pixel Map

Source: https://electromage.com/docs/language-reference

Returns true if a 2D pixel map is currently installed, false otherwise.

```javascript
has2DMap()
```

--------------------------------

### Green Arrow Pattern (No Mapper)

Source: https://electromage.com/docs/intro-to-mapping

An example of a pattern written without using the mapper, which is specific to a 3x3 matrix. This code would need significant modification to work on different display sizes or configurations.

```javascript
export function render(x, y, z) {
  if (x < 1.5 && y < 1.5) {
    return [255, 255, 255];
  }
  return [0, 255, 0];
}
```

--------------------------------

### Get Clock/Time Components

Source: https://electromage.com/docs/language-reference

Retrieve components of the current time, including year, month, day, hour (24-hour format), minute, second, and weekday (Sunday=1). Requires the discovery service to be enabled and internet connectivity.

```javascript
clockYear()
```

```javascript
clockMonth()
```

```javascript
clockDay()
```

```javascript
clockHour()
```

```javascript
clockMinute()
```

```javascript
clockSecond()
```

```javascript
clockWeekday()
```

--------------------------------

### Power Calculation

Source: https://electromage.com/docs/language-reference

Calculates the `base` raised to the `exponent` power. Example: `pow(10, 2)` returns `100`.

```javascript
pow(10,2) == 100
```

--------------------------------

### Create HSV Color Picker

Source: https://electromage.com/docs/language-reference

Export a function starting with 'hsvPicker' followed by the picker's name to create an HSV color picker. The function receives hue, saturation, and value as parameters between 0.0 and 1.0.

```javascript
export function hsvPickerPrimaryColor(h, s, v) {...}
```

--------------------------------

### Create Toggle Switch

Source: https://electromage.com/docs/language-reference

Export a function starting with 'toggle' followed by the switch's name to create a toggle switch. The function is called with 'true' when turned on and 'false' when turned off.

```javascript
export function toggleEnableAwesomeness(isEnabled) {...}
```

--------------------------------

### Scan Network with nmap

Source: https://electromage.com/docs/quickstart-v3-standard

Use this nmap command to find your Pixelblaze's IP address on your network when not using the discovery service. The controller hostname typically starts with 'ESP_' or 'Espressif'.

```bash
nmap -sn 192.168.1.0/24
```

--------------------------------

### Display Number

Source: https://electromage.com/docs/language-reference

Export a function starting with 'showNumber' followed by the number's name to display a number. The function should return a number, which will be displayed with 4 decimal places.

```javascript
export function showNumberEnergyAverage() {return ...}
```

--------------------------------

### Fractional Component Extraction

Source: https://electromage.com/docs/language-reference

Extracts the fractional part of a number. Examples: `frac(5.5)` returns `0.5`, `frac(-5.5)` returns `-0.5`.

```javascript
frac(5.5) == 0.5
frac(-5.5) == -0.5
```

--------------------------------

### Create RGB Color Picker

Source: https://electromage.com/docs/language-reference

Export a function starting with 'rgbPicker' followed by the picker's name to create an RGB color picker. The function receives red, green, and blue values as parameters between 0.0 and 1.0.

```javascript
export function rgbPickerPrimaryColor(r, g, b) {...}
```

--------------------------------

### Quadratic Bezier Curve

Source: https://electromage.com/docs/language-reference

Calculates a point on a quadratic Bezier curve at parameter `t`. Requires start point `p0`, control point `p1`, and end point `p2`.

```javascript
bezierQuadratic(t, p0, p1, p2)
```

--------------------------------

### Base 2 Logarithm Calculation

Source: https://electromage.com/docs/language-reference

Calculates the base 2 logarithm of a number. Example: `log2(256)` returns `8`.

```javascript
log2(256) == 8
```

--------------------------------

### Display Gauge

Source: https://electromage.com/docs/language-reference

Export a function starting with 'gauge' followed by the gauge's name to display a gauge. The function should return a number between 0.0 and 1.0, representing a percentage. Values outside this range are clamped.

```javascript
export function gaugeLightLevel() {return ...}
```

--------------------------------

### Create Number Input

Source: https://electromage.com/docs/language-reference

Export a function starting with 'inputNumber' followed by the input's name to create a number input. The function is called with the new value when a number is entered or when the pattern is switched.

```javascript
export function inputNumberScale(v) {...}
```

--------------------------------

### Create Trigger Button

Source: https://electromage.com/docs/language-reference

Export a function starting with 'trigger' followed by the button's name to create a trigger button. This function is called only when the button is pressed and takes no parameters.

```javascript
export function triggerFireLasers() {...}
```

--------------------------------

### Set Color Palette Gradient

Source: https://electromage.com/docs/language-reference

Defines a color palette using an array of positions and RGB values. This allows for smooth color gradients. The example fades from black to magenta to cyan.

```javascript
var rgbGradient = [
    0,    0, 0, 0, //position start, rgb(0,0,0)
    0.75, 1, 0, 1, //position 75%, rgb(1,0,1)
    1,    0, 1, 1  // position end, rgb(0,1,1)
  ]
  setPalette(rgbGradient)
```

--------------------------------

### Replace Array Elements at Offset

Source: https://electromage.com/docs/language-reference

Replaces elements of an array starting at a specified offset with provided arguments. The arguments must fit within the array at the given offset. Other elements are unaffected.

```javascript
arrayReplaceAt(a, offset, ...)
a.replace(offset, ...)
```

--------------------------------

### Getting and Setting Variables

Source: https://electromage.com/docs/websockets-api

Allows for the retrieval and modification of exported variables within the currently active Pixelblaze pattern. For V2 and V3, variables can be exported using `export var name = value` in the pattern code.

```APIDOC
## Setting Variables
### Description
Send a JSON text frame to set the values of exported variables.
### Method
JSON Text Frame
### Request Example
```json
{
  "setVars": {
    "myVar": 3.14159,
    "var2": 42
  }
}
```

## Getting Variables
### Description
Send a JSON text frame to retrieve the current values of all exported variables.
### Method
JSON Text Frame
### Request Example
```json
{
  "getVars": true
}
```
### Response Example
```json
{
  "vars": {
    "myVar": 3.14159,
    "var2": 42,
    "untouched": -1.1
  }
}
```
```

--------------------------------

### Reduce Array to a Single Value

Source: https://electromage.com/docs/language-reference

Applies a reducer function to each element of an array, accumulating a single result. An initial value is used to seed the accumulator. Examples include summing, finding max, counting, and finding the index of the closest value.

```javascript
arrayReduce(a, (acc, v) => acc + v, 0)
arrayReduce(a, (acc, v) => max(acc,v), a[0])
key = 5; arrayReduce(a, (acc, v) => acc + (v == key), 0)
target = 5; arrayReduce(a, (acc, v, i, a) => abs(target - v) < abs(target - a[acc]) ? i : acc , 0)
a.reduce(fn, initialValue)
```

--------------------------------

### Get Pixel Map Dimensions

Source: https://electromage.com/docs/language-reference

Returns the number of dimensions in the current pixel map. Returns 0 if no pixel map is installed.

```javascript
pixelMapDimensions()
```

--------------------------------

### Control Onboard LED (Pixelblaze v2)

Source: https://electromage.com/docs/GPIO

Demonstrates controlling the onboard status LED on Pixelblaze v2 using `digitalWrite`. This functionality is not available on v3.

```javascript
digitalWrite(12, HIGH_OR_LOW)
```

--------------------------------

### Mode Initialization with Arrow Functions

Source: https://electromage.com/docs/language-reference

Initialize different modes using arrow functions. Ensure `currentMode` is defined and within the bounds of the `modes` array.

```javascript
modes[0] = () => {/* do mode 0 */};
  modes[1] = () => {/* do mode 1 */};
  // ...
  modes[currentMode]();
```

--------------------------------

### Square Root Calculation

Source: https://electromage.com/docs/language-reference

Calculates the square root of a number. Example: `sqrt(9)` returns `3`.

```javascript
sqrt(9) == 3
```

--------------------------------

### Function Declaration

Source: https://electromage.com/docs/language-reference

Demonstrates defining a function using the 'function' keyword.

```javascript
function myFunction(arg1) {return arg1 * 2}
```

--------------------------------

### Absolute Value Calculation

Source: https://electromage.com/docs/language-reference

Calculates the absolute value of a number. Example: `abs(-2)` returns `2`.

```javascript
abs(-2) == 2
```

--------------------------------

### Detect Sensor Board Connection

Source: https://electromage.com/docs/sensor-expansion-board

Initialize a sensor array with an impossible value to detect if the sensor board is connected. Use the `beforeRender` function to conditionally execute code based on the sensor board's presence.

```javascript
// It's important to init these reserved-word
// sensor arrays' names to the correct size
export var frequencyData = array(32)
// Start with an impossible value for data from the SB
frequencyData[0] = -1

export function beforeRender(delta) {
  if (frequencyData[0] == -1) {
    // Code for when no sensor board is connected
  } else {
    // Code for when the sensor board *is* connected
  }
}
```

--------------------------------

### Read ADC and Control Brightness (Pixelblaze v3)

Source: https://electromage.com/docs/GPIO

Configures a pin for analog input, reads its value, and uses it to control LED brightness. Values are 0-1 for 0-3.3V.

```javascript
// Set the pin labeled IO33 to use its ADC (A-to-D Converter)
pinMode(33, ANALOG)

// Export this var to monitor the value live in the IDE's Vars Watch
export var knobVal

export function beforeRender(delta) {
  // Read the value once per frame
  // Values are in 0-1 for 0-3.3 V sensed on the pin
  knobVal = analogRead(33)
}

export function render(index) {
  // Scale the output brightness from 0 - 100% based on the sensed voltage
  hsv(0, 1, knobVal)
}
```

--------------------------------

### Get Array Length

Source: https://electromage.com/docs/language-reference

Returns the number of elements in an array. The `.length` property is a direct access, not a function call.

```javascript
arrayLength(a)
a.length
```

--------------------------------

### Export Sensor Variables

Source: https://electromage.com/docs/language-reference

Declare variables for sensor expansion board data. These can have optional defaults if the board is not connected.

```javascript
export var frequencyData
  export var energyAverage
  export var maxFrequencyMagnitude
  export var maxFrequency
  export var accelerometer
  export var light
  export var analogInputs
```

--------------------------------

### Lambda Function Declaration

Source: https://electromage.com/docs/language-reference

Demonstrates defining a function using the short lambda-style form.

```javascript
myFunction = (arg1) => arg1 * 2
```

--------------------------------

### Get Node ID

Source: https://electromage.com/docs/language-reference

Retrieve the integer node ID configured in settings. Useful for controlling behavior within a group.

```javascript
nodeId()
```

--------------------------------

### Integer Component Extraction

Source: https://electromage.com/docs/language-reference

Returns the integer part of a number. Examples: `trunc(5.5)` returns `5`, `trunc(-5.5)` returns `-5`.

```javascript
trunc(5.5) == 5
trunc(-5.5) == -5
```

--------------------------------

### Implicit vs. Explicit Variable Assignment

Source: https://electromage.com/docs/language-reference

Demonstrates implicit global variable assignment and explicit local variable declaration using `var` within a function.

```javascript
function() {bar = 123}
function() {var baz = 123}
```

--------------------------------

### Floor Function Usage

Source: https://electromage.com/docs/language-reference

Rounds a number down to the next smallest integer. Examples: `floor(5.9)` returns `5`, `floor(-5.1)` returns `-6`.

```javascript
floor(5.9) == 5
floor(-5.1) == -6
```

--------------------------------

### Ceiling Function Usage

Source: https://electromage.com/docs/language-reference

Rounds a number up to the next largest integer. Examples: `ceil(5.1)` returns `6`, `ceil(-5.9)` returns `-5`.

```javascript
ceil(5.1) == 6
ceil(-5.9) == -5
```

--------------------------------

### Listing Patterns

Source: https://electromage.com/docs/websockets-api

Retrieves a list of all available patterns stored on the Pixelblaze device. The response is delivered via a binary frame protocol for efficiency.

```APIDOC
## Listing Patterns
### Description
Send a JSON text frame to request a list of all patterns on the Pixelblaze board.
### Method
JSON Text Frame
### Request Example
```json
{
  "listPrograms": true
}
```
### Response
#### Success Response
The response uses a binary frame protocol. Each frame contains a 2-byte header indicating frame type and flags, followed by a tab-separated list of pattern IDs and names. Concatenate frames until the end frame flag (0x04) is detected.
- **Frame Header**: `0x07` (program list), `0x01/0x04` (start/end frame flags, `0x05` for single frame)
- **Data**: Tab separated list of `id` + `\t` + `name` per line.
```

--------------------------------

### Control Pixelblaze Brightness

Source: https://electromage.com/docs/websockets-api

Send a JSON frame with a brightness value between 0.0 and 1.0 to adjust the overall brightness. This setting is not saved between restarts.

```json
{
  "brightness": 0.5
}
```

--------------------------------

### Set Pin Mode

Source: https://electromage.com/docs/language-reference

Configure a pin for input or output. Note specific pull-up/down behavior for V2 devices on GP16.

```javascript
pinMode(pin, mode)
```

--------------------------------

### Get Exported Variables via Websockets

Source: https://electromage.com/docs/websockets-api

Send a JSON frame to request the current values of all exported variables. The response contains variable states after the last pixel render.

```json
{
"getVars": true
}
```

--------------------------------

### Input / Output Functions

Source: https://electromage.com/docs/language-reference

Functions for reading analog input from devices.

```APIDOC
## readAdc()

### Description
Reads the value from the ADC as a number between 0.0 and 1.0. **_This function is only available on V2 devices_**

### Returns
- (number) The ADC value between 0.0 and 1.0.

## analogRead(`pin`)

### Description
Reads the value from the pin as a number between 0.0 and 1.0. **_This function is only available on V3 devices_**

### Parameters
- **pin** (number) - The analog pin to read from.

### Returns
- (number) The analog read value between 0.0 and 1.0.
```

--------------------------------

### List All Patterns on Pixelblaze

Source: https://electromage.com/docs/websockets-api

Send a JSON frame to request a list of all patterns stored on the Pixelblaze board. The response is delivered via a binary frame protocol.

```json
{
"listPrograms": true
}
```

--------------------------------

### Sensor Expansion Board Data

Source: https://electromage.com/docs/language-reference

Access to data from the sensor expansion board, including microphone, accelerometer, and light sensor.

```APIDOC
## Sensor Data Exports

### Description
These variables are exported by the sensor expansion board and can be accessed directly in your patterns. Optional defaults can be provided if the board is not connected.

### Exported Variables
- **frequencyData** (array) - 32 element array with frequency magnitude data ranging from 12.5-10khz.
- **energyAverage** (number) - Total audio volume.
- **maxFrequencyMagnitude** (number) - The magnitude of the strongest detected frequency.
- **maxFrequency** (number) - The strongest detected frequency in Hz.
- **accelerometer** (array) - 3 element array with [x,y,z] acceleration data (16G range).
- **light** (number) - Ambient light sensor value.
- **analogInputs** (array) - 5 element array with analog values from A0-A4.
```

--------------------------------

### Modulo Operation with Floored Remainder

Source: https://electromage.com/docs/language-reference

Calculates the floored remainder of `x/y`. The result has the same sign as `y`. Example: `mod(-3.5, 3)` returns `2.5`, unlike `-3.5 % 3` which returns `-.5`.

```javascript
mod(-3.5, 3) == 2.5
-3.5 % 3 == -.5
```

--------------------------------

### Match Ambient Light Level with Light Sensor

Source: https://electromage.com/docs/sensor-expansion-board

Adjusts display intensity based on ambient light levels using a running average to smooth out readings. Samples light readings at a controlled rate.

```javascript
// White light in proportion to the ambient light level

export var light        // Sensor board variable
var avgLight            // Light value to use in a pattern

var sampleSize = 50
var samples = array(sampleSize)
var sampleIdx = 0
var samplesTotal = 0

// Circular buffer
function runningAverage(sample) {
  samplesTotal -= samples[sampleIdx] // Remove the oldest value
  samplesTotal += sample             // Add this value
  samples[sampleIdx] = sample        // Store this value
  sampleIdx = (sampleIdx + 1) % sampleSize // Roll the index
  return samplesTotal / sampleSize   // Average = total / count
}

deltaAccumlator = 0
export function beforeRender(delta) {
  deltaAccumlator += delta
  // Sample light readings no faster than every 25ms
  // as the sensor board sends readings at ~40 Hz
  if (deltaAccumlator > 25) {
    deltaAccumlator = 0
    // Stores sample and return average
    avgLight = runningAverage(light)
  }
}

export function render(index) {
  // Minimum inensity in total darkness
  v = clamp(avgLight, 0.01, 1)
  hsv(0, 0, v)
}
```

--------------------------------

### Hypotenuse Calculation with Two Arguments

Source: https://electromage.com/docs/language-reference

Calculates the hypotenuse of a right triangle with sides `x` and `y`, equivalent to the distance from the origin to point `(x,y)`. Example: `hypot(3, 4)` returns `5`.

```javascript
hypot(3, 4) == 5
```

--------------------------------

### Generate 3D Fractal Perlin Noise (FBM)

Source: https://electromage.com/docs/language-reference

Generates 3D fractal Perlin noise (fractal Brownian Motion). Values repeat based on wrap settings and can seamlessly loop. Lacunarity controls octave spacing (integer recommended for wrapping), and gain controls octave strength (0.5-0.8 recommended).

```javascript
perlinFbm(x, y, z, lacunarity, gain, octaves)
```

--------------------------------

### Cubic Bezier Curve

Source: https://electromage.com/docs/language-reference

Calculates a point on a cubic Bezier curve at parameter `t`. Requires start point `p0`, two control points `p1`, `p2`, and end point `p3`.

```javascript
bezierCubic(t, p0, p1, p2, p3)
```

--------------------------------

### Toggle Digital Outputs (Pixelblaze ESP32)

Source: https://electromage.com/docs/GPIO

Configures two pins as outputs and toggles them on and off based on time to create an alternating pattern. Suitable for ESP32-based Pixelblaze devices.

```javascript
pinMode(25, OUTPUT) // Pin labeled IO25 set as an output
pinMode(26, OUTPUT)

export function beforeRender(delta) {
  t1 = time(2 / 65.535) // Ramp 0..1 every 2 seconds
  digitalWrite(25, t1 < .5) // Set IO25 high for the 1st second
  digitalWrite(26, t1 >= .5)
}

export function render(index) { hsv(0, 0, 0) }
```

--------------------------------

### Set Perlin Noise Wrap

Source: https://electromage.com/docs/language-reference

Configures Perlin noise functions to wrap at specified intervals. Useful for seamless texture generation. Intervals must be integers between 2 and 256.

```javascript
setPerlinWrap(256, 256, 256)
```

--------------------------------

### Shake to Switch Modes with Accelerometer

Source: https://electromage.com/docs/sensor-expansion-board

Use the accelerometer to detect shakes and cycle through different display modes. Includes debouncing to prevent rapid mode changes.

```javascript
// Shake to switch modes

export var accelerometer  // Enable the accelerometer
mode = debounce = 0

export function beforeRender(delta) {
  // 3D vector sum of x, y, and z acceleration
  totalAcceleration = sqrt(
    accelerometer[0] * accelerometer[0] +
    accelerometer[1] * accelerometer[1] +
    accelerometer[2] * accelerometer[2]
  )

  debounce = clamp(debounce + delta, 0, 2000) // Prevent overflow

  // Cycle mode if sensor board is shaken, no more than 1x / sec
  if (debounce > 1000 && totalAcceleration > 0.03) {
    mode = (mode + 1) % 3
    debounce = 0
  }
}

h = s = v = 1
modes = array(3)
modes[0] = (index) => { h = 1 - index / pixelCount / 4; v = 1 }
modes[1] = (index) => { h = 0.5; v = index % 2 }
modes[2] = (index) => { h = wave((index+wave(time(0.04))*5)/pixelCount)*6; v = 0.1+random(wave(time(0.03))) }

export function render(index) {
  modes[mode](index)
  hsv(h, s, v)
}
```

--------------------------------

### Set Controls

Source: https://electromage.com/docs/websockets-api

Set the values for UI controls in the currently active pattern. Values can be optionally persisted.

```APIDOC
## Set Controls

### Description
Sets the values for UI controls in the active pattern. Supports sliders and color pickers. Values can be optionally persisted to flash memory.

### Method
Websocket Message (JSON)

### Request Body
```json
{
  "setControls": {
    "<control_name_1>": <value_1>,
    "<control_name_2>": <value_2>
  },
  "save": true (optional)
}
```

### Parameters
- **setControls** (object) - Required - An object containing control names as keys and their desired values.
  - Sliders expect a single numeric value between 0.0 and 1.0.
  - HSV and RGB color pickers expect an array of 3 numeric values, each between 0.0 and 1.0.
- **save** (boolean) - Optional - If true, the control values will be persisted after a delay, otherwise they are temporary for the current session.
```

--------------------------------

### Access All Sensor Data

Source: https://electromage.com/docs/sensor-expansion-board

Declare all available sensor variables to access the complete set of sensor data. This includes frequency, energy, accelerometer, analog inputs, and light.

```javascript
export var frequencyData
export var energyAverage
export var maxFrequencyMagnitude
export var maxFrequency
export var accelerometer
export var analogInputs
export var light

export function render(index) {}
```

--------------------------------

### Clock / Time Functions

Source: https://electromage.com/docs/language-reference

Functions to retrieve current time information when the discovery service is enabled and the device is connected to the internet.

```APIDOC
## clockYear()

### Description
Returns the current year.

## clockMonth()

### Description
Returns the current month (1-12).

## clockDay()

### Description
Returns the current day of the month (1-31).

## clockHour()

### Description
Returns the current hour in 24-hour format (0-23).

## clockMinute()

### Description
Returns the current minute (0-59).

## clockSecond()

### Description
Returns the current second (0-59).

## clockWeekday()

### Description
Returns the current day of the week. Sunday = 1, Monday = 2, etc.
```

--------------------------------

### Replace Array Elements

Source: https://electromage.com/docs/language-reference

Replaces elements of an array starting from index 0 with provided arguments. The number of arguments must fit within the array's bounds. Excess array elements remain unchanged.

```javascript
arrayReplace(a, ...)
a.replace(...)
```

--------------------------------

### Response of Pixelblaze Controls

Source: https://electromage.com/docs/websockets-api

The response contains an object keyed to the pattern ID, listing each control's name and its current value(s).

```json
{
  "controls":{
      "qzpL3CLaMP3cqae2R":{
          "hsvPickerMyColor":[0.77,0.84,1],
          "sliderMySlider":0.4431
      }
  }
}
```

--------------------------------

### Set HSV Color (24-bit)

Source: https://electromage.com/docs/language-reference

Sets the current pixel color using HSV values, restricted to 24-bit color. Hue wraps between 0.0 and 1.0. Negative values wrap backwards. This may reduce flickering on some LEDs.

```javascript
hsv24(0.5, 1.0, 1.0)
```

--------------------------------

### Pixelblaze Before Render Function

Source: https://electromage.com/docs/language-reference

The `beforeRender(delta)` function is called once per frame before pixels are rendered. Use the `delta` argument (milliseconds elapsed) to create animations with consistent speed.

```javascript
export function beforeRender(delta) {
  // Animation logic here
}
```

--------------------------------

### Activate a Specific Pattern

Source: https://electromage.com/docs/websockets-api

Send a JSON frame with the pattern ID to change the currently active pattern. This change is persistent and will survive device restarts.

```json
{
"activeProgramId": "<id>"
}
```

--------------------------------

### Pixelblaze Render Function

Source: https://electromage.com/docs/language-reference

The `render(index)` function is called for each pixel to set its color using `hsv` or `rgb`. The `index` parameter specifies the current pixel being rendered.

```javascript
export function render(index) {
  hsv(index / pixelCount, 1, 1)
}
```

--------------------------------

### Pixelblaze 2D/3D Render Functions

Source: https://electromage.com/docs/language-reference

Alternative render functions `render2D(index, x, y)` and `render3D(index, x, y, z)` can be specified for use with 2D or 3D pixel maps. The appropriate function is automatically selected.

```javascript
export function render2D(index, x, y) {
  hsv(x / 10, 1, 1)
}
```

```javascript
export function render3D(index, x, y, z) {
  hsv(z / 10, 1, 1)
}
```

--------------------------------

### Pixel / Color Functions

Source: https://electromage.com/docs/language-reference

Functions for setting pixel colors using HSV or RGB values, and for defining color palettes.

```APIDOC
## hsv(`hue`, `saturation`, `value`)

### Description
Sets the current pixel by calculating the RGB values based on the HSV color space. `Hue` "wraps" between 0.0 and 1.0. Negative values wrap backwards. For LEDs that support it, this uses 24-bit color plus an additional 5 bits of brightness control giving a high dynamic range especially at lower light levels and reduces posterization.

### Parameters
- **hue** (number) - The hue value, wraps between 0.0 and 1.0.
- **saturation** (number) - The saturation value.
- **value** (number) - The value (brightness) of the color.

## hsv24(`hue`, `saturation`, `value`)

### Description
Sets the current pixel by calculating the RGB values based on the HSV color space. `Hue` "wraps" between 0.0 and 1.0. Negative values wrap backwards. This uses 24-bit color only, even if the LEDs support additional resolution and may reduce flickering in some LEDs.

### Parameters
- **hue** (number) - The hue value, wraps between 0.0 and 1.0.
- **saturation** (number) - The saturation value.
- **value** (number) - The value (brightness) of the color.

## rgb(`red`, `green`, `blue`)

### Description
Sets the current pixel to the RGB value provided. Values range between 0.0 and 1.0.

### Parameters
- **red** (number) - The red component (0.0 to 1.0).
- **green** (number) - The green component (0.0 to 1.0).
- **blue** (number) - The blue component (0.0 to 1.0).

## setPalette(`array`)

### Description
Sets the palette to a gradient based on an array of positions and RGB values. For example, this fades from black to magenta to cyan:
```
var rgbGradient = [
    0,    0, 0, 0, //position start, rgb(0,0,0)
    0.75, 1, 0, 1, //position 75%, rgb(1,0,1)
    1,    0, 1, 1  // position end, rgb(0,1,1)
  ]
  setPalette(rgbGradient)
```

### Parameters
- **array** (array) - An array defining the color palette gradient.

## paint(`value`, [`brightness = 1`])

### Description
Sets the current pixel to a color based on the `value`'s position in the current palette. `Value` "wraps" between 0.0 and 1.0. Negative values wrap backwards. Optionally `brightness` can be specified.

### Parameters
- **value** (number) - The position in the palette (0.0 to 1.0).
- **brightness** (number, optional) - The brightness of the color (defaults to 1.0).
```

--------------------------------

### Generate 3D Perlin Noise

Source: https://electromage.com/docs/language-reference

Generates 3D Perlin noise. Each integer coordinate produces a unique, smoothly transitioning random value. Noise values repeat based on wrap settings and can seamlessly loop.

```javascript
perlin(x, y, z, seed)
```

--------------------------------

### Access Individual Sensor Data

Source: https://electromage.com/docs/sensor-expansion-board

Declare frequencyData to access sound energy levels. This snippet shows how to read a specific frequency magnitude.

```javascript
export var frequencyData

// Read the sound energy level around 237Hz,
//    near middle C
middleCMagnitude = frequencyData[7]
```

--------------------------------

### Apply Arbitrary Matrix Transform

Source: https://electromage.com/docs/language-reference

Applies a custom 4x4 matrix transformation to the coordinate system. This allows for complex transformations beyond standard translate, scale, and rotate.

```javascript
transform(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 10, 20, 0, 1)
```

--------------------------------

### Smooth Step Interpolation

Source: https://electromage.com/docs/language-reference

Provides a smooth interpolation between 0.0 and 1.0 based on a value `v` crossing between `low` and `high` thresholds. Values outside this range are clamped. Useful for easing transitions.

```javascript
smoothstep(low, high, v)
```

--------------------------------

### Perlin Noise Functions

Source: https://electromage.com/docs/language-reference

Functions for generating 3D fractal Perlin noise with options for wrapping, lacunarity, gain, and offset.

```APIDOC
## perlinRidge(`x`, `y`, `z`, `lacunarity`, `gain`, `offset`, `octaves`)

### Description
Generate 3D fractal ridged Perlin noise. The values will repeat every 256 or as specified with `setPerlinWrap()`, and can seamlessly wrap. The `lacunarity` controls the distance between octaves and should be set to 2 or another integer value if wrapping is desired. The `gain` controls the strength between each octave, try values around 0.5-0.8. The `offset` is used to invert the ridges, values around 1.0 work well.

### Parameters
- **x** (number) - The x-coordinate.
- **y** (number) - The y-coordinate.
- **z** (number) - The z-coordinate.
- **lacunarity** (number) - Controls the distance between octaves.
- **gain** (number) - Controls the strength between each octave.
- **offset** (number) - Inverts the ridges.
- **octaves** (number) - The number of noise octaves.

## perlinTurbulence(`x`, `y`, `z`, `lacunarity`, `gain`, `octaves`)

### Description
Generate 3D fractal turbulent Perlin noise. The values will repeat every 256 or as specified with `setPerlinWrap()`, and can seamlessly wrap. The `lacunarity` controls the distance between octaves and should be set to 2 or another integer value if wrapping is desired. The `gain` controls the strength between each octave, try values around 0.5-0.8.

### Parameters
- **x** (number) - The x-coordinate.
- **y** (number) - The y-coordinate.
- **z** (number) - The z-coordinate.
- **lacunarity** (number) - Controls the distance between octaves.
- **gain** (number) - Controls the strength between each octave.
- **octaves** (number) - The number of noise octaves.

## setPerlinWrap(`x`, `y`, `z`)

### Description
Causes perlin functions to wrap at the given integer intervals between 2 and 256. Useful for creating textures that can repeat smoothly, while controlling density.

### Parameters
- **x** (number) - The wrapping interval for the x-axis.
- **y** (number) - The wrapping interval for the y-axis.
- **z** (number) - The wrapping interval for the z-axis.
```
Tokens:
Raw