Skip to content

0.3.0

Latest

Choose a tag to compare

@lovyan03 lovyan03 released this 06 Nov 00:08
28d4794

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 after init() where it used to read 1, and every rotation value moves by one: the picture of the old setRotation(n) is now setRotation((n + 3) % 4) (the old setRotation(1) is setRotation(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, while setRotation(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() is board_unknown and getCandidateBoard() 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 after display() must call waitDisplay() 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 plain pushSprite() still completes at the outermost endWrite(), but code that keeps startWrite() held and redraws the same canvas right after pushing it must first wait on the destination: display.waitDMA(), not the sprite's waitDMA() (or use two canvases). The same applies before deleteSprite(), createSprite() or setColorDepth() 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 from init() / begin(); a derived class that called autodetect() from outside the initialization should call init() / begin() instead and read the result with getBoard() (autodetect() returned the board); inside an init_impl() override, call M5GFX::init_impl(use_reset, use_clear) (calling init() there would recurse into the override). (#379)
  • Object layouts changed (new members in M5GFX, the SPI bus and Panel_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 use esp_ptr_internal() instead, and call lgfx::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) and fixed_board (a fixed firmware identity starts that board directly, without probing other families or touching NVS); getCandidateBoard(), getFixedBoard(). Defined on every platform; on SDL fixed_board is used before M5GFX_BOARD. The settings and getters are documented in M5GFX.h. (#342, #345, #356, #361)
  • board_M5StamPLC: the product is named StamPLC, not StampPLC. board_M5StampPLC is kept as a deprecated alias with the same value (a board identity stored in NVS still resolves). The SDL window title becomes M5StamPLC. (#309, #359)
  • board_M5UnitPoEP4DisplayOut / M5UnitPoEP4DisplayOut / M5UnitPoEP4DisplayOut.h replace the ...HDMI names 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 as board_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_class in 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_M5StampP4 is 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_I2C open it themselves, as SPI already worked. After init() 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_CST9217 driver; 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 clipped pushSprite() of the same size returns after 3 ms instead of 26 ms. LGFX_SPI_SCT_DISABLE turns it off. ESP-IDF 6.1 moved the capability macro to hal/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): init issues 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 by writePixels() / 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/DisplayRotation examples. (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 .inl files 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 of use_dma is documented on Bus / Panel / LGFXBase::pushImage. (#360)

  • Comments added since 0.2.33 are in English, and the error_t descriptions are updated (mode_mismatch also covers a nested beginTransaction and 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 of M5GFX.cpp into 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.md documents the M5GFX_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.hpp become 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.md is removed. The board schema rejects a measured_by value that is a local document path (ending in .md or containing docs/). 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)

Deprecated

  • SpriteBuffer::use_dma(): DMA eligibility is decided by the destination bus. (#360)
  • board_M5UnitPoEP4HDMI → board_M5UnitPoEP4DisplayOut, M5UnitPoEP4HDMI → M5UnitPoEP4DisplayOut, M5UnitPoEP4HDMI.h → M5UnitPoEP4DisplayOut.h (#343)
  • board_M5StampPLC → board_M5StamPLC (#309, #359)