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**: mono speaker with `play_audio()`, runtime sample-rate
  control, and software volume / mute. On the original the I2S stream drives
  an NS4168 amplifier directly; on the ADV it goes through an ES8311 codec
  (initialized automatically) into an NS4150B amplifier.
- **Microphone**: a recording task delivers 16-bit mono samples to a
  callback, with adjustable volume via `microphone_volume()`. Original:
  SPM1423 PDM microphone (volume applied in software); ADV: analog MEMS
  microphone via the ES8311 codec's ADC (volume applied in the codec).
- **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 initializing one while the other is active will fail. 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; they share the I2S sample rate,
> which is set by whichever subsystem is initialized first.

## 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.