Port M5StickC Plus to M5Unified library stack with corrected Plus2 inheritance

doc/node_help/m5stickc_mic.rst

@@ -0,0 +1,86 @@
+m5stickc_mic
+============
+
+**Available on M5StickC Plus and M5StickC Plus2**
+
+..  code-block:: cpp
+
+    m5stickc_mic(name);
+
+**other names:** ``m5stickc_microphone``
+
+Captures audio from the built-in PDM microphone on M5StickC Plus and M5StickC
+Plus2 devices, and publishes raw 16-bit PCM audio buffers over MQTT.
+
+Parameters
+----------
+
+- ``name``: the name it can be addressed via MQTT in the network. Inside the code
+  it can be addressed via IN(name).
+
+MQTT Interface
+--------------
+
+The microphone device creates the following MQTT topics:
+
+- ``<node>/name/audio`` → Binary payload: raw 16-bit signed PCM samples at
+  16 kHz mono, 1024 samples (2048 bytes) per publish.
+
+The audio topic publishes binary data whenever a complete buffer of 1024 samples
+has been recorded. Only one buffer is queued at a time; if the previous buffer
+has not yet been published, the new recording is skipped to avoid back-pressure.
+
+Recording Details
+-----------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Parameter
+     - Value
+   * - Sample rate
+     - 16 000 Hz
+   * - Bit depth
+     - 16-bit signed integer (int16_t)
+   * - Channels
+     - Mono
+   * - Buffer size
+     - 1024 samples (64 ms audio)
+   * - Encoding
+     - Raw PCM (little-endian)
+
+Example
+-------
+
+**node name:** ``living_room/stick1``
+
+..  code-block:: cpp
+
+    m5stickc_mic(mic);
+
+Subscribe to the audio stream:
+
+..  code-block:: bash
+
+    mosquitto_sub -t "living_room/stick1/mic/audio" | \
+        aplay -f S16_LE -r 16000 -c 1
+
+Decode in Python using NumPy:
+
+..  code-block:: python
+
+    import numpy as np
+
+    def on_audio(client, userdata, msg):
+        samples = np.frombuffer(msg.payload, dtype=np.int16)
+        # samples is a 1-D array of 1024 int16 values at 16 kHz
+
+Notes
+-----
+
+- The microphone shares the I2S peripheral with the built-in speaker.
+  The device automatically disables the speaker (``StickCP2.Speaker.end()``) during
+  initialization so that the microphone can use I2S.
+- On M5StickC Plus, ``M5Unified`` is used; on M5StickC Plus2, ``M5StickCPlus2``
+  is used.  The device source is shared between the two boards via the
+  ``m5stickc_plus`` node-type inheritance.

doc/projects_help/m5stickc.rst

@@ -177,4 +177,146 @@ Resources
 ---------
 
 Product page:
