Data Structures | Macros
periph_cpu.h File Reference
CPU » ESP32

CPU specific definitions and functions for peripheral handling. More...

Detailed Description

CPU specific definitions and functions for peripheral handling.

Author
Gunar Schorcht gunar.nosp@m.@sch.nosp@m.orcht.nosp@m..net

Definition in file periph_cpu.h.

#include <stdint.h>
+ Include dependency graph for periph_cpu.h:

Go to the source code of this file.

Data Structures

struct  i2c_conf_t
 I2C configuration options. More...
 
struct  spi_conf_t
 SPI configuration structure type. More...
 
struct  uart_conf_t
 UART device configuration. More...
 

Macros

#define CPUID_LEN   (7U)
 Length of the CPU_ID in octets.
 
#define PERIPH_TIMER_PROVIDES_SET
 Prevent shared timer functions from being used.
 

Power management configuration

#define PROVIDES_PM_SET_LOWEST
 
#define PROVIDES_PM_RESTART
 
#define PROVIDES_PM_OFF
 
#define PROVIDES_PM_LAYERED_OFF
 
#define PM_NUM_MODES   (2U)
 Number of usable low power modes.
 

Power modes

#define ESP_PM_MODEM_SLEEP   (2U)
 
#define ESP_PM_LIGHT_SLEEP   (1U)
 
#define ESP_PM_DEEP_SLEEP   (0U)
 

GPIO configuration

#define HAVE_GPIO_T
 Override the default gpio_t type definition. More...
 
typedef unsigned int gpio_t
 
#define GPIO_UNDEF   (0xffffffff)
 Definition of a fitting UNDEF value.
 
#define GPIO_PIN(x, y)   ((x & 0) | y)
 Define a CPU specific GPIO pin generator macro.
 
#define PORT_GPIO   (0)
 Available GPIO ports on ESP32.
 
#define GPIO_PIN_NUMOF   (40)
 Define CPU specific number of GPIO pins.
 

Predefined GPIO names

#define GPIO0   (GPIO_PIN(PORT_GPIO,0))
 
#define GPIO1   (GPIO_PIN(PORT_GPIO,1))
 
#define GPIO2   (GPIO_PIN(PORT_GPIO,2))
 
#define GPIO3   (GPIO_PIN(PORT_GPIO,3))
 
#define GPIO4   (GPIO_PIN(PORT_GPIO,4))
 
#define GPIO5   (GPIO_PIN(PORT_GPIO,5))
 
#define GPIO6   (GPIO_PIN(PORT_GPIO,6))
 
#define GPIO7   (GPIO_PIN(PORT_GPIO,7))
 
#define GPIO8   (GPIO_PIN(PORT_GPIO,8))
 
#define GPIO9   (GPIO_PIN(PORT_GPIO,9))
 
#define GPIO10   (GPIO_PIN(PORT_GPIO,10))
 
#define GPIO11   (GPIO_PIN(PORT_GPIO,11))
 
#define GPIO12   (GPIO_PIN(PORT_GPIO,12))
 
#define GPIO13   (GPIO_PIN(PORT_GPIO,13))
 
#define GPIO14   (GPIO_PIN(PORT_GPIO,14))
 
#define GPIO15   (GPIO_PIN(PORT_GPIO,15))
 
#define GPIO16   (GPIO_PIN(PORT_GPIO,16))
 
#define GPIO17   (GPIO_PIN(PORT_GPIO,17))
 
#define GPIO18   (GPIO_PIN(PORT_GPIO,18))
 
#define GPIO19   (GPIO_PIN(PORT_GPIO,19))
 
#define GPIO21   (GPIO_PIN(PORT_GPIO,21))
 
#define GPIO22   (GPIO_PIN(PORT_GPIO,22))
 
#define GPIO23   (GPIO_PIN(PORT_GPIO,23))
 
#define GPIO25   (GPIO_PIN(PORT_GPIO,25))
 
#define GPIO26   (GPIO_PIN(PORT_GPIO,26))
 
#define GPIO27   (GPIO_PIN(PORT_GPIO,27))
 
#define GPIO32   (GPIO_PIN(PORT_GPIO,32))
 
#define GPIO33   (GPIO_PIN(PORT_GPIO,33))
 
#define GPIO34   (GPIO_PIN(PORT_GPIO,34))
 
#define GPIO35   (GPIO_PIN(PORT_GPIO,35))
 
#define GPIO36   (GPIO_PIN(PORT_GPIO,36))
 
#define GPIO37   (GPIO_PIN(PORT_GPIO,37))
 
#define GPIO38   (GPIO_PIN(PORT_GPIO,38))
 
#define GPIO39   (GPIO_PIN(PORT_GPIO,39))
 

ADC configuration

ESP32 integrates two 12-bit ADCs (ADC1 and ADC2) capable of measuring up to 18 analog signals in total.

