m5_unit_unified_wiring.hpp File Reference

Opt-in, header-only board-aware connection helpers for M5UnitUnified examples. More...

#include "../M5UnitUnified.hpp"
#include <driver/i2c.h>
#include <driver/uart.h>
#include <driver/spi_master.h>
#include <hal/gpio_types.h>
#include <soc/soc_caps.h>

Go to the source code of this file.

Classes
struct	m5::unit::wiring::I2CPins
	I2C backend selection + pin numbers (pure getter result, no side effects) More...
struct	m5::unit::wiring::GpioPinPair
	GPIO rx/tx pin pair; fallback_a indicates port_a fallback was used. More...
struct	m5::unit::wiring::UartPinPair
	UART rx/tx pin pair; fallback_a indicates port_a fallback was used. More...
struct	m5::unit::wiring::SpiPins
	SPI pin set (sclk / miso / mosi) on the board's shared SD/SPI bus. More...
struct	m5::unit::wiring::HatI2CPins
	Hat I2C pin pair + bus selection; sda=scl=-1 if board has no Hat header. More...
struct	m5::unit::wiring::HatPinPair
	Hat rx/tx pin pair (shared by Hat GPIO and Hat UART); rx=tx=-1 if board has no Hat header. More...
struct	m5::unit::wiring::IdfUartParams
	Map UartConfig to ESP-IDF native uart_config_t fields. More...
struct	m5::unit::wiring::detail::UARTCacheEntry
struct	m5::unit::wiring::detail::SPIHostEntry
struct	m5::unit::wiring::detail::SPIDevEntry

Namespaces
namespace	m5
	Top level namespace of M5Stack.

Enumerations
Pin acquisition options (enums, no platform dependency)
enum class	m5::unit::wiring::NessoPort { PortB , PortA }
	NessoN1 connection choice: PortB = direct GROVE (SoftwareI2C), PortA = QWIIC / PbHub (Wire)
enum class	m5::unit::wiring::GpioRole { Both , InOnly , OutOnly }
	GPIO usage role: how many pins of the port the unit actually uses. More...
enum class	m5::unit::wiring::UartConfig : uint32_t {   Default = 0 , _8N1 = 1 , _8N2 = 2 , _8E1 = 3 ,   _8O1 = 4 , _7N1 = 5 , _7E1 = 6 , _7O1 = 7 }
	UART config (word length / parity / stop bits). Common across Arduino and ESP-IDF native. More...

Functions
bool	m5::unit::wiring::detail::ensureI2CLegacyDriver (const i2c_port_t port, const gpio_num_t sda, const gpio_num_t scl, const uint32_t clock)
	Install the legacy I2C master driver once per {port, sda, scl}; cached so re-adds are no-ops.
uart_port_t	m5::unit::wiring::detail::ensureUARTPort (const uart_port_t port, const gpio_num_t rx, const gpio_num_t tx, const uint32_t baud, const UartConfig config)
	Get or install a UART port, cached by {port, rx, tx}.
spi_device_handle_t	m5::unit::wiring::detail::ensureSPIDevice (const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso, const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode, const uint8_t bit_order)
	Get or initialize a SPI device, cached by {host, clock_hz, mode, bit_order}.
ESP-IDF native infrastructure (cache, hooks, defaults)
uart_port_t	m5::unit::wiring::defaultUartPort ()
	The board's default UART port for a Port unit, chosen by SoC UART count (ESP-IDF native)
IdfUartParams	m5::unit::wiring::toIdfUartParams (const UartConfig c)
	The board's default UART port for a Port unit, chosen by SoC UART count (ESP-IDF native)
uart_port_t	m5::unit::wiring::uartPortHandle (const uart_port_t port, const gpio_num_t rx, const gpio_num_t tx, const uint32_t baud, const UartConfig config=UartConfig::Default)
	Get or install a UART port (cached by {port, rx, tx})
