Repository navigation
Breaking changes
- Rotation 0 is the board's upright orientation on every board and external display. On Core BASIC / Fire / Gray, Core2, Tough, ToughC5, the CoreS3 family including StackChan, Station, Cardputer / Cardputer-Adv, StamPLC, CoreMatrix and the Module Display, Atom Display, Module RCA / Unit RCA, GLASS, GLASS2 and Mini OLED units the picture and the touch mapping at start-up do not change, but
getRotation()reads 0 afterinit()where it used to read 1, and every rotation value moves by one: the picture of the oldsetRotation(n)is nowsetRotation((n + 3) % 4)(the oldsetRotation(1)issetRotation(0); 4 to 7 move the same way within the mirrored set). Code that turns relative to the current value (setRotation(getRotation() + 1)) keeps working, whilesetRotation(getRotation() ^ 1)still toggles landscape / portrait but shows the portrait view turned 180° compared with 0.2.x; code that writes an absolute value must be rewritten, e.g.display.setRotation(1);→display.setRotation(0);. DinMeter now starts in landscape (240x135) instead of portrait (135x240), with the same shift for the values that select its pictures. (by @hlym123, #304; #306) - Board detection confirms a board only from positive evidence (an IC identity, its own touch controller, the pull state of an internal line). A result is confirmed, candidate or unknown:
getBoard()returns the adopted board,getCandidateBoard()the candidate. An unknown result no longer writes NVS (it used to write 0 and erase the stored hint). StampC6 / StampC5 (package facts only):init()returns false,getBoard()isboard_unknownandgetCandidateBoard()reports the Stamp board; an ESP32-P4 module without board evidence has an unknown candidate (M5Unified supplies the package default). Third-party PICO-D4 boards are no longer taken for AtomLite / AtomU by the touch ratio alone. The M5Unified side (cfg.fallback_board,BOARD_ID) needs M5Unified 0.3.0. (#311, #342, #345) Panel_ED2208::display()no longer blocks: the panel runs power-on, refresh, power-off and deep sleep on its own (AUTO) and the call returns after about 1 s instead of waiting for the whole refresh. Code that cuts the power right afterdisplay()must callwaitDisplay()first. (#336, #357)- Sprites in PSRAM on ESP32-S3 / C5 / C61 / P4 are pushed through DMA, so
pushSprite()of a PSRAM sprite is asynchronous like an internal RAM sprite. A plainpushSprite()still completes at the outermostendWrite(), but code that keepsstartWrite()held and redraws the same canvas right after pushing it must first wait on the destination:display.waitDMA(), not the sprite'swaitDMA()(or use two canvases). The same applies beforedeleteSprite(),createSprite()orsetColorDepth()on a sprite that was just pushed. With flash encryption enabled, C5 / C61 / P4 keep the CPU path. (#297) - The protected
M5GFX::autodetect()is removed. Detection starts frominit()/begin(); a derived class that calledautodetect()from outside the initialization should callinit()/begin()instead and read the result withgetBoard()(autodetect()returned the board); inside aninit_impl()override, callM5GFX::init_impl(use_reset, use_clear)(callinginit()there would recurse into the override). (#379) - Object layouts changed (new members in
M5GFX, the SPI bus andPanel_ED2208): rebuild the library and all code that uses its classes; mixing objects built against the previous release is unsupported. (#298, #336, #342, #345) lgfx::heap_capable_dma(ptr)(ESP32 family) also returns true for external RAM (PSRAM) on chips whose DMA can read it (ESP32-S3 / C5 / C61 / P4 with ESP-IDF 5.2 or later). A custom bus or panel that used it to tell internal RAM apart must useesp_ptr_internal()instead, and calllgfx::dma_cache_sync()before handing a PSRAM buffer to DMA. (#297)
New API
M5GFX::setDetectConfig(detect_config_t)/getDetectConfig():fallback_board(the caller's choice wins over a provisional member that differs from it) andfixed_board(a fixed firmware identity starts that board directly, without probing other families or touching NVS);getCandidateBoard(),getFixedBoard(). Defined on every platform; on SDLfixed_boardis used beforeM5GFX_BOARD. The settings and getters are documented inM5GFX.h. (#342, #345, #356, #361)board_M5StamPLC: the product is named StamPLC, not StampPLC.board_M5StampPLCis kept as a deprecated alias with the same value (a board identity stored in NVS still resolves). The SDL window title becomesM5StamPLC. (#309, #359)board_M5UnitPoEP4DisplayOut/M5UnitPoEP4DisplayOut/M5UnitPoEP4DisplayOut.hreplace the...HDMInames of the Unit PoE-P4 display output (value 201 unchanged); the old names stay as deprecated aliases and the old header includes the new one. (#343)board_M5StampP4XHub(value 157, also available asboard_M5StamP4XHub): a board ID for M5StampP4XHub. It is not detected yet. (#390, #392)
Board detection
- The hand-written autodetect chain is replaced by a board detection framework driven by per-board descriptions: signature / confirm (read-only) → prepare (typed power and reset operation lists) → display / touch construction. A family is identified by read-only probes before its power / reset sequence; a member whose touch controller only answers after that power-up (PaperMono) is confirmed after preparation, or kept provisionally on the final attempt. Detection runs inside a GPIO transaction, so a failed probe no longer leaves pins or I2C ports configured for another board; a held I2C bus (a slave holding SDA across a reset) is recovered first; pads left routed to LP I2C by a previous boot are returned to GPIO (ESP32-C5 / C6 / P4); PM1 and M5IOE1 operations retry transient NACKs; UnitC6L's reset pulse goes to the OLED reset pin (GPIO15) instead of its CS. (#311, #312)
- Family members are confirmed by their own devices (Core2 / Tough by their touch controllers, StopWatch / PaperMono by theirs, VAMeter by the INA226 ID, Cardputer-Adv by the TCA8418, Tab5 by the IO expander IDs with the panel chosen from the touch controller) instead of "not A, so B". A missed read costs a retry instead of selecting another board; on the final attempt a family with a silent member device keeps a display with a warning and stores nothing. Tab5 starts at least 80 ms sooner when the touch controller answers. (#312, #313)
- Boards without a display are identified in the detector: Atom Lite / Matrix / U / Echo, TimerCam, AtomS3Lite / AtomS3U, Capsule, PowerHub, DualKey, AtomS3R Cam (including the M12 variant) / Ext, AtomVoiceS3R, StampS3Bat, StampC3 / StampC3U, NanoC6 / StampC6, UnitC6L, NanoH2, StampC5 (confirmed where a device ID, USB SOF or a pin only one board drives exists; a candidate otherwise). AtomVoiceS3R, StampS3Bat, Capsule and UnitC6L need a device ID, not a bare ACK, and an AtomS3R whose LCD read failed once is no longer taken for an Ext or Cam. (#342)
- ESP32-P4: Unit PoE-P4 is confirmed by its Ethernet PHY ID over MDIO (independent of the display output board being attached), Tab5X is selected by chip revision (v3.0 or later; it used to be detected as Tab5 and saved as such), and a Tab5 candidate is kept when the IO expanders do not answer but the backlight enable line reads low. (#343, #344)
- StampS3 / Capsule: the RGB LED (WS2812 on GPIO21) stayed green after boot; the three-wire ID read left the MOSI output latch high. Capsule: the buzzer (GPIO2) clicked at boot; the AirQ candidate pulsed GPIO2 unconditionally. A per-GPIO
detect_classin the catalog is compared with the measured pull before any driven probe. (#337) - CoreS3 family: board detection enabled the backlight LDO at full brightness together with the other LDOs, so the screen flashed until the panel init turned it off. The LDO is left off until a brightness is set; four boards on one hub drew 0.4 to 0.5 A at startup instead of 0.8 A. (#335)
fixed_board = board_M5StampP4is accepted (displayless; StampP4 is still not detected automatically). (#363)- Board detection talks to devices only over software I2C and no longer opens the board's internal hardware I2C port at the end of preparation; the touch drivers, I2C backlights and
Bus_I2Copen it themselves, as SPI already worked. Afterinit()the port is open on boards with a touch controller or an I2C backlight (M5Unified opens it in any case). Tab5 reads the touch firmware version that selects its panel right after power-up instead of during display construction. (#367) - StopWatch: units with the CST9217 touch controller (I2C 0x5A, two touch points) are confirmed and use the new
lgfx::Touch_CST9217driver; units with the CST820 keep their driver and start about 13 ms later, the time the detection waits for that controller to answer. (by @Ocean-lhy, #391, #392)
Board specification catalog (extras/board_spec)
- A JSON catalog of M5Stack boards (chip, GPIO roles by owner, buses, devices, connectors, revisions, storage, buttons) with generators for the detector's wiring headers and the M5Unified pin tables, schema validation and tests, and a standalone editor / viewer (
dist/board_spec_editor.html). (#311, #323, #328) - Every user-exposed connector (headers, HAT buses, Grove ports, Proto pads, FPC / BTB) and links to the official product pages and schematics are cataloged from official sources, so a pin reachable through a connector cannot be used as detection evidence. The editor shows connector pinouts per page; the conventions, connector types, accessories and CLI are documented in the README. (#346, #347, #352)
- ToughC5: the M-Bus pin map. (#393)
SPI / DMA
- Segmented-Configure-Transfer on ESP32-S3 / C3 / C6 / C2 / H2: a DMA transfer over 32 KB is started once and the CPU is free until it completes, instead of restarting every 32 KB segment from the CPU.
pushImageDMA()of a 320x240 RGB565 image returns after 16 µs instead of 24 ms (transfer time unchanged); a clippedpushSprite()of the same size returns after 3 ms instead of 26 ms.LGFX_SPI_SCT_DISABLEturns it off. ESP-IDF 6.1 moved the capability macro tohal/spi_ll.h; it is found there too. (#298, #322) - Sprites in PSRAM go through DMA on ESP32-S3 / C5 / C61 / P4, using the external-RAM DMA path that
pushImageDMA()has had since 0.2.31. The CPU is free during the transfer instead of feeding the SPI FIFO 64 bytes at a time; a transfer from PSRAM takes about 0.9 ms longer per 25 KB for the cache write-back. (#297)
E-paper
- Panel_ED2208 (6-color E Ink):
display()sends and refreshes only the modified rectangle (partial window) instead of the whole panel. A refresh still takes about 15 s, but the rest of the screen keeps its image instead of flashing through the colors. (#378)
Fixes
- Panel_ED2208 (6-color E Ink): the controller was never reset, so a panel left in deep sleep by a previous program did not wake up (BUSY stayed low, every wait timed out,
init()took up to 40 s), and the 20 s refresh wait was shorter than a refresh, so power-off was sent mid-refresh.init()/wakeup()reset the controller (the image is kept), the refresh runs under AUTO,setSleep(true)uses the bus like the other commands, and the BUSY wait ends at the first high (display()1.12 s instead of 1.33 s). (#336, #357) - ESP targets without board detection (ESP32-S2) no longer run an unsuccessful detection that could write the unknown result back to NVS. (#356)
- ESP-IDF targets newer than the ESP32-C61 (ESP32-S31 / H21 in the ESP-IDF 6.1 preview) failed to build or fell through to the ESP32 code path. Chip-specific code is selected by what the target's headers provide; the existing targets keep their code paths. (#302)
- Panel_AMOLED: a horizontally clipped image drew nothing when the panel was driven without its frame buffer: the rows were queued without the pixel-write start, or each row restarted the write and rewound to the window start. The write is now started once for all rows (StopWatch draws through its frame buffer and was not affected in normal use). (#360)
- Software I2C (negative ports):
initissues nine STOP conditions on fixed 5 µs steps, so a device left mid transfer by earlier traffic on the same pins answers again. Skipped for a pin number the platform cannot drive. (#363) - Frame-buffer panels that send only the modified area (Panel_AMOLED / CO5300, Panel_ED2208) missed pixels drawn by
pushAlphaImage()/ anti-aliased drawing, and bywritePixels()/pushPixels()on a rotated screen: the alpha path did not record its area, and the rotated path recorded a shifted one. (#378) - SDL (PC) build: Paper / PaperS3 / PaperDIY, PaperMono and StamPLC opened a window whose size did not match the logical screen at rotation 0 (Paper: a 960 × 540 window for a 540 × 960 screen), so the picture was drawn sideways and clipped. The window now has the upright size. (#389)
- Tab5 / Tab5X / CoreP4X: the DSI panels allocated a second frame buffer that was never used. Only one is allocated now, which leaves 1.8 MB more PSRAM free on Tab5 and Tab5X, and 460 KB on CoreP4X. (#394)
Internal
-
Compiler warnings from the library sources and from the ESP-IDF headers it includes are cleared (they appeared in user builds); no change in behavior. (#325)
-
Board detection cleanups: unreachable panel-ID checks and an unused software-SPI switch removed, stale comments corrected; no detection result or timing changes. (#338)
-
Documentation: API reference and contributing guide under
docs/,Basic/DisplayRotationexamples. (by @hlym123, #304) -
CI: the ESP-IDF / arduino-esp32 versions are split with M5Unified so that together they cover every ESP-IDF minor from 5.1 to 6.1 and every arduino-esp32 series from 2.0 to 3.3; push builds also run when only
.inlfiles change. (#303, #327) -
pushSprite()lets the destination bus decide whether DMA can read the sprite buffer (no change in what is read by DMA on the ESP32 family). The meaning ofuse_dmais documented onBus/Panel/LGFXBase::pushImage. (#360) -
Comments added since 0.2.33 are in English, and the
error_tdescriptions are updated (mode_mismatchalso covers a nestedbeginTransactionand a call from a task that does not own the I2C transaction). Comments only. (#361) -
Board detection tests run on the host against the unchanged production sources (
test/board_detect/), and the detection tests that the board specification CI had skipped now run. The detection integration moved out ofM5GFX.cppinto internal includes (moves only; log lines show the new file names). (#363) -
Board catalog and detection maintenance: target metadata is derived from the catalog, generated detection headers name the boards and the reason for each order constraint, the detection decisions are explained where they are made, and a host test checks that each detector family only probes pins declared in its boards' catalog entries (it found undeclared Atom probe pins, now declared). No detection result or firmware code changes. (#364)
-
Board catalog: the resolved board/option combinations (
extras/board_spec/generated/resolved/) are no longer kept in the repository;node cli/spec.js resolve <file>prints them on demand. (#365) -
Board detection reaches GPIO, timing, I2C and chip registers through one inline layer (
src/board_detect/detect_io.hpp) instead of calling lgfx and ESP-IDF directly; the host tests supply their own implementation of it. No change in detection results or timing-sensitive code. (#367) -
Board detection: reserved operations and state that nothing used are removed, detection operations call the I/O layer directly, and fixed-board startup reuses the detection retry loop (five attempts, reset from the fourth, as before). The test-only setup failure injection takes a board list,
-DM5GFX_AUTODETECT_TEST_FAIL_SETUP_BOARDS=board_t::board_.... No detection result or timing changes. (#379) -
Board detection: names follow the detection phases (signature, confirm, prepare, construct, adopt), comments that described an older implementation are corrected, the ESP32-S3 board table has its own file,
extras/board_spec/README.mddocuments theM5GFX_AUTODETECT_TEST_*macros, and a host test checks the detector order for every board hint. Internal names only; no detection result changes. (#380) -
Board detection sources are merged into one detection file and one construction file per chip (87 files under
src/board_detect/become 54, per-chip subdirectories removed), and the generated<chip>_wiring.hpp/<chip>_specs.hppbecome one<chip>_board_data.hpp. Code is moved, not rewritten; no detection result changes. (#381) -
Comments, catalog notes and test documents describe the current behavior only (references to documents outside the repository, descriptions of earlier implementations and dates removed);
test/board_detect/MIGRATION.mdis removed. The board schema rejects ameasured_byvalue that is a local document path (ending in.mdor containingdocs/). Comments and catalog text only; no code change. (#385) -
Japanese comments added in recent changes are in English; three that did not match the code are corrected (the EPD blit return value, the placement of an I2C force-stop note, the EPD frame buffer cache note). Comments only. (#386)
-
Documentation:
pushSprite()says to wait on the destination (display.waitDMA()) before reusing or freeing the sprite; the rotation pages describe the rotation 0 convention as current behavior, the default table lists StamPLC, CoreMatrix and the Paper family, and the AtomDisplay / UnitGLASS / UnitRCA pages use the current rotation numbers. (#389)