Tab5 Keyboard Unit for M5UnitUnified. More...

#include "unit_Keyboard.hpp"
#include <array>
#include <bitset>
#include <memory>
#include <string>
#include "../utility/bitwise_state.hpp"

Go to the source code of this file.

Classes
struct	m5::unit::tab5_keyboard::HidMapping
	HID Usage Code + base modifier byte for a Tab5 Keyboard matrix position. More...

struct	m5::unit::tab5_keyboard::Event
	Unified event payload for all 3 operation modes (tagged union, POD) More...

class	m5::unit::UnitTab5Keyboard
	Tab5 built-in keyboard unit connected via I2C ExtPort1. More...

struct	m5::unit::UnitTab5Keyboard::config_t
	Settings for begin. More...

Namespaces
namespace	m5
	Top level namespace of M5Stack.

namespace	tab5_keyboard
	Constants and types for Tab5 Keyboard.

Typedefs
using	m5::unit::tab5_keyboard::key_status_bits_t = std::bitset<KEY_COUNT>
	Bitset type for tracking per-key state (Normal mode)

Enumerations
enum class	m5::unit::tab5_keyboard::EventType : uint8_t { None = 0 , Key = 1 , Hid = 2 , Character = 3 }
	Discriminator for tab5_keyboard::Event tagged union. More...

enum class	m5::unit::tab5_keyboard::Mode : uint8_t { Normal = 0 , HID = 1 , Character = 2 }
	Keyboard operation mode (REG_MODE_KEYBOARD 0x10) More...

enum class	m5::unit::tab5_keyboard::RgbMode : uint8_t { Bind = 0 , Custom = 1 }
	RGB LED operation mode (REG_MODE_RGB 0x11) More...

Functions
bool	m5::unit::tab5_keyboard::isModifierKey (const uint8_t row, const uint8_t col)
	True if the given (row, col) corresponds to a modifier key (Sym/Aa/Ctrl/Alt)

uint8_t	m5::unit::tab5_keyboard::toKeyIndex (const uint8_t row, const uint8_t col)
	Convert (row, col) to flat key index (0..KEY_COUNT-1)

HidMapping	m5::unit::tab5_keyboard::keyMatrixToHidBase (const uint8_t row, const uint8_t col)
	Base (no Sym held) HID mapping for the given (row, col)

HidMapping	m5::unit::tab5_keyboard::keyMatrixToHidSym (const uint8_t row, const uint8_t col)
	Sym-held variant of the HID mapping for the given (row, col)

Variables
constexpr uint8_t	m5::unit::tab5_keyboard::KEY_EVENT_EMPTY {0xFF}
	Sentinel value returned when the Normal-mode event queue is empty.

constexpr uint8_t	m5::unit::tab5_keyboard::CHAR_EVENT_MAX_CHARS {9}
	Maximum character payload length in one CHAR_EVENT (char0..char8)

constexpr uint32_t	m5::unit::tab5_keyboard::I2C_ADDRESS_WRITE_DELAY_MS {50}
	Milliseconds to wait after writing I2C address to REG_I2C_ADDRESS (datasheet: Flash erase ~20 ms; use 50 ms margin for hardware/firmware variance)

constexpr uint8_t	m5::unit::tab5_keyboard::RGB_LED_COUNT {2}
	Number of RGB LEDs on the device.

constexpr uint8_t	m5::unit::tab5_keyboard::KEY_COUNT {70}
	Total number of keys in the Tab5 Keyboard matrix (5 rows x 14 cols)

constexpr uint8_t	m5::unit::tab5_keyboard::KEY_COL_COUNT {14}
	Number of columns in the Tab5 Keyboard matrix.

constexpr uint32_t	m5::unit::tab5_keyboard::DEFAULT_STORED_SIZE {16}
	Default internal CircularBuffer<Event> capacity (~256 bytes total)

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_INT_CFG {REG_INT_CFG}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_INT_STAT {REG_INT_STAT}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_EVENT_NUM {REG_EVENT_NUM}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_BRIGHTNESS {REG_BRIGHTNESS}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_MODE_KEYBOARD {REG_MODE_KEYBOARD}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_MODE_RGB {REG_MODE_RGB}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_KEY_EVENT {REG_KEY_EVENT}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_HID_EVENT {REG_HID_EVENT}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_CHAR_EVENT_LENGTH {REG_CHAR_EVENT_LENGTH}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_CHAR_EVENT {REG_CHAR_EVENT}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_RGB1_B {REG_RGB1_B}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_FIRMWARE_VERSION {REG_FIRMWARE_VERSION}

constexpr uint8_t	m5::unit::tab5_keyboard::command::CMD_I2C_ADDRESS {REG_I2C_ADDRESS}

Modifier key positions in Normal mode (5x14 matrix)
constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_ROW_SYM {3}
	Hardware-confirmed (row, col) of the four modifier keys. In Normal mode these arrive as ordinary Key events; the library excludes them from software auto-repeat via isModifierKey().

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_COL_SYM {0}
	Sym key column.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_ROW_AA {3}
	Aa key row.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_COL_AA {1}
	Aa key column.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_ROW_CTRL {4}
	Ctrl key row.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_COL_CTRL {0}
	Ctrl key column.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_ROW_ALT {4}
	Alt key row.

constexpr uint8_t	m5::unit::tab5_keyboard::MODIFIER_KEY_COL_ALT {1}
	Alt key column.

Pre-computed key indices for the modifier keys
constexpr uint8_t	m5::unit::tab5_keyboard::KIDX_SYM = MODIFIER_KEY_ROW_SYM * KEY_COL_COUNT + MODIFIER_KEY_COL_SYM
	42 (Sym)

