Port M5StickC Plus to M5Unified library stack with corrected Plus2 inheritance

[Copilot]

Feature Request

Description

Modernizes M5StickC Plus board support to use the M5Unified all-in-one library (same API surface as Plus2's StickCP2.*), restructures the inheritance chain so Plus inherits from Plus2, and places all shared device implementations in the Plus2 layer.

Motivation

M5StickC Plus was stuck on the legacy M5StickCPlus@^0.1.0 library with no microphone support, while Plus2 had a full modern device stack (display, IMU, mic, sleep_mgr) using StickCP2.*. The two boards share the same ESP32-PICO-D4 SoC, MPU6886 IMU, and PDM mic — there was no reason for duplicate implementations.

Changes Made

Inheritance chain

• m5stickc_plus/base symlink changed: ../m5stickc → ../m5stickc_plus2
• m5stickc_plus2/base symlink remains: ../m5stickc (unchanged from original)
• New chain: m5stickc_plus → m5stickc_plus2 → m5stickc → esp32
• Plus2 is the authoritative base; Plus inherits from it and overrides only board-specific files

M5StickC Plus2 — device source files (canonical location)

• dev_mic_m5stickc.{h,cpp} — PDM microphone, 16 kHz mono PCM, 1024-sample MQTT binary payloads
• dev_display_m5stickc.{h,cpp}, dev_imu_m5stickc.{h,cpp}, dev_sleep_mgr.{h,cpp} — full device stack using native StickCP2.* API

M5StickC Plus — board-specific overrides only

• platform_extras.h: includes M5Unified.h, defines #define StickCP2 M5 so all inherited device sources use StickCP2.* uniformly on both boards
• pins.h: Plus-specific pin assignments

How the compatibility layer works

// m5stickc_plus/src/platform_extras.h  (overrides Plus2's during Plus builds)
#include <M5Unified.h>
#define StickCP2 M5   // maps StickCP2.Display / .Imu / .Power / .Mic → M5.*

// m5stickc_plus2/src/platform_extras.h  (used as-is for Plus2 builds)
#include <M5StickCPlus2.h>
// StickCP2 is defined natively — no alias needed

Library & config

• esp/platformio.ini [env:m5stickc_plus]: m5stack/M5StickCPlus@^0.1.0 → m5stack/M5Unified@^2.1.1
• m5stickc/src/platform_includes.h: ENV_M5STICKC_PLUS branch updated to include M5Unified.h

Documentation

• doc/node_help/m5stickc_mic.rst: new device reference (MQTT topic, recording params, Python/shell examples)
• doc/projects_help/m5stickc.rst: new "M5StickC Plus" section with board name, device table, setup.cpp example, and hardware spec table

Testing

Verified via code review and static analysis (CodeQL — 0 alerts). Hardware build verification against physical M5StickC Plus / Plus2 boards is recommended before merge.

Additional Notes

M5Unified provides M5.Lcd as an alias for M5.Display, so the handful of M5.Lcd.* calls remaining in the display header continue to compile correctly on both boards without modification.

The inheritance direction (Plus2 as base for Plus) ensures that Plus2's build directory never includes Plus's platform_extras.h (which depends on M5Unified), preventing a build break for Plus2 which uses the M5StickCPlus2 library.

Original prompt

Port the M5StickC Plus board support in iotempire/iotempower to the newer unified M5StickC Plus2-style library stack, while preserving IoTempower’s inheritance-based node-type architecture and documentation conventions.

Repository: iotempire/iotempower
Base branch: master

Context and constraints

• IoTempower board types inherit through base symlinks. The user wants m5stickc_plus2 to inherit from m5stickc_plus, so move shared M5StickC Plus2-specific implementation down into lib/node_types/m5stickc_plus/ and make lib/node_types/m5stickc_plus2/base point to m5stickc_plus.
• Honor the IoTempower paradigm described in doc/architecture.rst: declarative device definitions, generated dependencies from devices.ini, and board-specific overrides in node type directories.
• The existing Plus2 implementation already has device support using the newer all-in-one M5Stack device library (M5StickCPlus2.h, StickCP2.*). The request is to modernize M5StickC Plus support to use the corresponding modern all-in-one library approach and support both Plus and Plus2 architectures cleanly.

Relevant current files / observations

• lib/node_types/m5stickc_plus2/src/dev_mic_m5stickc.cpp and .h contain microphone support that should be ported to m5stickc_plus.
• lib/node_types/m5stickc_plus2/src/dev_display_m5stickc.cpp/.h, dev_imu_m5stickc.cpp/.h, dev_sleep_mgr.cpp/.h, and platform_extras.h are Plus2-specific implementations using StickCP2 and the new-style all-in-one library.
• lib/node_types/m5stickc_plus/src/ currently appears minimal (e.g. only pins.h), so Plus2 currently overrides more behavior than Plus.
• lib/node_types/m5stickc_plus/src/pins.h differs from Plus2 pins: Plus uses ONBOARDLED 10, IR 9; Plus2 uses BUTTON_LEFT/BUTTON_POWER, ONBOARDLED 19, IR 19.
• Existing classic M5StickC implementations exist in lib/node_types/m5stickc/src/dev_display_m5stickc.* and dev_imu_m5stickc.* and currently use older APIs like M5.begin, M5.Lcd, M5.IMU.
• lib/node_types/esp/devices.ini already defines m5stickc_display, m5stickc_imu, m5stickc_mic, and sleep_mgr device entries; board-specific devices.ini likely controls imported libraries / overrides.
• doc/node_help/sleep_mgr.rst exists as a model for device docs; doc/projects_help/m5stickc.rst is a model for board/project docs.

Requested work

1. Rework board inheritance:

   • Change lib/node_types/m5stickc_plus2/base so Plus2 inherits from m5stickc_plus instead of inheriting directly from the older ancestor.
   • Ensure the resulting inheritance chain remains valid for IoTempower’s copy/override deployment process.

2. Move/port shared modern M5StickC support into lib/node_types/m5stickc_plus/:

   • Add microphone support there by moving/porting dev_mic_m5stickc.cpp and dev_mic_m5stickc.h from Plus2.
   • Port/move other Plus2-specific shared code that should now live at the Plus layer so that both Plus and Plus2 can use the modern M5Stack all-in-one device library approach where possible.
   • This likely includes display, IMU, sleep manager, and platform early-init support, but use best judgment based on what can truly be shared and what must remain overridden in Plus2.
   • Where hardware/API differences exist between Plus and Plus2, create a maintainable compatibility layer or conditional handling rather than duplicating large files unnecessarily.

3. Modernize m5stickc_plus board configuration:

   • Update lib/node_types/m5stickc_plus/src as needed to use the newer all-in-one device library approach similar to Plus2, but for the M5StickC Plus hardware.
   • Update lib/node_types/m5stickc_plus/platformio.ini and lib/node_types/m5stickc_plus/devices.ini to import/use the modern libraries corresponding to the new implementation.
   • Also update m5stickc_plus2 platform/config files as needed so they inherit shared configuration correctly and continue to build.

4. Keep Plus2 working:

   • After moving shared code to Plus, leave Plus2-specific overrides only where genuinely required (for pins or APIs unique to Plus2).
   • Ensure microphone, display, IMU, and sleep manager behavior still works for Plus2.

5. Documentation:

   • Create or update device documentation under doc/node_help/ for the microphone device (m5stickc_mic) following repository conventions.
   • Update any board/project help documentation needed to reflect M5StickC Plus support and the modernized device/library stack. If a board doc is appropriate, doc/projects_help/m5stickc.rst is a likely place or a new Plus-specific doc if that is more consistent.
   • Keep docs aligned with IoTempower’s declarative setup.cpp DSL style (device names unquoted, MQTT automatic, etc.).

Implementation guidance

• Prefer minimal, maintainable diffs that respect the inheritance/override model.
• Reuse existing IoTempower device naming and class names (M5StickC_Display, M5StickC_IMU, M5StickC_Mic, SleepManager) unless a ...

This pull request was created from Copilot chat.

[ulno]

@copilot there seems to be a small hickup in the inheritence induced by the base links. Maybe it would be easier to port bothj m5stivkc plus and plus2 to the unified library directly or at least fix the direction of links here.

[ulno]

Creating this file in m5stickc_plus and relinking the base from m5tickc_plus2 here will make this file show up in teh platformio-build directory for the m5stickc_plus2. This will break its built. So if we implement it like this m5stickc_plus2 would need to be the base for m5stickc_plus

[Copilot]

Fixed in commit Fix inheritance chain: Plus2 as base for Plus. The chain is now reversed as suggested:

• m5stickc_plus2/base → ../m5stickc (restored to original)
• m5stickc_plus/base → ../m5stickc_plus2 (new)

Full chain: m5stickc_plus → m5stickc_plus2 → m5stickc → esp32

All device source files (dev_display, dev_imu, dev_mic, dev_sleep_mgr) now live in m5stickc_plus2/src/ where they belong. m5stickc_plus/src/ contains only the board-specific overrides: pins.h and platform_extras.h (the M5Unified compatibility layer that maps StickCP2 → M5). Plus2's platform_extras.h will never see Plus's M5Unified header.

[Copilot]

@copilot there seems to be a small hickup in the inheritence induced by the base links. Maybe it would be easier to port bothj m5stivkc plus and plus2 to the unified library directly or at least fix t...

The inheritance direction is fixed. The new chain is m5stickc_plus → m5stickc_plus2 → m5stickc → esp32. Plus2 retains all device source files and its native M5StickCPlus2 platform setup; Plus inherits the device files from Plus2 and only overrides platform_extras.h with the M5Unified compatibility layer (#define StickCP2 M5). This keeps both boards on the unified device API without any file collision risk.