Chain RGB

RGBChain 是 Chain 总线上 Chain RGB 显示设备的辅助类。它提供控制 8x8 RGB 显示屏的方法，使用 RGB888 整数颜色值，支持像素绘制、全屏缓冲区刷新、ASCII 字符显示、滚动文本、亮度和旋转。

支持以下产品：

Chain RGB

常量

显示模式使用 RGBChain.MODE_PIXEL 和 RGBChain.MODE_SCROLL。

滚动方向使用 RGBChain.SCROLL_DIR_LEFT、RGBChain.SCROLL_DIR_RIGHT、RGBChain.SCROLL_DIR_UP 和 RGBChain.SCROLL_DIR_DOWN。

滚动模式使用 RGBChain.SCROLL_MODE_ONCE、RGBChain.SCROLL_MODE_LOOP 和 RGBChain.SCROLL_MODE_BOUNCE。

滚动状态使用 RGBChain.SCROLL_STATE_START、RGBChain.SCROLL_STATE_PAUSE 和 RGBChain.SCROLL_STATE_RESET。

显示旋转使用 RGBChain.ROTATION_0、RGBChain.ROTATION_90、RGBChain.ROTATION_180 和 RGBChain.ROTATION_270。

UiFlow2 Example

滚动文本、旋转和亮度控制

Open the basic_chain_rgb_example.m5f2 project in UiFlow2.

This example initializes Chain RGB in scroll mode and displays the text M5STACK in cyan. It also shows a simple controller UI on the host display and uses the hardware buttons to control the Chain RGB module.

  • BtnA 在开始和暂停之间切换滚动状态。

  • BtnB 在 0、90、180、270 度之间循环切换显示旋转。

  • BtnC 循环切换显示亮度等级。

UiFlow2 代码块：

example.png

示例输出：

None

MicroPython 示例

滚动文本、旋转和亮度控制

该示例将 Chain RGB 初始化为滚动模式，并以青色显示文本 M5STACK，同时在主机屏幕上显示一个简单的控制界面，并使用硬件按键控制 Chain RGB 模块：

  • BtnA 在开始和暂停之间切换滚动状态。

  • BtnB 在 0、90、180、270 度之间循环切换显示旋转。

  • BtnC 循环切换显示亮度等级。

MicroPython 代码块：

  1# SPDX-FileCopyrightText: 2025 M5Stack Technology CO LTD
  2#
  3# SPDX-License-Identifier: MIT
  4
  5import os, sys, io
  6import M5
  7from M5 import *
  8from chain import ChainBus
  9from chain import RGBChain
 10
 11
 12label_title = None
 13label_text = None
 14label_state = None
 15label_rotation = None
 16label_direction = None
 17bus2 = None
 18chain_rgb_0 = None
 19scroll_state = None
 20display_rotation = None
 21brightness = None
 22
 23
 24def btna_was_clicked_event(state):
 25    global \
 26        label_title, \
 27        label_text, \
 28        label_state, \
 29        label_rotation, \
 30        label_direction, \
 31        bus2, \
 32        chain_rgb_0, \
 33        scroll_state, \
 34        display_rotation, \
 35        brightness
 36    scroll_state = (scroll_state if isinstance(scroll_state, (int, float)) else 0) + 1
 37    if scroll_state >= 2:
 38        scroll_state = 0
 39    chain_rgb_0.set_scroll_state(scroll_state)
 40
 41
 42def btnb_was_clicked_event(state):
 43    global \
 44        label_title, \
 45        label_text, \
 46        label_state, \
 47        label_rotation, \
 48        label_direction, \
 49        bus2, \
 50        chain_rgb_0, \
 51        scroll_state, \
 52        display_rotation, \
 53        brightness
 54    display_rotation = (display_rotation if isinstance(display_rotation, (int, float)) else 0) + 1
 55    if display_rotation >= 4:
 56        display_rotation = 0
 57    chain_rgb_0.set_display_rotation(display_rotation, save=False)
 58
 59
 60def btnc_was_clicked_event(state):
 61    global \
 62        label_title, \
 63        label_text, \
 64        label_state, \
 65        label_rotation, \
 66        label_direction, \
 67        bus2, \
 68        chain_rgb_0, \
 69        scroll_state, \
 70        display_rotation, \
 71        brightness
 72    brightness = (brightness if isinstance(brightness, (int, float)) else 0) + 10
 73    if brightness >= 50:
 74        brightness = 0
 75    chain_rgb_0.set_brightness(brightness, save=False)
 76
 77
 78def setup():
 79    global \
 80        label_title, \
 81        label_text, \
 82        label_state, \
 83        label_rotation, \
 84        label_direction, \
 85        bus2, \
 86        chain_rgb_0, \
 87        scroll_state, \
 88        display_rotation, \
 89        brightness
 90
 91    M5.begin()
 92    Widgets.setRotation(1)
 93    Widgets.fillScreen(0x000000)
 94    label_title = Widgets.Label(
 95        "Chain RGB Control", 45, 11, 1.0, 0x0F92E8, 0x000000, Widgets.FONTS.Montserrat24
 96    )
 97    label_text = Widgets.Label(
 98        "M5STACK", 62, 80, 1.0, 0x17E6CF, 0x000000, Widgets.FONTS.Montserrat40
 99    )
