Chain RGB

RGBChain is the helper class for Chain RGB display devices on the Chain bus. It provides methods to control an 8 x 8 RGB display using RGB888 integer color values, including pixel drawing, full-screen buffer refresh, ASCII character display, scrolling text, brightness, and rotation.

Support the following products:

Chain RGB

Constants

Display modes use RGBChain.MODE_PIXEL and RGBChain.MODE_SCROLL.

Scroll directions use RGBChain.SCROLL_DIR_LEFT, RGBChain.SCROLL_DIR_RIGHT, RGBChain.SCROLL_DIR_UP, and RGBChain.SCROLL_DIR_DOWN.

Scroll modes use RGBChain.SCROLL_MODE_ONCE, RGBChain.SCROLL_MODE_LOOP, and RGBChain.SCROLL_MODE_BOUNCE.

Scroll states use RGBChain.SCROLL_STATE_START, RGBChain.SCROLL_STATE_PAUSE, and RGBChain.SCROLL_STATE_RESET.

Display rotation uses RGBChain.ROTATION_0, RGBChain.ROTATION_90, RGBChain.ROTATION_180, and RGBChain.ROTATION_270.

UiFlow2 Example

Scroll text, rotation, and brightness control

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 toggles the scroll state between start and pause.

  • BtnB cycles the display rotation through 0, 90, 180, and 270 degrees.

  • BtnC cycles the display brightness level.

UiFlow2 Code Block:

example.png

Example output:

None

MicroPython Examples

Scroll text, rotation, and brightness control

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 toggles the scroll state between start and pause.

  • BtnB cycles the display rotation through 0, 90, 180, and 270 degrees.

  • BtnC cycles the display brightness level.

MicroPython Code Block:

  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")

Example output:

None

API

RGBChain

class chain.rgb.RGBChain(bus, device_id)

Bases: KeyChain

RGB Chain class for interacting with 8x8 RGB display devices over Chain bus.

Parameters:

  • bus (ChainBus) – The Chain bus instance.

  • device_id (int) – The device ID of the RGB display on the Chain bus.

UiFlow2 Code Block:

init.png

MicroPython Code Block:

from chain import ChainBus
from chain import RGBChain

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

For general Chain device methods, please refer to the ChainKey class.

set_display_mode(mode=0)

Set the display mode.

Parameters:

mode (int) – Display mode. Use RGBChain.MODE_PIXEL (0) for pixel mode or RGBChain.MODE_SCROLL (1) for scrolling string mode.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_display_mode.png

MicroPython Code Block:

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

Get the display mode.

Returns:

Display mode. 0 means pixel mode, 1 means scrolling string mode. Returns None if failed.

Return type:

int

UiFlow2 Code Block:

get_display_mode.png

MicroPython Code Block:

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

Set one pixel color on the 8x8 display.

Parameters:

  • x (int) – X coordinate, range 0-7.

  • y (int) – Y coordinate, range 0-7.

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

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_pixel.png

MicroPython Code Block:

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

Set multiple pixel colors on the 8x8 display.

Parameters:

coordinates – Iterable of (x, y, color) values. Supports 1-64 pixels.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_pixels.png

MicroPython Code Block:

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

Get one pixel RGB888 color from the 8x8 display.

Parameters:

  • x (int) – X coordinate, range 0-7.

  • y (int) – Y coordinate, range 0-7.

Returns:

RGB888 color value in 0xRRGGBB format, or None if failed.

Return type:

int

UiFlow2 Code Block:

get_pixel.png

MicroPython Code Block:

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

Get multiple pixel RGB888 colors from the 8x8 display.

Parameters:

coordinates – Iterable of (x, y) coordinates. Supports 1-64 pixels.

Returns:

Tuple of RGB888 color values in 0xRRGGBB format, or None if failed.

Return type:

tuple

UiFlow2 Code Block:

get_pixels.png

MicroPython Code Block:

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

Refresh the full 8x8 display buffer.

Parameters:

buffer – 64 RGB888 color values in 0xRRGGBB format, row-major order, left to right and top to bottom.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_display_buffer.png

MicroPython Code Block:

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

Get the full 64-color RGB888 display buffer.

Returns:

Tuple of 64 RGB888 color values in 0xRRGGBB format, or None if failed.

Return type:

tuple

UiFlow2 Code Block:

get_display_buffer.png

MicroPython Code Block:

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

Set one ASCII character in pixel mode.

Parameters:

  • char – Character or ASCII code in range 32-127.

  • x_offset (int) – X offset, range 0-7.

  • y_offset (int) – Y offset, range 0-7.

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

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_display_char.png

MicroPython Code Block:

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

Set the scrolling ASCII text.

Parameters:

  • text – ASCII string or bytes to display. Supports ASCII characters 32-127.

  • direction (int) – Scroll direction. Use RGBChain.SCROLL_DIR_LEFT (0), RGBChain.SCROLL_DIR_RIGHT (1), RGBChain.SCROLL_DIR_UP (2), or RGBChain.SCROLL_DIR_DOWN (3).

  • mode (int) – Scroll mode. Use RGBChain.SCROLL_MODE_ONCE (0), RGBChain.SCROLL_MODE_LOOP (1), or RGBChain.SCROLL_MODE_BOUNCE (3).

  • speed (int) – Scroll speed in milliseconds per pixel. Range: 0-65535.

  • color (int) – RGB888 text color in 0xRRGGBB format. 0x000000 enables gradient rainbow color for scroll text.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_scroll_text.png

MicroPython Code Block:

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

Set the scrolling text state.

Parameters:

state (int) – Scroll state. Use RGBChain.SCROLL_STATE_START (0), RGBChain.SCROLL_STATE_PAUSE (1), or RGBChain.SCROLL_STATE_RESET (2).

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_scroll_state.png

MicroPython Code Block:

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

Get the scrolling text state.

Returns:

Scroll state. 0 means scrolling, 1 means paused, 2 means reset/idle. Returns None if failed.

Return type:

int

UiFlow2 Code Block:

get_scroll_state.png

MicroPython Code Block:

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

Set the display rotation.

Parameters:

  • rotation (int) – Display rotation. 0 default, 1 clockwise 90 degrees, 2 clockwise 180 degrees, 3 clockwise 270 degrees.

  • save (bool) – Whether to save the setting to flash.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_display_rotation.png

MicroPython Code Block:

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

Get the display rotation.

Returns:

Display rotation. 0 default, 1 clockwise 90 degrees, 2 clockwise 180 degrees, 3 clockwise 270 degrees. Returns None if failed.

Return type:

int

UiFlow2 Code Block:

get_display_rotation.png

MicroPython Code Block:

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

Set the screen brightness percentage.

Parameters:

  • brightness (int) – Brightness percentage. Range: 0-100.

  • save (bool) – Whether to save the setting to flash.

Returns:

True if the operation was successful, False otherwise.

Return type:

bool

UiFlow2 Code Block:

set_brightness.png

MicroPython Code Block:

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

Get the screen brightness percentage.

Returns:

Brightness percentage, range 0-100. Returns None if failed.

Return type:

int

UiFlow2 Code Block:

get_brightness.png

MicroPython Code Block:

brightness = chain_rgb_0.get_brightness()