espp/m5stack-cardputer

Readme

# M5Stack Cardputer Board Support Package (BSP) Component

[![Badge](https://components.espressif.com/components/espp/m5stack-cardputer/badge.svg)](https://components.espressif.com/components/espp/m5stack-cardputer)

The M5Stack Cardputer (K132) and Cardputer ADV are card-sized computers based
on the ESP32-S3 StampS3 module, with a 56-key QWERTY keyboard, a 1.14" 240x135
IPS display, a mono speaker, a microphone, a micro-SD card slot, an IR
transmitter, a Grove port, and a WS2812 RGB LED.

The `espp::M5StackCardputer` component supports **both variants with the same
API**, detecting the board at runtime (see `variant()`), and provides a
singleton hardware abstraction for initializing and using the subsystems:

- **Display**: 1.14" 240x135 IPS TFT (ST7789V2) over SPI @ 40 MHz, with LVGL
  integration via `espp::Display` and PWM backlight brightness control.
- **Keyboard**: on the original, the 56-key matrix (scanned through a 74HC138
  3-to-8 demultiplexer) is polled by a scanner task; on the ADV the same 56
  keys are read from the TCA8418 I2C keyboard controller's event FIFO. Either
  way, a callback is invoked once per key state change with the key's matrix
  position, resolved character (shift-aware), fn-layer special key (F1-F12,
  arrows, esc, delete), and modifier state (fn / shift / ctrl / opt / alt).
- **Audio output**: `initialize_audio()` (an `AudioConfig` -
  `espp::Audio::AppConfig`, started from `default_audio_config()` - picks the
  sample rate, which directions to set up, the playback buffer and the tasks), a mono speaker with `play_audio()` /
  `clear_audio()`, runtime sample-rate control, and software volume / mute,
  through the espp `audio` component (`audio()` returns it). On the original
  the I2S stream drives an NS4168 amplifier directly; on the ADV it goes
  through an ES8311 codec (clocked from BCLK, set up by the BSP) into an
  NS4150B amplifier.
- **Microphone**: with `AudioConfig::recording_enabled`,
  `start_audio_recording()` delivers 16-bit mono samples to a callback, with
  adjustable volume via `microphone_volume()`. Original: SPM1423 PDM
  microphone on its own I2S port (`microphone_audio()`; volume applied in
  software); ADV: analog MEMS microphone via the ES8311 codec's ADC (volume
  applied in the codec). The older `initialize_sound()` /
  `initialize_microphone()` are kept as deprecated forwarders.
- **uSD card**: SPI-mode micro-SD mounted at `/sdcard`.
- **RGB LED**: the StampS3's WS2812 via `espp::Neopixel`.
- **Battery**: battery voltage measurement (2:1 divider into ADC1) and an
  estimated state of charge from a 1S lithium-ion discharge curve.
- **G0 (BOOT) button**: via `espp::Interrupt` with a callback.
- **IR transmitter / Grove port**: pin accessors for use with your own RMT /
  I2C drivers.
- **IMU** (ADV only): the BMI270 on the internal I2C bus via
  `initialize_imu()` / `imu()` (espp `bmi270` driver, with optional
  orientation filter).
- **Internal I2C bus** (ADV only): accessor for the bus hosting the TCA8418
  (0x34), ES8311 (0x18), and BMI270 (0x68).

> [!NOTE]
> On the original Cardputer the speaker and microphone cannot be used at the
> same time: GPIO 43 doubles as the speaker's I2S word-select and the PDM
> microphone's (MHz-range) clock - two different signals on one physical pin
> - so `initialize_audio()` with both playback and recording enabled fails
> there. On the Cardputer ADV both go through the ES8311 codec in full duplex
> on a single I2S bus (shared bit/word clocks, separate data pins), so the
> speaker and microphone can be used simultaneously, at one sample rate.

## Example

The [example](./example) shows how to use the `espp::M5StackCardputer` hardware
abstraction component to initialize the display (with a `Gui` class built on
LVGL), type text with the keyboard, play key-click sounds on the speaker, cycle
the RGB LED color, and monitor the battery voltage.