100    label_state = Widgets.Label(
101        "state", 40, 205, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.Montserrat18
102    )
103    label_rotation = Widgets.Label(
104        "brighness", 204, 205, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.Montserrat18
105    )
106    label_direction = Widgets.Label(
107        "rotation", 118, 205, 1.0, 0xFFFFFF, 0x000000, Widgets.FONTS.Montserrat18
108    )
109
110    BtnA.setCallback(type=BtnA.CB_TYPE.WAS_CLICKED, cb=btna_was_clicked_event)
111    BtnB.setCallback(type=BtnB.CB_TYPE.WAS_CLICKED, cb=btnb_was_clicked_event)
112    BtnC.setCallback(type=BtnC.CB_TYPE.WAS_CLICKED, cb=btnc_was_clicked_event)
113
114    bus2 = ChainBus(2, tx=21, rx=22)
115    chain_rgb_0 = RGBChain(bus2, 1)
116    chain_rgb_0.set_display_mode(RGBChain.MODE_SCROLL)
117    chain_rgb_0.set_scroll_text(
118        "M5STACK", RGBChain.SCROLL_DIR_LEFT, RGBChain.SCROLL_MODE_LOOP, 100, 0x17E6CF
119    )
120    scroll_state = 0
121    brightness = 20
122    display_rotation = 0
123    chain_rgb_0.set_display_rotation(display_rotation, save=False)
124    chain_rgb_0.set_brightness(brightness, save=False)
125
126
127def loop():
128    global \
129        label_title, \
130        label_text, \
131        label_state, \
132        label_rotation, \
133        label_direction, \
134        bus2, \
135        chain_rgb_0, \
136        scroll_state, \
137        display_rotation, \
138        brightness
139    M5.update()
140
141
142if __name__ == "__main__":
143    try:
144        setup()
145        while True:
146            loop()
147    except (Exception, KeyboardInterrupt) as e:
148        try:
149            bus2.deinit()
150            from utility import print_error_msg
151
152            print_error_msg(e)
153        except ImportError:
154            print("please update to latest firmware")

示例输出：

None

API

RGBChain

class chain.rgb.RGBChain(bus, device_id)

基类：KeyChain

用于通过 Chain 总线与 8x8 RGB 显示设备交互的 RGB Chain 类。

参数:

  • bus (ChainBus) – Chain 总线实例。

  • device_id (int) – Chain 总线上 RGB 显示设备的设备 ID。

UiFlow2 代码块：

init.png

MicroPython 代码块：

from chain import ChainBus
from chain import RGBChain

bus2 = ChainBus(2, tx=21, rx=22)
chain_rgb_0 = RGBChain(bus2, 1)

通用 Chain 设备方法请参考 ChainKey 类。

set_display_mode(mode=0)

设置显示模式。

参数:

mode (int) – 显示模式。使用 RGBChain.MODE_PIXEL (0) 表示像素模式，使用 RGBChain.MODE_SCROLL (1) 表示字符串滚动模式。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_display_mode.png

MicroPython 代码块：

success = chain_rgb_0.set_display_mode(RGBChain.MODE_PIXEL)
get_display_mode()

获取显示模式。

返回:

显示模式。0 表示像素模式，1 表示字符串滚动模式。失败时返回 None。

返回类型:

int

UiFlow2 代码块：

get_display_mode.png

MicroPython 代码块：

mode = chain_rgb_0.get_display_mode()
set_pixel(x, y, color=16777215)

设置 8x8 显示屏上单个像素的颜色。

参数:

  • x (int) – X 坐标，范围 0-7。

  • y (int) – Y 坐标，范围 0-7。

  • color (int) – 0xRRGGBB 格式的 RGB888 颜色值。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_pixel.png

MicroPython 代码块：

success = chain_rgb_0.set_pixel(0, 0, 0xFF0000)
set_pixels(coordinates=None)

设置 8x8 显示屏上多个像素的颜色。

参数:

coordinates – (x, y, color) 值的可迭代对象，支持 1-64 个像素。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_pixels.png

MicroPython 代码块：

success = chain_rgb_0.set_pixels(((0, 0, 0xFF0000), (1, 0, 0x00FF00)))
get_pixel(x, y)

从 8x8 显示屏读取单个像素的 RGB888 颜色。

参数:

  • x (int) – X 坐标，范围 0-7。

  • y (int) – Y 坐标，范围 0-7。

返回:

0xRRGGBB 格式的 RGB888 颜色值，失败时返回 None。

返回类型:

int

UiFlow2 代码块：

get_pixel.png

MicroPython 代码块：

color = chain_rgb_0.get_pixel(0, 0)
get_pixels(coordinates)

从 8x8 显示屏读取多个像素的 RGB888 颜色。

参数:

coordinates – (x, y) 坐标的可迭代对象，支持 1-64 个像素。

