NovaMP 文档

Appearance

RGBMatrix 模块 ​

模块介绍 ​

用于控制 8x8 LED 矩阵屏幕（WS2812B/NeoPixel）的驱动类。支持像素级颜色控制、屏幕旋转、位图渲染等功能。

硬件引脚说明 ​

引脚名称全称/含义接线颜色功能描述
DI/DINData In/数据输入黄色/绿色数据传输引脚，用于向 LED 矩阵发送颜色数据
VCC/5VVoltage/电源红色电源电压输入（通常为 5V），为 LED 矩阵提供工作电压
GNDGround/地线黑色接地引脚，完成电路回路

初始化参数 ​

参数类型默认值说明
pinPin无machine.Pin实例
rotationint0屏幕旋转角度，支持 0, 90, 180, 270

导入和实例创建 ​

python
from machine import Pin  # 导入Pin模块
from rgb_matrix import RGBMatrix  # 导入RGBMatrix驱动模块

# 初始化 8x8 LED 矩阵，连接到 GPIO5
screen = RGBMatrix(Pin(5), rotation=0)  # 创建RGBMatrix实例，传入Pin对象

核心属性方法 ​

属性或方法参数返回类型说明
brightness-float属性：获取或设置当前亮度（0.0 ~ 1.0）
fill()color (tuple)None填充整个屏幕为单一颜色
set_color()position (list/tuple), color (tuple), immediate=True (bool)None设置指定位置的颜色
get_color()position (list/tuple)tuple获取指定位置的颜色
[x, y]-tuple/None魔法方法：获取或设置颜色，如 screen[2, 3] = RED
[x][y]-tuple/None魔法方法：二维索引方式，如 screen[2][3] = RED
set_direction()direction (int)None设置屏幕旋转方向（0, 90, 180, 270）
set_bitmap()bitmap (list)None设置整个屏幕的位图（8x8 颜色矩阵）
set_brightness()value (float)None设置屏幕亮度（0.0 ~ 1.0）
clear()无None清空屏幕（填充黑色）
write()无None将颜色数据写入硬件（根据亮度调整）
deinit()无None释放资源：关闭 NeoPixel 并清空屏幕

使用示例 ​

python
from machine import Pin
from rgb_matrix import RGBMatrix
from colors import RED, GREEN, BLUE, YELLOW, ORANGE, generate_gradient_colors

# 初始化 8x8 LED 矩阵，连接到 GPIO4
screen = RGBMatrix(Pin(4), rotation=0)

# 基本控制
screen.fill(RED)                    # 填充红色
screen.clear()                      # 清空屏幕

# 像素级控制（三种方式）
screen.set_color([3, 3], GREEN)     # 方式1：使用方法
screen[2, 2] = BLUE                 # 方式2：元组索引
screen[1][1] = YELLOW               # 方式3：二维索引

# 获取颜色
color = screen.get_color([3, 3])    # 方式1：使用方法
color = screen[2, 2]                # 方式2：元组索引
color = screen[1][1]                # 方式3：二维索引

# 亮度控制
screen.brightness = 0.5             # 设置亮度为 50%
screen.set_brightness(0.8)          # 设置亮度为 80%
current = screen.brightness         # 获取当前亮度

# 旋转屏幕
screen.set_direction(90)            # 顺时针旋转 90°

# 位图渲染 - 绘制皇冠图案
crown_bitmap = [
    [BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE],
    [BLUE, YELLOW, BLUE, YELLOW, YELLOW, BLUE, YELLOW, BLUE],
    [BLUE, YELLOW, BLUE, YELLOW, YELLOW, BLUE, YELLOW, BLUE],
    [BLUE, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, BLUE],
    [BLUE, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, BLUE],
    [BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE],
    [BLUE, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, YELLOW, BLUE],
    [BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE, BLUE],
]
screen.set_bitmap(crown_bitmap)

# 渐变色扫描动画
screen.clear()
colors_gradient = generate_gradient_colors(BLUE, ORANGE, 64)
index = 0
for y in range(8):
    for x in range(8):
        screen[x, y] = colors_gradient[index]
        index += 1

# 批量像素更新（性能优化）
for i in range(8):
    screen.set_color([i, i], RED, immediate=False)  # 不立即写入
screen.write()  # 统一写入硬件

# 释放资源
screen.deinit()

注意事项 ​

引脚与电源要求

  • 确保所用引脚支持数字输出（ESP32/ESP8266 的多数 GPIO 均支持）
  • 8x8 LED 矩阵在全亮白色时功耗较大（约 3A @ 5V），建议使用外部电源供电

参数范围

  • 像素坐标 (x, y) 必须在 0~7 范围内，超出范围会抛出 ValueError
  • 旋转角度仅支持 0, 90, 180, 270 度，其他角度会抛出 ValueError
  • brightness 有效范围为 0.0~1.0，超出范围会抛出 ValueError

使用技巧

  • 修改亮度会自动重新渲染整个屏幕，调整后的颜色会立即生效
  • 批量更新像素时，先设置所有颜色（immediate=False），最后调用 write() 一次性写入可提升性能
  • 支持三种访问方式：screen.set_color([x, y], color) / screen[x, y] = color / screen[x][y] = color
  • 在 while True 循环中请配合延时函数使用，防止程序过载

技术细节

  • set_bitmap() 要求 8x8 矩阵，每个颜色为 (R, G, B) 格式，RGB 分量为 0~255 整数
  • set_color() 的 immediate 参数控制是否立即写入硬件，False 适合批量操作
  • 使用完毕后调用 deinit() 释放资源并清空屏幕