constexpr uint8_t	m5::unit::tab5_keyboard::KIDX_AA = MODIFIER_KEY_ROW_AA * KEY_COL_COUNT + MODIFIER_KEY_COL_AA
	43 (Aa)

constexpr uint8_t	m5::unit::tab5_keyboard::KIDX_CTRL = MODIFIER_KEY_ROW_CTRL * KEY_COL_COUNT + MODIFIER_KEY_COL_CTRL
	56 (Ctrl)

constexpr uint8_t	m5::unit::tab5_keyboard::KIDX_ALT = MODIFIER_KEY_ROW_ALT * KEY_COL_COUNT + MODIFIER_KEY_COL_ALT
	57 (Alt)

Detailed Description

Tab5 Keyboard Unit for M5UnitUnified.

Enumeration Type Documentation

◆ EventType

enum class m5::unit::tab5_keyboard::EventType : uint8_t

strong

Discriminator for tab5_keyboard::Event tagged union.

Enumerator
None	No event (queue empty sentinel)
Key	Normal mode: matrix coordinate event.
Hid	HID mode: modifier + keycode.
Character	Character mode: modifier + UTF-8 string (<=9 bytes)

◆ Mode

enum class m5::unit::tab5_keyboard::Mode : uint8_t

strong

Keyboard operation mode (REG_MODE_KEYBOARD 0x10)

Enumerator
Normal	Normal mode: returns matrix coordinate events (5 rows x 14 cols)
HID	HID mode: returns HID modifier + keycode.
Character	Character mode: returns modifier + UTF-8 string.

◆ RgbMode

enum class m5::unit::tab5_keyboard::RgbMode : uint8_t

strong

RGB LED operation mode (REG_MODE_RGB 0x11)

Enumerator

Bind

Bind mode: LED color is driven by firmware. Observed behavior on real hardware:

Right LED (RGB2) indicates the current keyboard mode: Blue = Mode::Normal Green = Mode::HID Purple= Mode::Character
Left LED (RGB1) indicates run-time state (modifier / activity). Default after power-on (REG_MODE_RGB default = 0).

Custom

Custom mode: LED color is set via REG_RGB1_B/G/R and REG_RGB2_B/G/R. Use writeRgb()/readRgb() to control. writeRgbMode(Custom) must be called first.

Function Documentation

◆ isModifierKey()

bool m5::unit::tab5_keyboard::isModifierKey	(	const uint8_t	row,
		const uint8_t	col )

inline

True if the given (row, col) corresponds to a modifier key (Sym/Aa/Ctrl/Alt)

Parameters

row	Matrix row (0-4)
col	Matrix column (0-13)

Returns: True if the position is a modifier key (Sym/Aa/Ctrl/Alt)

Note: Used by software auto-repeat to skip modifier keys (holding Sym must not spawn repeat events). User code can also call this to filter events.

◆ keyMatrixToHidBase()

HidMapping m5::unit::tab5_keyboard::keyMatrixToHidBase	(	const uint8_t	row,
		const uint8_t	col )

Base (no Sym held) HID mapping for the given (row, col)

Parameters

row	Matrix row (0..4)
col	Matrix column (0..13)

Returns: HidMapping for the key. Returns {0, 0} for out-of-range coordinates and for the four modifier keys (Sym/Aa/Ctrl/Alt).

Note: US ANSI layout, derived from Tab5 firmware HID-mode logs.

◆ keyMatrixToHidSym()

HidMapping m5::unit::tab5_keyboard::keyMatrixToHidSym	(	const uint8_t	row,
		const uint8_t	col )

Sym-held variant of the HID mapping for the given (row, col)

Parameters

row	Matrix row (0..4)
col	Matrix column (0..13)

Returns: HidMapping that reflects the Sym-layer character. Keys whose Sym layer is identical to the base layer return the same value as keyMatrixToHidBase(). Modifier keys and out-of-range coordinates return {0, 0}.

◆ toKeyIndex()

uint8_t m5::unit::tab5_keyboard::toKeyIndex	(	const uint8_t	row,
		const uint8_t	col )

inline

Convert (row, col) to flat key index (0..KEY_COUNT-1)

Parameters

row	Matrix row (0..4)
col	Matrix column (0..13)

Returns: Flat key index = row * 14 + col

Note: No bounds checking — caller is responsible for valid (row, col).

Variable Documentation

◆ KEY_EVENT_EMPTY

uint8_t m5::unit::tab5_keyboard::KEY_EVENT_EMPTY {0xFF}

constexpr

Sentinel value returned when the Normal-mode event queue is empty.

Note: Normal mode: empty = 0xFF (1 byte). HID mode: empty = 0xFF 0xFF (2 bytes). Char mode: empty when REG_CHAR_EVENT_LENGTH (0x40) reads 0.

◆ MODIFIER_KEY_ROW_SYM

uint8_t m5::unit::tab5_keyboard::MODIFIER_KEY_ROW_SYM {3}

constexpr

Hardware-confirmed (row, col) of the four modifier keys. In Normal mode these arrive as ordinary Key events; the library excludes them from software auto-repeat via isModifierKey().

Sym key row

Classes

Namespaces

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ EventType

◆ Mode

◆ RgbMode

Function Documentation

◆ isModifierKey()

◆ keyMatrixToHidBase()

◆ keyMatrixToHidSym()

◆ toKeyIndex()

Variable Documentation

◆ KEY_EVENT_EMPTY

◆ MODIFIER_KEY_ROW_SYM