Add JC ESP32-P4 M3 audio firmware support

[ssjgesus]

Summary

Adds a dedicated firmware configuration and hardware profile for the JC-ESP32P4-M3-DEV, including working support for its onboard ES8311 microphone codec for ProjectMM audio-reactive effects.

Changes

• Adds the "esp32p4-jc-m3-eth" firmware variant.
• Adds a "JC-ESP32P4-M3-DEV" device-model entry.
• Configures the onboard ES8311 codec:
  • I²C address: "0x18"
  • SDA: GPIO7
  • SCL: GPIO8
  • BCLK/SCK: GPIO12
  • WS/LRCLK: GPIO10
  • MCLK: GPIO13
  • Microphone data: GPIO48
• Keeps the microphone data pin runtime-configurable.
• Corrects the ES8311 address format at the "esp_codec_dev" driver boundary.
• Configures capture using 32-bit I²S words to match ProjectMM’s audio pipeline.
• Uses the ES8311 codec-control interface directly, allowing ProjectMM to continue managing the I²S data path.
• Adds board documentation, firmware manifest projections and focused regression coverage.
• Adds a GitHub Actions workflow for building a complete ESP32-P4 flash package.

Validation

The following checks pass:

• Python test suite
• JavaScript test suite
• Manifest and device-catalog validation
• Specification and scenario checks
• Desktop warnings-as-errors build
• ESP32-P4 firmware build using ESP-IDF "v6.1-beta1"
• Sanitizer checks

Hardware validation

The firmware has been successfully installed and tested on a physical JC-ESP32P4-M3-DEV.

The onboard ES8311 microphone works with the configured pinout, and ProjectMM’s audio service successfully receives microphone input for audio-reactive effects.

References

• "JC-ESP32P4-M3-DEV community documentation and schematic" (https://github.com/p1ngb4ck/unofficial_guition_esp32p4_repo/tree/main/JC-ESP32P4-M3-Dev)
• "Espressif "esp_codec_dev"" (https://components.espressif.com/components/espressif/esp_codec_dev)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9821372b-1249-4dd2-b242-e4b21305fece

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[ewowi]

Hi @ssjgesus , I didn't know about this board, nice PR !

few questions/remarks

• where to buy this board?
• what is the MP3 part in the name? should it play mp3 files?
• do you have a board image with pins labels (Agents can look at that and reason from it)
• what AI did you use to create the code? Looks pretty coherent with current repo ;-)
• I see a number workflow yml and test python file is created, are they needed (as I don't have them for other firmwares until now)

[wompslab]

these are very simmilar / variants of the P4 880x430 screen devkit I have - they're nice. There's a very good WLED firmware for the 7" variant. I paid about £20 for mine Ali but I'd recommend paying for the next one up that comes with a case in the rear side.

[ewowi]

Thanks for this, and sorry it waited so long.

PR #128 does the same for the Waveshare ESP32-P4-ETH, and the two boards share their codec wiring. Rather than a firmware per board, our next commit makes the ES8311 runtime configuration: esp_codec_dev built for the P4, and the codec with its I2C pins and address as AudioService controls. An existing firmware, esp32p4rev1-eth, then covers this board through a deviceModels.json entry. Your fix for the address format at the esp_codec_dev boundary matches one in #128, and it goes into that commit.

On the microphone data line: the schematic routes it to GPIO48, which is what you tested on the board, while the board's ESPHome example (JC-ESP32-P4.M3-Dev.yaml) uses GPIO11. The entry follows your hardware test; sdPin stays a live control, so 11 can be tried without reflashing. The proposed entry, with the codec control names still to be settled:

{
  "name": "Guition JC-ESP32P4-M3-DEV",
  "chip": "ESP32-P4",
  "firmwares": ["esp32p4rev1-eth"],
  "url": "https://github.com/p1ngb4ck/unofficial_guition_esp32p4_repo/tree/main/JC-ESP32P4-M3-Dev",
  "supported": ["LEDs", "Ethernet", "Audio"],
  "modules": [
    { "type": "System", "id": "System", "controls": { "deviceModel": "Guition JC-ESP32P4-M3-DEV" } },
    { "type": "EthernetModule", "id": "Ethernet", "parent_id": "Network", "controls": { "ethBoard": "P4-NANO" } },
    { "type": "AudioService", "id": "Audio", "parent_id": "Services",
      "controls": { "mode": 2, "codec": "ES8311", "codecSda": 7, "codecScl": 8, "codecAddr": 24,
                    "mclkPin": 13, "sckPin": 12, "wsPin": 10, "sdPin": 48 } }
  ]
}

The Ethernet wiring (IP101, MDC 31, MDIO 52, power 51, clock in on 50) is the P4-NANO preset's. Once the runtime codec lands we can close this in favour of that entry; or, if you prefer, rebase this onto it with the entry and your board documentation, dropping the variant.

[ewowi]

An update: the ES8311 support this PR asked for is built, in a slightly different shape, and goes into main as the latest release in the coming days.

What is built

• The codec is runtime configuration rather than a firmware variant. AudioService has a codec select (none / ES8311) and a codecAddr (0x18), and the codec ships in every ESP32-P4 and S31 firmware, so the existing esp32p4rev1-eth firmware drives the JC-ESP32P4-M3-DEV.
• The I2C pins live on one shared bus module (System, I2cBus, sda 7 / scl 8), which a scan also uses. It now names what it finds, as 0x18 Audio (ES8311).
• The address fix at the esp_codec_dev boundary is in, the same one you found.
• The Guition JC-ESP32P4-M3-DEV has a device catalog entry with your pinout: I2C 7/8, MCLK 13, BCLK 12, WS 10 and the mic data on GPIO48.

Verified with the same codec on a Waveshare P4-ETH, a P4-NANO and an ESP32-S31: the codec found at 0x18 and the mic level following sound. We have no M3 here, so the M3 entry itself is untested on hardware.

Thanks for the pinout and the hardware test, which the catalog entry is built from. Once the release is out, could you install the latest build on your M3 and confirm the mic works? That is the one check we cannot do.

[ewowi]

Thank you @ssjgesus. This is merged in #129 in a different shape: the ES8311 codec became runtime configuration (AudioService codec and codecAddr on a shared I2C bus) rather than a firmware variant, so the Guition JC-ESP32P4-M3-DEV runs on the standard P4 firmware through its own deviceModels.json entry, with mic data on GPIO 48 from your hardware test. We have no M3 on the bench, so could you confirm on the next release that applying the Guition M3 device model gives a mic level that follows sound? Closing in favor of #129; please reopen or open an issue if it does not.