Most of these ADC channels are either connected to a number of integrated sensors like a Hall sensors, touch sensors and a temperature sensor or can be connected with certain GPIOs. Integrated sensors are disabled in RIOT's implementation and are not accessible. Thus, up to 18 GPIOs, the RTC GPIOs, can be used as ADC inputs:

  • ADC1 supports 8 channels: GPIO 32-39
  • ADC2 supports 10 channels: GPIO 0, 2, 4, 12-15, 25-27

For each ADC line, an attenuation of the input signal can be defined separately unsing function adc_set_attenuation, see file $RIOTBASE/cpu/esp32/include/adc_arch.h. This results in different full ranges of the measurable voltage at the input. The attenuation can be set to 0 dB, 3 dB, 6 dB and 11 dB, with 11 dB being the standard attenuation. Since an ADC input is measured against a reference voltage Vref of 1.1 V, approximately the following measurement ranges are given when using a corresponding attenuation:

Attenuation Voltage Range Symbol
0 dB 0 ... 1.1V (Vref) ADC_ATTENUATION_0_DB
3 dB 0 ... 1.5V ADC_ATTENUATION_3_DB
6 dB 0 ... 2.2V ADC_ATTENUATION_6_DB
11 dB (default) 0 ... 3.3V ADC_ATTENUATION_11_DB

Please note: The reference voltage Vref can vary from device to device in the range of 1.0V and 1.2V. The Vref of a device can be read with the function adc_vref_to_gpio25 at the pin GPIO 25, see file $RIOTBASE/cpu/esp32/include/adc_arch.h. The results of the ADC input can then be adjusted accordingly.

ADC_GPIOS in the board-specific peripheral configuration defines a list of GPIOs that can be used as ADC channels. The order of the listed GPIOs determines the mapping between the RIOT's ADC lines and the GPIOs.

Note
ADC_GPIOS must be defined even if there are no GPIOs that could be used as ADC channels on the board. In this case, an empty list hast to be defined which just contains the curly braces.

ADC_NUMOF is determined automatically from the ADC_GPIOS definition.

Note
As long as the GPIOs listed in ADC_GPIOS are not initialized as ADC channels with the adc_init function, they can be used for other purposes.
#define ADC_NUMOF_MAX   16
 Number of ADC channels that could be used at maximum. More...
 

DAC configuration

ESP32 supports 2 DAC lines at GPIO25 and GPIO26.

These DACs have a width of 8 bits and produce voltages in the range from 0 V to 3.3 V (VDD_A). The 16 bits DAC values given as parameter of function dac_set are down-scaled to 8 bit.

DAC_GPIOS in the board-specific peripheral configuration defines a list of GPIOs that can be used as DAC channels. The order of the listed GPIOs determines the mapping between the RIOT's DAC lines and the GPIOs.

Note
DAC_GPIOS must be defined even if there are no GPIOs that could be used as DAC channels on the board. In this case, an empty list hast to be defined which just contains the curly braces.

DAC_NUMOF is determined automatically from the DAC_GPIOS definition.

Note
As long as the GPIOs listed in DAC_GPIOS are not initialized as DAC channels with the dac_init function, they can be used for other purposes.
#define DAC_NUMOF_MAX   2
 Number of DAC channels that could be used at maximum.
 

I2C configuration

ESP32 has two built-in I2C interfaces.

The board-specific configuration of the I2C interface I2C_DEV(n) requires the definition of

I2Cn_SPEED, the bus speed, I2Cn_SCL, the GPIO used as SCL signal, and I2Cn_SDA, the GPIO used as SDA signal,

where n can be 0 or 1. If they are not defined, the I2C interface I2C_DEV(n) is not used.

Note
The configuration of the I2C interfaces I2C_DEV(n) must be in continuous ascending order of n.

I2C_NUMOF is determined automatically from board-specific peripheral definitions of I2Cn_SPEED, I2Cn_SCK, and I2Cn_SDA.

#define I2C_NUMOF_MAX   (2)
 Maximum number of I2C interfaces that can be used by board definitions.
 
#define PERIPH_I2C_NEED_READ_REG
 i2c_read_reg required
 
#define PERIPH_I2C_NEED_READ_REGS
 i2c_read_regs required
 
#define PERIPH_I2C_NEED_WRITE_REG
 i2c_write_reg required
 
#define PERIPH_I2C_NEED_WRITE_REGS
 i2c_write_regs required
 

PWM configuration

PWM implementation uses ESP32's high-speed MCPWM modules.

ESP32 has 2 such modules, each with up to 6 channels (PWM_CHANNEL_NUM_DEV_MAX). Thus, the maximum number of PWM devices is 2 and the maximum total number of PWM channels is 12.

PWM0_GPIOS and PWM1_GPIOS in the board-specific peripheral configuration each define a list of GPIOs that can be used with the respective PWM devices as PWM channels. The order of the listed GPIOs determines the association between the RIOT PWM channels and the GPIOs.

Note
The definition of PWM0_GPIOS and PWM1_GPIOS can be omitted or empty. In the latter case, they must at least contain the curly braces. The corresponding PWM device can not be used in this case.

PWM_NUMOF is determined automatically from the PWM0_GPIOS and PWM1_GPIOS definitions.

