Set pixels

What this example shows

How to light single LEDs by their (x, y) position. The sketch sets a low brightness, colours three corners and two pixels in the middle, once with separate red, green and blue values and once with a packed colour, and then sends everything to the grid in one show().

Wire VCC to 5 V, GND to GND and DIN to pin 6 of your controller, or change PIN to the pin you used.

The example code

This is SetPixel.ino from the pinned library, exactly as shipped.

Select Board

SetPixel.ino

/**
 **************************************************
 *
 * @file        SetPixel.ino
 * @brief       Basic usage: set individual pixels by (x, y) coordinates on the
 *              Soldered 8x8 WS2812B LED grid.
 *
 *              Connect the grid data line to PIN below.
 *              (0, 0) is top-left. X increases to the right, Y increases downward.
 *
 * @authors     Josip Šimun Kuči @ soldered.com
 ***************************************************/

#include "WS2812Grid-SOLDERED.h"

#define PIN 6

WS2812Grid grid(PIN);

void setup()
{
    grid.begin();

    // Set overall brightness (0 = off, 255 = full).
    // Keep this low to avoid excessive current draw.
    grid.setBrightness(40);

    // Draw a red pixel at the top-left corner
    grid.setPixel(0, 0, 255, 0, 0);

    // Draw a green pixel at the top-right corner
    grid.setPixel(7, 0, 0, 255, 0);

    // Draw a blue pixel at the bottom-left corner
    grid.setPixel(0, 7, 0, 0, 255);

    // Draw a white pixel in the centre using a packed color
    grid.setPixel(3, 3, WS2812Grid::Color(255, 255, 255));
    grid.setPixel(4, 4, WS2812Grid::Color(255, 255, 255));

    // Push all changes to the hardware
    grid.show();
}

void loop()
{
    // Nothing to do — pixels stay lit
}

Expected result: the sketch prints nothing to the Serial Monitor. Right after the upload, the top-left pixel (0, 0) lights red, the top-right pixel (7, 0) green, the bottom-left pixel (0, 7) blue, and the pixels at (3, 3) and (4, 4) white, all at brightness 40 out of 255. They stay lit, because loop() does nothing.

Functions used

WS2812Grid(uint8_t pin, uint8_t width = 8, uint8_t height = 8)returns WS2812Grid

Creates the grid driver for width x height LEDs on the pin wired to DIN. One grid is 8 x 8, the default. For several chained grids, pass the panel's full width and height.

ReturnsThe grid object.

Parameters

Type	Name	Description
uint8_t	pin	Arduino pin connected to the grid's DIN.
uint8_t	width	Number of columns, a multiple of 8. Default 8.
uint8_t	height	Number of rows, a multiple of 8. Default 8.

begin()returns void

Initialises the LED driver, setting the data pin as an output, then clears every pixel and calls show(), so the grid starts dark. Call it once in setup().

ReturnsNothing.

setBrightness(uint8_t b)returns void

Sets the output brightness for all LEDs. The change shows at the next show(). It is meant to be set once in setup(): the library scales the stored colours, so changing it again and again loses colour precision.

ReturnsNothing.

Parameters

Type	Name	Description
uint8_t	b	Brightness, 0 (off) to 255 (brightest).

setPixel(uint8_t x, uint8_t y, uint8_t r, uint8_t g, uint8_t b)returns void

Sets one LED by its grid position to separate red, green and blue values. A position outside the grid is ignored. Call show() afterwards to send the change to the LEDs.

ReturnsNothing.

Parameters

Type	Name	Description
uint8_t	x	Column, 0 = left.
uint8_t	y	Row, 0 = top.
uint8_t	r	Red, 0 to 255.
uint8_t	g	Green, 0 to 255.
uint8_t	b	Blue, 0 to 255.

setPixel(uint8_t x, uint8_t y, uint32_t color)returns void

Sets one LED by its grid position to a packed colour, such as one made with WS2812Grid::Color(). A position outside the grid is ignored. Call show() afterwards to send the change to the LEDs.

ReturnsNothing.

Parameters

Type	Name	Description
uint8_t	x	Column, 0 = left.
uint8_t	y	Row, 0 = top.
uint32_t	color	Packed colour, 0x00RRGGBB.

WS2812Grid::Color(uint8_t r, uint8_t g, uint8_t b)returns uint32_t

A static helper that packs red, green and blue into one 32-bit colour value, for setPixel() with a packed colour. Call it on the class, as WS2812Grid::Color().

ReturnsThe packed colour, (r << 16) | (g << 8) | b.

Parameters

Type	Name	Description
uint8_t	r	Red, 0 to 255.
uint8_t	g	Green, 0 to 255.
uint8_t	b	Blue, 0 to 255.

show()returns void

Sends the colours held in memory to the LEDs. On most boards it briefly turns interrupts off to keep the signal timing, so millis() and micros() lose about 30 µs per LED each time it runs.

ReturnsNothing.

Putting it together

Create the grid with the pin wired to DIN, call begin() once, set the brightness, then set as many pixels as you like and finish with one show(). Nothing changes on the grid until show() runs. Raising the brightness above 40 makes the LEDs brighter and draws more current, so check your 5 V supply first.

SourceOpen the verified Arduino exampleView the exact source used by this page.examples/SetPixel/SetPixel.ino