spi_device_handle_t	m5::unit::wiring::spiDeviceHandle (const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso, const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode=0, const uint8_t bit_order=0)
	Get or initialize a SPI device on the given host (cached by {host, clock_hz, mode, bit_order})

Variables
constexpr size_t	m5::unit::wiring::detail::kI2CBusCacheSize = 4
constexpr size_t	m5::unit::wiring::detail::kUARTPortCacheSize = 4
constexpr size_t	m5::unit::wiring::detail::kSPIHostCacheSize = 2
constexpr size_t	m5::unit::wiring::detail::kSPIDevCacheSize = 4

Detailed Description

Opt-in, header-only board-aware connection helpers for M5UnitUnified examples.

This header exists solely to keep the example code in M5UnitUnified and M5Unit-* repositories short and readable. Each helper resolves board-specific pins / backends through M5Unified, opens the bus, and calls UnitUnified::add().

Users SHOULD treat these helpers as reference implementations, not as the only supported way to wire a unit. In real applications, prefer to call UnitUnified::add() directly with a bus or handle that fits the application's lifecycle (shared bus management, custom pins, alternative backends, etc.).

Note

REQUIRES <M5Unified.h> (or <M5Unified.hpp>) to be included BEFORE this header. Pin-acquisition helpers (i2cPins / gpioPins / uartPins / spiPins / hatI2CPins / hatGPIOPins / hatUARTPins) work on both Arduino and ESP-IDF (any platform where M5Unified is available). High-level addX helpers (addI2C / addGPIO / addUART / addSPI / addHatI2C / addHatGPIO / addHatUART) provide the same signatures on Arduino and ESP-IDF native, so example code can compile on both frameworks unchanged.

On ESP-IDF native, the following public lifecycle hooks are also exposed for unit-specific wiring developers (M5Unit-* libraries that need to share a bus handle with the generic helpers above): i2cBusHandle, uartPortHandle, spiDeviceHandle. Examples should NOT use these directly; use the generic addX helpers instead.

Enumeration Type Documentation

GpioRole

enum class m5::unit::wiring::GpioRole

strong

GPIO usage role: how many pins of the port the unit actually uses.

Enumerator
Both	Both input and output pins (e.g., IR Tx+Rx)
InOnly	Input only — rx = port_*_in (pin1), tx = -1 (e.g., RF433 Rx, IR Rx alone)
OutOnly	Output only — rx = -1, tx = port_*_out (pin2) (e.g., Flashlight, RF433 Tx, IR Tx alone)

UartConfig

enum class m5::unit::wiring::UartConfig : uint32_t

strong

UART config (word length / parity / stop bits). Common across Arduino and ESP-IDF native.

Enumerator
Default	= _8N1

Function Documentation

ensureSPIDevice()

spi_device_handle_t m5::unit::wiring::detail::ensureSPIDevice ( const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso, const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode, const uint8_t bit_order )

inline

Get or initialize a SPI device, cached by {host, clock_hz, mode, bit_order}.

Note

spics_io_num is fixed to GPIO_NUM_NC; cs is controlled manually by the unit's adapter.

spiDeviceHandle()

spi_device_handle_t m5::unit::wiring::spiDeviceHandle ( const spi_host_device_t host, const gpio_num_t mosi, const gpio_num_t miso, const gpio_num_t sck, const uint32_t clock_hz, const uint8_t mode = 0, const uint8_t bit_order = 0 )

inline

Get or initialize a SPI device on the given host (cached by {host, clock_hz, mode, bit_order})

Note

Intended for unit-specific wiring; examples should use addSPI() instead. CS is controlled manually by the unit's adapter (spics_io_num = GPIO_NUM_NC).

uartPortHandle()

uart_port_t m5::unit::wiring::uartPortHandle ( const uart_port_t port, const gpio_num_t rx, const gpio_num_t tx, const uint32_t baud, const UartConfig config = UartConfig::Default )

inline

Get or install a UART port (cached by {port, rx, tx})

Note

Intended for unit-specific wiring; examples should use addUART() instead.