Library for RGB using M5UnitUnified.
M5UnitUnified is a library for unified handling of various M5 units products.
Unit RGB is an LED light unit. It integrates 3 programmable LED lights, allowing you to customize their color and brightness through programming. It supports daisy-chaining multiple Unit RGBs for expansion. You can use it in STEM classrooms to create interesting applications, such as traffic lights, or use it in other projects as status indicators.
Unit RGB LED is a programmable light strip that uses SK6812 LEDs. This light strip supports digital addressing, meaning you can individually control the color and brightness of each LED on the strip. It uses a single-bus programming interface, allowing for the expansion of the light strip. Note that as the number of connected LEDs increases, so does the power consumption. Therefore, when using a Unit RGB LED strip with a large number of LEDs, an additional power supply is required.
Unit HEX is a hexagonal RGB LED light board. It embeds a total of 37 RGB LED beads and provides input and output ports, which means you can connect multiple RGB LEDs in series.
Unit NeoHEX is a hexagonal RGB LED light panel embedded with 37 RGB LED full-color beads. It uses a single-bus control and supports cascading multiple light panels. It provides two sets of input interfaces with different socket angles, which can be used for independent power supply + signal control, ensuring sufficient power supply when cascading multiple light panels. The external structure comes with mounting ears for easy embedding and fixing. It comes with a milky white diffuser, making the lighting effect softer, suitable for various lighting DIY exhibits.
Unit RGB LED Strip is a programmable light strip that uses SK6812 LED beads. This strip supports digital addressing, meaning you can individually control the color and brightness of each LED on the strip. It uses a single-bus programming interface, allowing for strip expansion. The strip is processed with a waterproof epoxy coating, and the transparent protective silicone layer provides IP65 waterproof protection, making it suitable for various environments. The product uses flexible FPC (soft strip board) / PCB (hard strip board) as the base for soldering LEDs, with 5050 RGB LED beads. The back is equipped with 3M strong double-sided tape for easy installation. It operates at a 5V DC voltage, and various lighting effects can be achieved through controller programming.
Unit Neco is an RGB light board unit with a "cat ear design," featuring 35 WS2812C-2020 RGB LEDs. It comes with two 4-pin Grove ports for connecting to M5 hosts and expanding more units. Additionally, it includes a touch button for interacting with the host and switching between different lighting effects. It is suitable for home decoration, party atmospheres, stage performances, and more.
Unit Puzzle is a colorful light control unit composed of an 8x8 array of 64 WS2812E RGB LEDs. Each LED is separated by a grid structure to prevent interference between adjacent lights, ensuring clearer and purer light effects. The product features two Grove interfaces, one for input signal and the other for output, along with a connector for linking multiple Unit Puzzle units to expand the light display area. The output Grove interface also includes a reserved IO port, allowing connection to other M5 devices, such as the Unit Angle sensor with a Port B interface, enabling more interactive control functions. The Unit Puzzle is compact and easy to install, with an M2 hole at the bottom for secure mounting. The product measures only 24 x 24 x 15mm. It is suitable for applications such as smart lighting, decorative displays, and interactive installations.
Hat NeoFlash is a matrix RGB LED panel specifically designed for StickC. This PCB board, with a size of only 58x23.5mm, embeds a total of 126 programmable RGB LEDs (WS2812), allowing users to freely set its color and brightness. Besides achieving cool colorful lighting effects, its 7x18 matrix design provides a good digital display experience.
ATOM Matrix has a built-in 5x5 RGB LED matrix on the panel. This library can manage the LED matrix.
Warning: Do not set brightness too high. Excessive brightness can generate high temperatures and damage the LEDs and acrylic panel. Recommended brightness is 20 or less.
Note (large cascades / PbHub): Two hardware limits apply to the cascaded examples (
DaisyChain,ViaPbHub):
- PbHub caps each channel at 74 LEDs. LEDs past the 74th on any channel receive no data — e.g. running two Unit Puzzles (64 + 64) on a single PbHub channel leaves 54 LEDs in the second puzzle unlit.
- USB-powered boards (NanoC6 / NanoH2, ~500 mA) cannot supply enough current for the full example configurations; the 5V rail sags and downstream LEDs dim or go dark. Reduce total LED count, lower brightness, or use an external 5V power source.
Note (StickS3 + HatNeoFlash boot): StickS3's Hat header uses GPIO 0 (ESP32-S3 boot-mode strap). HatNeoFlash's WS2812 DIN pulls GPIO 0 low at reset, forcing DOWNLOAD MODE (silent boot). Detach the Hat before flashing, then re-attach after the firmware starts.
UnitNeco button (direct GPIO connection)
- Button read requires an input GPIO with internal pull-up on the host's Grove port. Some boards route
port_b_into an input-only pin lacking pull-up (e.g. M5Stack Core = GPIO 36), on which the button is disabled at runtime (logged asRX GPIO NN is not usable for button; button disabled) — the LEDs still work. - To use the button on such boards, connect Neco to another port whose input pin has internal pull-up (e.g. Port A or Port C on boards that expose them) and add manually via
Units.add(unit, rx, tx)with the chosen pins instead ofwiring::addGPIO.
- Unit RGB - Document & Datasheet
- Unit RGB LED - Document & Datasheet
- Unit Hex - Document & Datasheet
- Unit NeoHex - Document & Datasheet
- Unit RGB LED Strip - Document & Datasheet
- Unit Neco - Document & Datasheet
- Unit Puzzle - Document & Datasheet
- Hat NeoFlash - Document & Datasheet
- M5AtomMatrix - Document & Datasheet
See also examples/UnitUnified
You must choose a define symbol for the unit you will use. (Rewrite source or specify with compile options)
- Simple
// *************************************************************
// Choose one define symbol to match the unit you are using
// *************************************************************
#if !defined(USING_UNIT_RGB) && !defined(USING_UNIT_PUZZLE) && !defined(USING_UNIT_HEX) && \
!defined(USING_UNIT_NEO_HEX) && !defined(USING_UNIT_NECO) && !defined(USING_UNIT_RGBLED15) && \
!defined(USING_UNIT_RGBLED_STRIP30) && !defined(USING_ATOM_MATRIX_RGB) && !defined(USING_HAT_NEOFLASH)
// For Unit RGB (U003)
// #define USING_UNIT_RGB
// For Unit Puzzle (U193)
// #define USING_UNIT_PUZZLE
// For Unit Hex (A045)
// #define USING_UNIT_HEX
// For Unit NeoHex (A045-B)
// #define USING_UNIT_NEO_HEX
// For Unit Neco (U163)
// #define USING_UNIT_NECO
// For Unit RGB LED (A035)
// #define USING_UNIT_RGBLED15
// For Unit RGB LED Strip (A093)
// #define USING_UNIT_RGBLED_STRIP30
// For ATOM Matrix built-in 5x5 RGB LED (C008-B)
// #define USING_ATOM_MATRIX_RGB
// For Hat NeoFlash (U071)
// #define USING_HAT_NEOFLASH
#endifNOTE: The ESP-IDF native build (
idf.py) targets ESP-IDF 5.1 or later (5.x and 6.x).
Direct GPIO drive needs RMT, so ESP32-C2 / ESP32-C61 (no RMT) are not supported targets.
On ESP-IDF native builds (idf.py), the unit/board of the Simple example is selected via Kconfig instead of editing the source #define. main/Kconfig.projbuild sources examples/UnitUnified/common/Kconfig.variant, and examples/UnitUnified/common/variant.cmake maps the chosen CONFIG_EXAMPLE_USING_* to the source-level USING_* macro shared with the Arduino build.
Pick the unit with menuconfig:
cd examples/UnitUnified/Simple
idf.py set-target esp32s3 # or esp32 / esp32c3 / esp32c6 / esp32h2 / esp32p4
idf.py menuconfig
# -> M5Unit-RGB example -> Target unit / board -> choose ONE of the options offered
idf.py build flash monitorDaisyChain, MultiChannel and ViaPbHub fix their units in the source, so there is no unit to choose: build the example directory directly.
Support via PbHub
| Unit | Support | Note |
|---|---|---|
| UnitRGB | OK | |
| UnitRGBLED | OK | |
| UnitHex | OK | |
| UnitNeoHex | OK | |
| UnitRGBLEDStrip | OK | |
| UnitNeco | OK | LED only, Button function NG |
| UnitPuzzle | OK |
See also M5Unit-HUB
- Each channel can control up to MAX 74 LEDs each
- Button status of UnitNeco cannot be retrieved
If you want to generate documents on your local machine, execute the following command
bash docs/doxy.sh
It will output it under docs/html
If you want to output Git commit hashes to html, do it for the git cloned folder.