RGB LED Matrix

Purpose Of This Page

This page explains how to control the 4 by 4 RGB LED Matrix on the CodyJoy Pro using Python.

By the end of this page, students will be able to:

• Turn on one RGB LED by LED number.
• Turn on one RGB LED by (x, y) coordinate.
• Use built-in color codes.
• Use RGB hex colors.
• Use RGB percentage colors.
• Clear all RGB LEDs.

Start Code

Every CodyNick Python script should import the CodyNick library and connect to the CodyNick device.

import CodyNick

cn = CodyNick.CN()

The variable cn represents the connected CodyNick device. It is passed to the CodyNick functions so Python knows which device to control.

RGB LED Number Layout

The CodyJoy Pro RGB LEDs are numbered as shown below:

15  14  13  12
 8   9  10  11
 7   6   5   4
 0   1   2   3

Important positions:

• LED 0 is the bottom-left LED.
• LED 3 is the bottom-right LED.
• LED 15 is the top-left LED.
• LED 12 is the top-right LED.

Turn On One LED By Number

Use RGB_Matrix.set() to turn on one LED.

Function format:

CodyNick.RGB_Matrix.set(cn, led_number, color)

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set(cn, 15, "#FF0000")

This turns LED 15 red.

Another example:

CodyNick.RGB_Matrix.set(cn, 0, "#00FF00")

This turns LED 0 green.

Clear The RGB Matrix

Use RGB_Matrix.clear() to turn off all RGB LEDs.

CodyNick.RGB_Matrix.clear(cn)

Example:

import CodyNick
import time

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set(cn, 15, "#FF0000")
time.sleep(1)
CodyNick.RGB_Matrix.clear(cn)

This turns LED 15 red for one second, then turns all LEDs off.

Built-In Color Codes

The easiest way to choose a color is to use one of the built-in color codes from 0 to 7.

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set(cn, 15, 0)

This turns LED 15 red, because color code 0 means red.

RGB Hex Colors

Students can also use RGB hex colors.

An RGB hex color starts with # and has six hexadecimal characters:

"#RRGGBB"

RR controls red, GG controls green, and BB controls blue.

Common examples:

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set(cn, 12, "#00FFFF")

This turns LED 12 cyan.

RGB Percentage Colors

Students can also describe a color with red, green, and blue percentages.

Format:

[red_percent, green_percent, blue_percent]

Each number must be between 0 and 100.

Examples:

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set(cn, 10, [0, 100, 100])

This turns LED 10 cyan.

Coordinate Layout

Students can also control LEDs by (x, y) coordinate.

The bottom-left LED is (0, 0).

The top-right LED is (3, 3).

(0,3)  (1,3)  (2,3)  (3,3)
(0,2)  (1,2)  (2,2)  (3,2)
(0,1)  (1,1)  (2,1)  (3,1)
(0,0)  (1,0)  (2,0)  (3,0)

Use RGB_Matrix.set_xy() to control one LED by coordinate.

Function format:

CodyNick.RGB_Matrix.set_xy(cn, x, y, color)

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.set_xy(cn, 0, 0, "#FF0000")

This turns the bottom-left LED red.

Another example:

CodyNick.RGB_Matrix.set_xy(cn, 3, 3, 2)

This turns the top-right LED blue, because color code 2 means blue.

Example: Four Corners

This example lights the four corner LEDs with different colors.

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.clear(cn)

CodyNick.RGB_Matrix.set_xy(cn, 0, 0, 0)          # bottom-left red
CodyNick.RGB_Matrix.set_xy(cn, 3, 0, 5)          # bottom-right green
CodyNick.RGB_Matrix.set_xy(cn, 0, 3, 2)          # top-left blue
CodyNick.RGB_Matrix.set_xy(cn, 3, 3, "#FFFF00")  # top-right yellow

Example: Show All Built-In Colors

This example shows all eight built-in colors one by one.

import CodyNick
import time

cn = CodyNick.CN()

for color_code in range(8):
    CodyNick.RGB_Matrix.clear(cn)
    CodyNick.RGB_Matrix.set(cn, color_code, color_code)
    time.sleep(0.5)

In this loop, the LED number and the color code are both using color_code.

Example: Center LEDs

The center four LEDs are:

(1,2)  (2,2)
(1,1)  (2,1)

Example:

import CodyNick

cn = CodyNick.CN()

CodyNick.RGB_Matrix.clear(cn)

CodyNick.RGB_Matrix.set_xy(cn, 1, 1, "#FF0000")
CodyNick.RGB_Matrix.set_xy(cn, 2, 1, "#00FF00")
CodyNick.RGB_Matrix.set_xy(cn, 1, 2, "#0000FF")
CodyNick.RGB_Matrix.set_xy(cn, 2, 2, "#FFFFFF")

Practice Tasks

Try these exercises:

1. Turn on LED 0 in red.
2. Turn on LED 12 in blue.
3. Clear the matrix after two seconds.
4. Turn on all four corners with different colors.
5. Use set_xy() to light the center four LEDs.
6. Create a loop that moves one light from LED 0 to LED 15.
7. Use percentage colors to make dim red, dim green, and dim blue.

Common Mistakes

Hex colors must be written as strings:

CodyNick.RGB_Matrix.set(cn, 0, "#FF0000")

This is not correct:

CodyNick.RGB_Matrix.set(cn, 0, #FF0000)

Color percentages must use numbers from 0 to 100:

CodyNick.RGB_Matrix.set(cn, 0, [100, 50, 0])

Coordinates must be between 0 and 3:

CodyNick.RGB_Matrix.set_xy(cn, 3, 3, 7)

This is outside the matrix:

CodyNick.RGB_Matrix.set_xy(cn, 4, 0, 7)

If old LEDs stay on, clear the matrix before drawing the next pattern:

CodyNick.RGB_Matrix.clear(cn)