1. Overview
The MAX7219 is a serial LED driver IC that controls up to 64 LEDs (an 8×8 matrix) over a simple 3-wire SPI-style bus, handling all the multiplexing and current limiting on-chip. It's the same driver used in the classic "FC-16" dot-matrix modules and can be daisy-chained to build longer scrolling displays.
2. Pinout
Verified against simulator/components/max7219 dot matrix.ts (5-pin header):
3. Key Specifications
| Spec | Value |
|---|
| Driver IC | MAX7219 |
| Matrix size | 8×8 LEDs (single color) per module |
| Interface | SPI-style, 3-wire (DIN/CS/CLK) |
| Brightness | 16 steps (0–15), set in software |
| Daisy-chain | Yes, on real hardware (OMS models one module) |
4. Libraries Used
- C++ (Arduino):
LedControl — the standard library for MAX7219/MAX7221 LED matrix and 7-segment modules.
- MicroPython: a community
max7219 module exposing a Matrix8x8 class over machine.SPI.
5. Component Properties
From the real props: [...]:
ledColor (color) — Color of the lit LEDs on the simulated canvas. Default: #ff1e1e (red, matching real single-color modules).
preset (select) — Heart (default), Smiley, Invader, Arrow, Checker, All ON, Clear, or Custom (set automatically when you click individual LEDs).
Powered state comes from VCC: above 3.5V the matrix lights; below 4.5V while powered, a LOW VCC fault is raised.
6. Simulator Behavior
Click any of the 64 LEDs directly on the canvas to toggle it (this switches preset to Custom and writes the pattern into customBuffer). A toolbar visible during simulation offers the 7 built-in presets as one-click buttons.
[!IMPORTANT]
Fidelity depends on which board/language you're running — and this session fixed a real bug in it. OMS has two different simulation tiers:
- AVR (C++, e.g. Uno/Nano/Mega) and RP2040 (C++, e.g. Pico) run on real cycle-accurate chip emulators that can watch the actual SPI bus. A hook for this already existed for MAX7219, but a dispatch bug meant it silently never fired for the real
max7219_matrix component (it checked for a component id, max7219, that no longer matched after this display's real circuit component was added — and it looked for a CS pin in the wrong place). Fixed 2026-08-25 (see Known_Bugs.md): on these boards, the matrix you see now genuinely reflects your compiled program's real LedControl SPI writes, the same fidelity tier as the OLED (10.6).
- MicroPython on any board runs through a separate WASM-based Python VM. That path has the supporting message-passing code already built (
SPI_REGISTER, a max7219FrameCallback) but nothing in the simulator core ever calls it — there is currently no real bus capture for MicroPython, on any board. On that path, the matrix always shows the preset/customBuffer prop only, not your actual code's output. This is logged as an open gap in Known_Bugs.md, not something fixed this session.
7. Supported Blockly Blocks (6 Blocks)