Note
As long as the GPIOs listed in PWM0_GPIOS and PMW1_GPIOS are not initialized as PWM channels with the pwm_init function, they can be used other purposes.
#define PWM_NUMOF_MAX   (2)
 Maximum number of PWM devices.
 
#define PWM_CHANNEL_NUM_DEV_MAX   (6)
 Maximum number of channels per PWM device.
 

RNG configuration

#define RNG_DATA_REG_ADDR   (0x3ff75144)
 The address of the register for accessing the hardware RNG.
 

RTT and RTC configuration

#define RTT_FREQUENCY   (32768UL)
 RTT frequency definition. More...
 
#define RTT_MAX_VALUE   (0xFFFFFFFFUL)
 RTT is a 32-bit counter.
 

SPI configuration

ESP32 has four SPI controllers:

  • controller SPI0 is reserved for caching the flash memory (CPSI)
  • controller SPI1 is reserved for external memories like flash and PSRAM (FSPI)
  • controller SPI2 realizes interface HSPI that can be used for peripherals
  • controller SPI3 realizes interface VSPI that can be used for peripherals

Thus, a maximum of two SPI controllers can be used as peripheral interfaces:

  • VSPI
  • HSPI

SPI interfaces could be used in quad SPI mode, but RIOT's low level device driver doesn't support it.

The board-specific configuration of the SPI interface SPI_DEV(n) requires the definition of

  • SPIn_CTRL, the SPI controller which is used for the interface (VSPI or HSPI),
  • SPIn_SCK, the GPIO used as clock signal
  • SPIn_MISO, the GPIO used as MISO signal
  • SPIn_MOSI, the GPIO used as MOSI signal, and
  • SPIn_CS0, the GPIO used as CS signal when the cs parameter in spi_aquire is GPIO_UNDEF,

where n can be 0 or 1. If they are not defined, the according SPI interface SPI_DEV(n) is not used.

SPI_NUMOF is determined automatically from the board-specific peripheral definitions of SPIn_*.

#define SPI_NUMOF_MAX   2
 Maximum number of SPI interfaces that can be used by board definitions.
 
#define PERIPH_SPI_NEEDS_TRANSFER_BYTE
 requires function spi_transfer_byte
 
#define PERIPH_SPI_NEEDS_TRANSFER_REG
 requires function spi_transfer_reg
 
#define PERIPH_SPI_NEEDS_TRANSFER_REGS
 requires function spi_transfer_regs
 
enum  spi_ctrl_t { HSPI = 2, VSPI = 3, HSPI = 1 }
 SPI controllers that can be used for peripheral interfaces. More...
 

Timer configuration depenend on which implementation is used

Timers are MCU built-in feature and not board-specific.

They are therefore configured here.

#define TIMER_NUMOF   (3)
 hardware timer modules are used for timer implementation (default)
 
#define TIMER_CHANNEL_NUMOF   (1)
 
#define TIMER_SYSTEM   TIMERG0.hw_timer[0]
 Timer used for system time.
 

UART configuration

ESP32 supports up to three UART devices.

UART_DEV(0) has a fixed pin configuration and is always available. All ESP32 boards use it as standard configuration for the console. 

 UART_DEV(0).TXD      GPIO1
 UART_DEV(0).RXD      GPIO3

The pin configuration of UART_DEV(1) and UART_DEV(2) are defined in board specific peripheral configuration by

  • UARTn_TXD, the GPIO used as TxD signal, and
  • UARTn_RXD, the GPIO used as RxD signal,

where n can be 1 or 2. If they are not defined, the according UART interface UART_DEV(n) is not used.

UART_NUMOF is determined automatically from the board-specific peripheral definitions of UARTn_*.

#define UART_NUMOF_MAX   (3)
 Maximum number of UART interfaces.
 

Macro Definition Documentation

◆ ADC_NUMOF_MAX

#define ADC_NUMOF_MAX   16

Number of ADC channels that could be used at maximum.

Note
GPIO37 and GPIO38 are usually not broken out on ESP32 modules and are therefore not usable. The maximum number of ADC channels (ADC_NUMOF_MAX) is therefore set to 16.

Definition at line 265 of file periph_cpu.h.

◆ HAVE_GPIO_T

#define HAVE_GPIO_T

Override the default gpio_t type definition.

This is required here to have gpio_t defined in this file.

Definition at line 69 of file periph_cpu.h.

◆ RTT_FREQUENCY

#define RTT_FREQUENCY   (32768UL)

RTT frequency definition.

The RTT frequency is always 32.768 kHz even if no external crystal is connected. In this case the RTT value counted with the internal 150 kHz RC oscillator is converted to a value for an RTT with 32.768 kHz.

Definition at line 424 of file periph_cpu.h.

Enumeration Type Documentation

◆ spi_ctrl_t

enum spi_ctrl_t

SPI controllers that can be used for peripheral interfaces.

Enumerator
HSPI 

HSPI interface controller.

VSPI 

VSPI interface controller.

HSPI 

HSPI interface controller.

Definition at line 473 of file periph_cpu.h.