返回:

由 0xRRGGBB 格式 RGB888 颜色值组成的元组，失败时返回 None。

返回类型:

tuple

UiFlow2 代码块：

get_pixels.png

MicroPython 代码块：

colors = chain_rgb_0.get_pixels(((0, 0), (1, 0)))
set_display_buffer(buffer)

刷新完整的 8x8 显示缓冲区。

参数:

buffer – 64 个 0xRRGGBB 格式的 RGB888 颜色值，按行优先顺序从左到右、从上到下排列。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_display_buffer.png

MicroPython 代码块：

success = chain_rgb_0.set_display_buffer((0xFF0000,) * 64)
get_display_buffer()

获取完整的 64 色 RGB888 显示缓冲区。

返回:

由 64 个 0xRRGGBB 格式 RGB888 颜色值组成的元组，失败时返回 None。

返回类型:

tuple

UiFlow2 代码块：

get_display_buffer.png

MicroPython 代码块：

buffer = chain_rgb_0.get_display_buffer()
set_display_char(char, x_offset=0, y_offset=0, color=16777215)

在像素模式下设置单个 ASCII 字符。

参数:

  • char – 字符或 ASCII 编码，范围 32-127。

  • x_offset (int) – X 偏移，范围 0-7。

  • y_offset (int) – Y 偏移，范围 0-7。

  • color (int) – RGB888 color value in 0xRRGGBB format.

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_display_char.png

MicroPython 代码块：

success = chain_rgb_0.set_display_char("R", 1, 0, 0x00FF00)
set_scroll_text(text, direction=0, mode=1, speed=100, color=0)

设置滚动 ASCII 文本。

参数:

  • text – 要显示的 ASCII 字符串或字节，支持 ASCII 字符 32-127。

  • direction (int) – 滚动方向。使用 RGBChain.SCROLL_DIR_LEFT (0)、RGBChain.SCROLL_DIR_RIGHT (1)、RGBChain.SCROLL_DIR_UP (2) 或 RGBChain.SCROLL_DIR_DOWN (3)。

  • mode (int) – 滚动模式。使用 RGBChain.SCROLL_MODE_ONCE (0)、RGBChain.SCROLL_MODE_LOOP (1) 或 RGBChain.SCROLL_MODE_BOUNCE (3)。

  • speed (int) – 滚动速度，单位为毫秒/像素。范围：0-65535。

  • color (int) – 0xRRGGBB 格式的 RGB888 文本颜色。对于滚动文本，0x000000 表示启用渐变彩虹色。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_scroll_text.png

MicroPython 代码块：

success = chain_rgb_0.set_scroll_text("M5Stack", RGBChain.SCROLL_DIR_LEFT, RGBChain.SCROLL_MODE_LOOP, 100, 0x000000)
set_scroll_state(state=0)

设置滚动文本状态。

参数:

state (int) – 滚动状态。使用 RGBChain.SCROLL_STATE_START (0)、RGBChain.SCROLL_STATE_PAUSE (1) 或 RGBChain.SCROLL_STATE_RESET (2)。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_scroll_state.png

MicroPython 代码块：

success = chain_rgb_0.set_scroll_state(RGBChain.SCROLL_STATE_START)
get_scroll_state()

获取滚动文本状态。

返回:

滚动状态。0 表示滚动中，1 表示暂停，2 表示复位/空闲。失败时返回 None。

返回类型:

int

UiFlow2 代码块：

get_scroll_state.png

MicroPython 代码块：

state = chain_rgb_0.get_scroll_state()
set_display_rotation(rotation=0, save=False)

设置显示旋转。

参数:

  • rotation (int) – 显示旋转。0 为默认方向，1 为顺时针 90 度，2 为顺时针 180 度，3 为顺时针 270 度。

  • save (bool) – 是否将设置保存到 Flash。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_display_rotation.png

MicroPython 代码块：

success = chain_rgb_0.set_display_rotation(RGBChain.ROTATION_0, save=False)
get_display_rotation()

获取显示旋转。

返回:

显示旋转。0 为默认方向，1 为顺时针 90 度，2 为顺时针 180 度，3 为顺时针 270 度。失败时返回 None。

返回类型:

int

UiFlow2 代码块：

get_display_rotation.png

MicroPython 代码块：

rotation = chain_rgb_0.get_display_rotation()
set_brightness(brightness=50, save=False)

设置屏幕亮度百分比。

参数:

  • brightness (int) – 亮度百分比。范围：0-100。

  • save (bool) – 是否将设置保存到 Flash。

返回:

操作成功返回 True，否则返回 False。

返回类型:

bool

UiFlow2 代码块：

set_brightness.png

MicroPython 代码块：

success = chain_rgb_0.set_brightness(50, save=False)
get_brightness()

获取屏幕亮度百分比。

返回:

亮度百分比，范围 0-100。失败时返回 None。

返回类型:

int

UiFlow2 代码块：

get_brightness.png

MicroPython 代码块：

brightness = chain_rgb_0.get_brightness()