Skip to main content

ESP32-S3 Peripheral Mapping

This document describes the mapping between ESP32-S3 (dual-core Xtensa LX7, AI/audio) on-chip peripherals and the TuyaOpen TKL layer software ports. ESP32-S3 is the primary chip for AI chat and voice applications in TuyaOpen.

GPIO​

  • All usable GPIO pins support interrupts.
  • TUYA_GPIO_NUM_E enum values map 1:1 to physical ESP32-S3 GPIO numbers.
  • TUYA_GPIO_NUM_22 ~ TUYA_GPIO_NUM_25 map to GPIO_NUM_NC and must not be used.
GPIO RangeTUYA_GPIO_NUM RangeNotes
GPIO0 ~ GPIO21TUYA_GPIO_NUM_0 ~ TUYA_GPIO_NUM_21General-purpose IO
—TUYA_GPIO_NUM_22 ~ TUYA_GPIO_NUM_25NC, do not use
GPIO26 ~ GPIO48TUYA_GPIO_NUM_26 ~ TUYA_GPIO_NUM_48General-purpose IO

UART​

  • 2 UART ports supported.
  • UART0 TX/RX pins are controlled by Kconfig options UART_NUM0_TX_PIN / UART_NUM0_RX_PIN, defaulting to GPIO43 / GPIO44.
  • UART1 has dedicated IO_MUX pins. Default pins can be overridden before initialization via tkl_io_pinmux_config().
  • Boards with ENABLE_ESP32S3_USB_JTAG_ONLY route UART0 through the internal USB Serial JTAG controller — no GPIO pins required.
Changing UART0 Pins

Run tos.py config menu in your project directory to enter the board configuration menu, find the relevant options and set the target GPIO numbers, or edit the default entries in boards/ESP32/ESP32-S3/Kconfig directly, then rebuild.

Board PinFunctionSoftware PinSoftware Port
GPIO43 (default)UART0_TXTUYA_GPIO_NUM_43TUYA_UART_NUM_0
GPIO44 (default)UART0_RXTUYA_GPIO_NUM_44TUYA_UART_NUM_0
GPIO17 (default)UART1_TXTUYA_GPIO_NUM_17TUYA_UART_NUM_1
GPIO18 (default)UART1_RXTUYA_GPIO_NUM_18TUYA_UART_NUM_1

I2C​

  • 2 I2C ports supported.
  • Default pins can be overridden before initialization via tkl_io_pinmux_config().
Board Pin (default)FunctionSoftware PinSoftware Port
GPIO0I2C0_SCLTUYA_IIC0_SCLTUYA_I2C_NUM_0
GPIO1I2C0_SDATUYA_IIC0_SDATUYA_I2C_NUM_0
GPIO2I2C1_SCLTUYA_IIC1_SCLTUYA_I2C_NUM_1
GPIO3I2C1_SDATUYA_IIC1_SDATUYA_I2C_NUM_1

PWM​

  • 6 PWM channels, implemented using ESP-IDF LEDC driver (LEDC_LOW_SPEED_MODE, 12-bit resolution).
  • Default pins can be overridden before initialization via tkl_io_pinmux_config().
Board Pin (default)FunctionSoftware PinSoftware Port
GPIO18PWM0TUYA_PWM0TUYA_PWM_NUM_0
GPIO19PWM1TUYA_PWM1TUYA_PWM_NUM_1
GPIO38PWM2TUYA_PWM2TUYA_PWM_NUM_2
GPIO39PWM3TUYA_PWM3TUYA_PWM_NUM_3
GPIO40PWM4TUYA_PWM4TUYA_PWM_NUM_4
GPIO41PWM5TUYA_PWM5TUYA_PWM_NUM_5

ADC​

  • 2 ADC units supported, 10 channels each.
  • Channels are configured via bitmask (ch_list.data), where bit N enables ADC_CHANNEL_N.
  • Attenuation is fixed at ADC_ATTEN_DB_12 (~0–3.3 V range). Calibration uses the curve-fitting scheme.
  • ADC2 shares hardware with the Wi-Fi RF and is unavailable while Wi-Fi is active.

ADC1 (TUYA_ADC_NUM_0)​

Board PinADC ChannelSoftware Port
GPIO1ADC1_CH0TUYA_ADC_NUM_0
GPIO2ADC1_CH1TUYA_ADC_NUM_0
GPIO3ADC1_CH2TUYA_ADC_NUM_0
GPIO4ADC1_CH3TUYA_ADC_NUM_0
GPIO5ADC1_CH4TUYA_ADC_NUM_0
GPIO6ADC1_CH5TUYA_ADC_NUM_0
GPIO7ADC1_CH6TUYA_ADC_NUM_0
GPIO8ADC1_CH7TUYA_ADC_NUM_0
GPIO9ADC1_CH8TUYA_ADC_NUM_0
GPIO10ADC1_CH9TUYA_ADC_NUM_0

ADC2 (TUYA_ADC_NUM_1)​

Wi-Fi Conflict

ESP32-S3 ADC2 shares hardware resources with the Wi-Fi RF. ADC2 reads will fail while Wi-Fi is active. Only use TUYA_ADC_NUM_1 when Wi-Fi is disabled.

Board PinADC ChannelSoftware Port
GPIO11ADC2_CH0TUYA_ADC_NUM_1
GPIO12ADC2_CH1TUYA_ADC_NUM_1
GPIO13ADC2_CH2TUYA_ADC_NUM_1
GPIO14ADC2_CH3TUYA_ADC_NUM_1
GPIO15ADC2_CH4TUYA_ADC_NUM_1
GPIO16ADC2_CH5TUYA_ADC_NUM_1
GPIO17ADC2_CH6TUYA_ADC_NUM_1
GPIO18ADC2_CH7TUYA_ADC_NUM_1
GPIO19ADC2_CH8TUYA_ADC_NUM_1
GPIO20ADC2_CH9TUYA_ADC_NUM_1

References​