Add test support and disable analog audio bypass

Author: renletao

README.md

@@ -26,6 +26,45 @@ M5.begin();
 audio.begin(Wire);
 ```
 
+## Microphone routing
+
+The LINE/MIC jack and the headset microphone share the ES8388 `LIN1` input. Keep the two STM32-controlled paths
+mutually exclusive.
+
+Use the LINE/MIC jack:
+
+```cpp
+audio.setHPMICStatus(AUDIO_MIC_CLOSE);
+audio.setMICStatus(AUDIO_MIC_OPEN);
+audio.setMicInputLine(ADC_INPUT_LINPUT1_RINPUT1);
+```
+
+Use the microphone in a connected headset:
+
+```cpp
+if (audio.getHPInsertStatus()) {
+    audio.setMICStatus(AUDIO_MIC_CLOSE);
+    audio.setHPMICStatus(AUDIO_MIC_OPEN);
+    audio.setMicInputLine(ADC_INPUT_LINPUT1_RINPUT1);
+}
+```
+
+Register `0x11` is reset to `AUDIO_MIC_CLOSE` at power-up. Headset insertion or removal does not change it.
+
+## Device UID
+
+Firmware `0xF1` exposes the STM32 96-bit UID in registers `0xE0` through `0xEB`:
+
+```cpp
+uint8_t uid[DEVICE_UID_LENGTH];
+if (audio.getDeviceUID(uid)) {
+    for (uint8_t value : uid) {
+        Serial.printf("%02X", value);
+    }
+    Serial.println();
+}
+```
+
 ## Related Link
 
 - [Document & Datasheet](https://docs.m5stack.com/en/module/Module-Audio)

src/M5Module_Audio.cpp

@@ -216,6 +216,12 @@ void M5ModuleAudio::setHPMode(audio_hpmode_t mode)
     writeBytes(_addr, reg, (uint8_t *)&mode, 1);
 }
 
+void M5ModuleAudio::setHPMICStatus(audio_mic_t status)
+{
+    uint8_t reg = HEADPHONE_MIC_STATUS;
+    writeBytes(_addr, reg, (uint8_t *)&status, 1);
+}
+
 void M5ModuleAudio::setRGBBrightness(uint8_t brightness)
 {
     if (brightness > 100) brightness = 100;
@@ -226,14 +232,35 @@ void M5ModuleAudio::setRGBBrightness(uint8_t brightness)
 void M5ModuleAudio::setRGBLED(uint8_t num, uint32_t color)
 {
     if (num > 2) num = 2;
-    color       = ((color & 0xFF) << 16) | (color & 0xFF00) | ((color >> 16) & 0xFF);
-    uint8_t reg = RGB_LED + num * 3;
-    writeBytes(_addr, reg, (uint8_t *)&color, 3);
+    uint8_t rgb[3] = {
+        static_cast<uint8_t>((color >> 16) & 0xFF),
+        static_cast<uint8_t>((color >> 8) & 0xFF),
+        static_cast<uint8_t>(color & 0xFF),
+    };
+    uint8_t reg = RGB_LED + num * sizeof(rgb);
+    writeBytes(_addr, reg, rgb, sizeof(rgb));
+}
+
+void M5ModuleAudio::setAllRGBLED(uint32_t color)
+{
+    const uint8_t red   = static_cast<uint8_t>((color >> 16) & 0xFF);
+    const uint8_t green = static_cast<uint8_t>((color >> 8) & 0xFF);
+    const uint8_t blue  = static_cast<uint8_t>(color & 0xFF);
+    uint8_t rgb[9];
+    for (size_t index = 0; index < sizeof(rgb); index += 3) {
+        rgb[index]     = red;
+        rgb[index + 1] = green;
+        rgb[index + 2] = blue;
+    }
+    writeBytes(_addr, RGB_LED, rgb, sizeof(rgb));
 }
 
 uint8_t M5ModuleAudio::setI2CAddress(uint8_t newAddr)
 {
-    newAddr     = constrain(newAddr, I2C_ADDR_MIN, I2C_ADDR_MAX);
+    if (newAddr < I2C_ADDR_MIN || newAddr > I2C_ADDR_MAX || newAddr == ES8388_ADDR) {
+        return _addr;
+    }
+
     uint8_t reg = I2C_ADDRESS;
     writeBytes(_addr, reg, (uint8_t *)&newAddr, 1);
     _addr = newAddr;
@@ -265,6 +292,14 @@ audio_hpmode_t M5ModuleAudio::getHPMode()
     return (audio_hpmode_t)data;
 }
 
+audio_mic_t M5ModuleAudio::getHPMICStatus()
+{
+    uint8_t data;
+    uint8_t reg = HEADPHONE_MIC_STATUS;
+    readBytes(_addr, reg, (uint8_t *)&data, 1);
+    return (audio_mic_t)data;
+}
+
 uint8_t M5ModuleAudio::getHPInsertStatus()
 {
     uint8_t data;
@@ -289,6 +324,26 @@ uint32_t M5ModuleAudio::getRGBLED(uint8_t num)
     return (rgb[0] << 16) | (rgb[1] << 8) | rgb[2];
 }
 
+bool M5ModuleAudio::getRGBLEDs(uint32_t colors[3])
+{
+    if (colors == nullptr) {
+        return false;
+    }
+
+    uint8_t rgb[9] = {};
+    if (!readBytes(_addr, RGB_LED, rgb, sizeof(rgb))) {
+        colors[0] = colors[1] = colors[2] = 0;
+        return false;
+    }
+
+    for (size_t index = 0; index < 3; ++index) {
+        const size_t offset = index * 3;
+        colors[index] = (static_cast<uint32_t>(rgb[offset]) << 16) | (static_cast<uint32_t>(rgb[offset + 1]) << 8) |
+                        static_cast<uint32_t>(rgb[offset + 2]);
+    }
+    return true;
+}
+
 uint8_t M5ModuleAudio::getFirmwareVersion()
 {
     uint8_t version;
@@ -305,6 +360,14 @@ uint8_t M5ModuleAudio::getI2CAddress()
     return I2CAddress;
 }
 
+bool M5ModuleAudio::getDeviceUID(uint8_t uid[DEVICE_UID_LENGTH])
+{
+    if (uid == nullptr) {
+        return false;
+    }
+    return readBytes(_addr, DEVICE_UID, uid, DEVICE_UID_LENGTH);
+}
+
 bool M5ModuleAudio::es8388_codec_init()
 {
     if (es8388 != nullptr) {
@@ -511,6 +574,20 @@ bool M5ModuleAudio::setMixSourceSelect(es_mixsel_t lmixsel, es_mixsel_t rmixsel)
     return true;
 }
 
+bool M5ModuleAudio::setLineBypass(bool enabled)
+{
+    if (es8388 == nullptr) {
+        ESP_LOGI(TAG, "ES8388 codec is not initialized");
+        return false;
+    }
+
+    if (!es8388->setLineBypass(enabled)) {
+        ESP_LOGI(TAG, "Failed to configure ES8388 line bypass");
+        return false;
+    }
+    return true;
+}
+
 bool M5ModuleAudio::setBitsSample(es_module_t mode, es_bits_length_t bits_len)
 {
     if (es8388 == nullptr) {
@@ -726,13 +803,13 @@ bool M5ModuleAudio::play(const uint8_t *buffer, int size)
     size_t bytes_written = 0;
 #if USE_NEW_I2S_API
     bytes_written = I2S.write(buffer, size);
-    if (bytes_written < 0) {
+    if (bytes_written != static_cast<size_t>(size)) {
         ESP_LOGI(TAG, "Playback failed");
         return false;
     }
 #else
     esp_err_t err = i2s_write(i2s_num, buffer, size, &bytes_written, portMAX_DELAY);
-    if (err != ESP_OK) {
+    if (err != ESP_OK || bytes_written != static_cast<size_t>(size)) {
         ESP_LOGI(TAG, "Playback failed");
         return false;
     }
@@ -774,25 +851,32 @@ void M5ModuleAudio::writeBytes(uint8_t addr, uint8_t reg, uint8_t *buffer, uint8
 #endif
 }
 
-void M5ModuleAudio::readBytes(uint8_t addr, uint8_t reg, uint8_t *buffer, uint8_t length)
+bool M5ModuleAudio::readBytes(uint8_t addr, uint8_t reg, uint8_t *buffer, uint8_t length)
 {
+    if (buffer == nullptr || length == 0) {
+        return false;
+    }
+
     if (_m5_i2c != nullptr) {
         if (!_m5_i2c->readRegister(addr, reg, buffer, length, _i2c_speed)) {
             memset(buffer, 0, length);
+            return false;
         }
-        return;
+        return true;
     }
 
     if (_wire == nullptr) {
         memset(buffer, 0, length);
-        return;
+        return false;
     }
 
     uint8_t index = 0;
     _wire->beginTransmission(addr);
     _wire->write(reg);
-    _wire->endTransmission(false);
-    _wire->requestFrom(addr, length);
+    if (_wire->endTransmission(false) != 0 || _wire->requestFrom(addr, length) != length) {
+        memset(buffer, 0, length);
+        return false;
+    }
     for (int i = 0; i < length; i++) {
         buffer[index++] = _wire->read();
     }
@@ -811,4 +895,5 @@ void M5ModuleAudio::readBytes(uint8_t addr, uint8_t reg, uint8_t *buffer, uint8_
     Serial.println("]");
 #else
 #endif
+    return true;
 }

src/M5Module_Audio.h

@@ -39,9 +39,12 @@
 #define I2C_ADDR_MAX            (0x77)
 #define MICROPHONE_STATUS       (0x00)
 #define HEADPHONE_MODE          (0x10)
+#define HEADPHONE_MIC_STATUS    (0x11)
 #define HEADPHONE_INSERT_STATUS (0x20)
 #define RGB_LED_BRIGHTNESS      (0x30)
 #define RGB_LED                 (0x40)
+#define DEVICE_UID              (0xE0)
+#define DEVICE_UID_LENGTH       (12)
 #define FLASH_WRITE             (0xF0)
 #define FIRMWARE_VERSION        (0xFE)
 #define I2C_ADDRESS             (0xFF)
@@ -63,12 +66,12 @@ typedef enum { AUDIO_MIC_CLOSE = 0, AUDIO_MIC_OPEN } audio_mic_t;
  * @brief Headphone output mode configuration options
  * @details Corresponds to register 0x10 (R/W)
  *
- * @var AUDIO_HPMODE_NATIONAL
- * National Standard audio mode (value: 0, default)
  * @var AUDIO_HPMODE_AMERICAN
- * American Standard audio mode (value: 1)
+ * American Standard (CTIA) audio mode (value: 0, default)
+ * @var AUDIO_HPMODE_NATIONAL
+ * National Standard (OMTP) audio mode (value: 1)
  */
-typedef enum { AUDIO_HPMODE_NATIONAL = 0, AUDIO_HPMODE_AMERICAN } audio_hpmode_t;
+typedef enum { AUDIO_HPMODE_AMERICAN = 0, AUDIO_HPMODE_NATIONAL = 1 } audio_hpmode_t;
 
 /**
  * @brief Class to manage M5ModuleAudio operations including audio input/output and codec control.
@@ -133,6 +136,13 @@ class M5ModuleAudio {
      */
     void setHPMode(audio_hpmode_t mode);
 
+    /**
+     * @brief Enable or disable the microphone in the headset jack.
+     * @param status Headset microphone state (AUDIO_MIC_CLOSE/AUDIO_MIC_OPEN).
+     * @note Controls register 0x11 (R/W). This setting is not persisted.
+     */
+    void setHPMICStatus(audio_mic_t status);
+
     /**
      * @brief Set global brightness for all RGB LEDs
      * @param brightness Brightness value (0-100)
@@ -142,13 +152,20 @@ class M5ModuleAudio {
 
     /**
      * @brief Set color for specific RGB LED
-     * @param num LED number (1-3)
+     * @param num Zero-based LED number (0-2)
      * @param color 24-bit color value (0xRRGGBB)
      * @note Writes to register 0x40 (R/W). Color components are automatically
      *       decomposed into 3 bytes (R, G, B)
      */
     void setRGBLED(uint8_t num, uint32_t color);
 
+    /**
+     * @brief Set all three RGB LEDs to the same color in one I2C transaction
+     * @param color 24-bit color value (0xRRGGBB)
+     * @note Writes 9 bytes to registers 0x40-0x48 in R, G, B order
+     */
+    void setAllRGBLED(uint32_t color);
+
     /**
      * @brief Trigger configuration save to internal Flash
      * @note Writes 1 to register 0xF0 (Write-Only). Requires 20ms for Flash erase.
@@ -158,9 +175,9 @@ class M5ModuleAudio {
 
     /**
      * @brief Set device I2C address
-     * @param newAddr New I2C address (0x08-0x77)
-     * @return Actual set address (may differ if invalid input)
-     * @note Writes to register 0xFF (R/W). Requires reboot to take effect.
+     * @param newAddr New I2C address (0x08-0x77, excluding 0x10 reserved for ES8388)
+     * @return Current device address; unchanged if newAddr is invalid
+     * @note Writes to register 0xFF (R/W). The new address takes effect immediately and is saved automatically.
      */
     uint8_t setI2CAddress(uint8_t newAddr);
 
@@ -178,6 +195,13 @@ class M5ModuleAudio {
      */
     audio_hpmode_t getHPMode();
 
+    /**
+     * @brief Get the microphone state of the headset jack.
+     * @return Current headset microphone state.
+     * @note Reads register 0x11 (R/W).
+     */
+    audio_mic_t getHPMICStatus();
+
     /**
      * @brief Get headphone insertion status
      * @return 0=Not inserted, 1=Inserted
@@ -194,12 +218,19 @@ class M5ModuleAudio {
 
     /**
      * @brief Get current color for specific RGB LED
-     * @param num LED number (1-3)
+     * @param num Zero-based LED number (0-2)
      * @return 24-bit color value (0xRRGGBB)
      * @note Reads from register 0x40 (R/W). Combines 3 bytes (R, G, B) into color
      */
     uint32_t getRGBLED(uint8_t num);
 
+    /**
+     * @brief Read all three RGB LED colors in one I2C transaction
+     * @param colors Output array of three 0xRRGGBB color values
+     * @return true when all 9 register bytes were read successfully
+     */
+    bool getRGBLEDs(uint32_t colors[3]);
+
     /**
      * @brief Get firmware version
      * @return 4-byte version code (e.g., 0x01020304 = v1.2.3.4)
@@ -214,6 +245,14 @@ class M5ModuleAudio {
      */
     uint8_t getI2CAddress();
 
+    /**
+     * @brief Read the STM32 96-bit unique device identifier.
+     * @param uid Destination buffer with room for DEVICE_UID_LENGTH bytes.
+     * @return True when all 12 bytes were read successfully.
+     * @note Reads registers 0xE0 through 0xEB in little-endian word order.
+     */
+    bool getDeviceUID(uint8_t uid[DEVICE_UID_LENGTH]);
+
     /**
      * @brief Sets the speaker volume.
      *
@@ -279,6 +318,14 @@ class M5ModuleAudio {
      */
     bool setMixSourceSelect(es_mixsel_t lmixsel, es_mixsel_t rmixsel);
 
+    /**
+     * @brief Enables or disables the ES8388 analog input bypass to the output mixers.
+     *
+     * @param enabled True to mix analog input into the outputs, false for DAC-only output.
+     * @return bool True if both mixer registers were updated successfully.
+     */
+    bool setLineBypass(bool enabled);
+
     /**
      * @brief Configures ES8388 sample width.
      *
@@ -414,8 +461,9 @@ class M5ModuleAudio {
      * @param reg    The register address from which the data will be read.
      * @param buffer A pointer to the data buffer where the read bytes will be stored.
      * @param length The number of bytes to read into the buffer.
+     * @return True when the complete register range was read successfully.
      */
-    void readBytes(uint8_t addr, uint8_t reg, uint8_t* buffer, uint8_t length);
+    bool readBytes(uint8_t addr, uint8_t reg, uint8_t* buffer, uint8_t length);
 
     // Initializes the ES8388 codec
     bool es8388_codec_init();