-    https://shop.m5stack.com/products/stick-c?variant=43982750843137
+    https://shop.m5stack.com/products/stick-c?variant=43982750843137
+
+M5StickC Plus
+=============
+
+The M5StickC Plus is an upgraded version of the M5StickC with a larger display
+(135×240 vs 80×160) and a built-in microphone.  It uses the same ESP32-PICO-D4
+SoC and the same IoTempower development workflow.
+
+Board name: ``m5stickc_plus``
+
+The Plus board is powered by the modern `M5Unified
+<https://github.com/m5stack/M5Unified>`_ library which provides a unified API
+(``Display``, ``Imu``, ``Power``, ``Mic``) shared with the M5StickC Plus2.
+
+Available Devices
+-----------------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Device
+     - IoTempower name
+     - Description
+   * - LCD display (135×240)
+     - ``m5stickc_display``
+     - Writable text display
+   * - MPU6886 IMU
+     - ``m5stickc_imu``
+     - Gyroscope, accelerometer, yaw/pitch/roll
+   * - Built-in microphone
+     - ``m5stickc_mic``
+     - Raw PCM audio at 16 kHz
+   * - Power / sleep manager
+     - ``sleep_mgr``
+     - Deep-sleep and shutdown via MQTT
+
+Example
+-------
+
+Configure the ``node.conf`` file:
+
+..  code-block:: bash
+
+    board="m5stickc_plus"
+
+Configure the ``setup.cpp`` file:
+
+..  code-block:: cpp
+
+    const char* id = "01";
+
+    out(led, ONBOARDLED).inverted().off();
+
+    button(home, BUTTON_HOME, "pressed", "released").inverted().debounce(10);
+    button(side, BUTTON_RIGHT, "pressed", "released").inverted().debounce(10);
+
+    m5stickc_display(console, 2, 0);   // font size 2, landscape
+    m5stickc_imu(motion);              // gyro + accel + yaw/pitch/roll + temp
+    m5stickc_mic(mic);                 // built-in microphone
+
+    void start() {
+        do_later(100, []() {
+            IN(console).print("Plus-").print(id);
+        });
+    }
+
+Sending text and display commands:
+
+..  code-block:: bash
+
+    # Print a line
+    mqtt_send mynode/console "Hello World"
+
+    # Clear display and print at position 1,1
+    mqtt_send mynode/console "&&cl&&go 1 1&&Hello"
+
+    # Change text colour to red (foreground)
+    mqtt_send mynode/console "&&fg FF0000"
+
+Reading IMU data:
+
+..  code-block:: bash
+
+    mosquitto_sub -t "mynode/motion/#"
+    # publishes: mynode/motion/gyro, /acc, /ypr, /temp
+
+Microphone audio stream:
+
+..  code-block:: bash
+
+    mosquitto_sub -t "mynode/mic/audio" | \
+        aplay -f S16_LE -r 16000 -c 1
+
+Power management:
+
+..  code-block:: bash
+
+    # Deep-sleep for 30 seconds
+    mqtt_send mynode/sleep_mgr/set "sleep 30000"
+
+    # Power off immediately
+    mqtt_send mynode/sleep_mgr/set "shutdown"
+
+Physical Features
+-----------------
+
+.. table::
+   :widths: auto
+
+   +----------------------+--------------------------------------------------+
+   | Resources            | Parameter                                        |
+   +======================+==================================================+
+   | ESP32 PICO-D4        | 240 MHz dual core, 520 KB SRAM, Wi-Fi            |
+   +----------------------+--------------------------------------------------+
+   | Flash Memory         | 4 MB                                             |
+   +----------------------+--------------------------------------------------+
+   | Power Input          | 5V via USB-C                                     |
+   +----------------------+--------------------------------------------------+
+   | LCD screen           | 1.14 inch, 135×240 color TFT (ST7789V2)          |
+   +----------------------+--------------------------------------------------+
+   | Buttons              | Home (G37), Side (G39)                           |
+   +----------------------+--------------------------------------------------+
+   | LED                  | Red LED (G10)                                    |
+   +----------------------+--------------------------------------------------+
+   | IR                   | Infrared TX (G9)                                 |
+   +----------------------+--------------------------------------------------+
+   | IMU                  | MPU6886 (gyro + accel)                           |
+   +----------------------+--------------------------------------------------+
+   | Microphone           | SPM1423 (PDM)                                    |
+   +----------------------+--------------------------------------------------+
+   | PMU                  | AXP192                                           |
+   +----------------------+--------------------------------------------------+
+   | Battery              | 120 mAh @ 3.7V                                   |
+   +----------------------+--------------------------------------------------+
+   | Product Size         | 48.2×25.5×13.7 mm                                |
+   +----------------------+--------------------------------------------------+
+
+Resources
+---------
+
+Product page:
+    https://shop.m5stack.com/products/m5stickc-plus-esp32-pico-mini-iot-development-kit

lib/node_types/esp/platformio.ini

@@ -299,8 +299,8 @@ monitor_filters = esp32_exception_decoder
 framework = ${common.framework}
 monitor_speed = ${common.monitor_speed}
 lib_deps = ${common.base_lib_deps} ${common.extra_lib_deps} ${common.extra_lib_deps_esp32} 
-  m5stack/M5StickCPlus@^0.1.0
-# added library to support weird configured hardware -> TODO move to other dependencies?
+  m5stack/M5Unified@^2.1.1
+# M5Unified provides the modern all-in-one API (Display, Imu, Power, Mic) for M5StickC Plus
 upload_speed = 1500000
 extra_scripts = ${common.extra_scripts}
 lib_ldf_mode = ${common.lib_ldf_mode}

lib/node_types/m5stickc/src/platform_includes.h

@@ -4,7 +4,7 @@
 #ifdef ENV_M5STICKC
     #include <M5StickC.h>
 #elif ENV_M5STICKC_PLUS
-    #include <M5StickCPlus.h>
+    #include <M5Unified.h>
 #elif ENV_M5STICKC_PLUS2
     #include <M5StickCPlus2.h>
 #endif

lib/node_types/m5stickc_plus/base

@@ -1 +1 @@
-../m5stickc
+../m5stickc_plus2

lib/node_types/m5stickc_plus/src/platform_extras.h

@@ -0,0 +1,24 @@
+#ifndef _PLATFORM_EXTRAS_H_
+#define _PLATFORM_EXTRAS_H_
+
+#include <M5Unified.h>
+#include "toolbox.h"
+
+// M5StickC Plus compatibility layer:
+// Map the Plus2-style StickCP2 singleton to the M5Unified M5 object so that
+// device source files shared between Plus and Plus2 can use StickCP2.* uniformly.
+#define StickCP2 M5
+
+/**
+ * @brief M5StickC Plus specific early initialization
+ *
+ * CRITICAL: This function MUST be called at the very beginning of setup()
+ *           to ensure that the M5StickC Plus is properly powered on.
+ */
+inline void iotempower_platform_early_init() {
+    // Initialize M5 system first, to make sure power is held
+    auto cfg = M5.config();
+    M5.begin(cfg);
+}
+
+#endif // _PLATFORM_EXTRAS_H_

lib/node_types/m5stickc_plus2/src/dev_mic_m5stickc.h

@@ -1,5 +1,5 @@
 // dev_mic_m5stickc.h
-// Header file for controlling the m5stickc Plus2 Microphone
+// Header file for controlling the M5StickC Plus / Plus2 Microphone
 
 #ifndef _IOTEMPOWER_M5STICKC_MIC_H_
 #define _IOTEMPOWER_M5STICKC_MIC_H_

lib/node_types/m5stickc_plus2/src/dev_sleep_mgr.cpp

@@ -1,5 +1,5 @@
 // dev_sleep_mgr.cpp
-// Implementation of sleep management device for M5StickC Plus2
+// Implementation of sleep management device for M5StickC Plus / Plus2
 
 #include "dev_sleep_mgr.h"
 

lib/node_types/m5stickc_plus2/src/dev_sleep_mgr.h

@@ -1,5 +1,5 @@
 // dev_sleep_mgr.h
-// Header File for sleep management device for M5StickC Plus2
+// Header File for sleep management device for M5StickC Plus / Plus2
 
 #ifndef _SLEEP_MGR_H_
 #define _SLEEP_MGR_H_
@@ -8,11 +8,11 @@
 
 /**
  * @class SleepManager
- * @brief M5StickC Plus2 specific sleep management device for IoTempower
- * 
+ * @brief M5StickC Plus / Plus2 sleep management device for IoTempower
+ *
  * PURPOSE
  * =======
- * The SleepManager device provides centralized sleep management capabilities for M5StickC Plus2 nodes:
+ * The SleepManager device provides centralized sleep management capabilities for M5StickC Plus / Plus2 nodes:
  * - ESP32 deep sleep mode control
  * - M5StickC Plus2 specific power management via StickCP2.Power
  * - Scheduled power-down operations