GPIO

GPIO is one of the most commonly used and versatile peripherals in microcontrollers. It is typically used to write and read pin states, with common operations including controlling LED lights, reading buttons, and more.

pinMode

void pinMode(uint8_t pin, uint8_t mode);

Function: Sets the working mode of the specified GPIO.
Parameters:

  • pin: GPIO pin number
  • mode: Operation mode
    • INPUT: Input without pull-up or high impedance
    • OUTPUT: Output mode
    • INPUT_PULLDOWN: Internal pull-down input
    • INPUT_PULLUP: Internal pull-up input

Example:

pinMode(3, OUTPUT);  // Set GPIO3 to output mode

digitalWrite

void digitalWrite(uint8_t pin, uint8_t val);

Function: Sets the level state of the specified GPIO (this function is only used when the GPIO is in OUTPUT mode).
Parameters:

  • pin: GPIO pin number
  • val: Level state
    • HIGH: High level
    • LOW: Low level

Example:

pinMode(3, OUTPUT);  // Set GPIO3 to output mode
digitalWrite(3, HIGH);  // Set GPIO3 to high level

digitalRead

int digitalRead(uint8_t pin);

Function: Reads the level state of the specified GPIO (this function is only used when the GPIO is in INPUT, INPUT_PULLDOWN, or INPUT_PULLUP mode).
Parameters:

  • pin: GPIO pin number

Return value: HIGH or LOW

Example:

pinMode(3, INPUT);  // Set GPIO3 to input mode
int value = digitalRead(3);  // Read the level of GPIO3

Interrupts

The interrupt function enables the main controller to respond quickly when the IO level changes.

attachInterrupt

attachInterrupt(uint8_t pin, voidFuncPtr handler, int mode);

Function: Attach an interrupt to the defined GPIO.
Parameters:

  • pin: GPIO pin number
  • handler: The function to handle the interrupt
  • mode: Set the interrupt mode
    • DISABLED: Disabled
    • RISING: Rising edge interrupt
    • FALLING: Falling edge interrupt
    • CHANGE: Both edges interrupt
    • ONLOW: Low level interrupt
    • ONHIGH: High level interrupt
    • ONLOW_WE: Low level interrupt with debounce
    • ONHIGH_WE: High level interrupt with debounce

Example:

void ARDUINO_ISR_ATTR isr() {
  // Add interrupt handling code
}
 
void setup() {
  pinMode(3, INPUT_PULLUP);
  attachInterrupt(3, isr, FALLING); // Set GPIO3 as a falling edge interrupt, and call the isr function when the interrupt is triggered
}
 
void loop() {
}

detachInterrupt

detachInterrupt(uint8_t pin);

Function: Detach the interrupt from the pin.
Parameters:

  • pin: GPIO pin number

Example:

void ARDUINO_ISR_ATTR isr() {
  // Add interrupt handling code
}
 
void setup() {
  pinMode(3, INPUT_PULLUP);
  attachInterrupt(3, isr, FALLING);
  detachInterrupt(3);
}
 
void loop() {
}

ADC

ADC (Analog-to-Digital Converter) is a very common peripheral used to convert analog signals such as voltage into digital form, so that the microcontroller can read and process them.

Note: Each ESP32 has a different number of ADC pins and channels. Please refer to the corresponding ESP32 datasheet.

analogRead

uint16_t analogRead(uint8_t pin);

Function: Reads the uncalibrated raw ADC value of the specified GPIO.
Parameters:

  • pin: GPIO pin number

Return value: Raw ADC value

Example:

uint16_t value = analogRead(3);  // Reads the raw ADC value of GPIO3

analogReadMillivolts

uint32_t analogReadMilliVolts(uint8_t pin);

Function: Reads the raw ADC value of the specified GPIO and converts it to an uncalibrated voltage value (in mV).
Parameters:

  • pin: GPIO pin number

Return value: ADC voltage value

Example:

uint32_t analogVolts = analogReadMilliVolts(3);  // Reads the ADC voltage value of GPIO3

analogReadResolution

void analogReadResolution(uint8_t bits);

Function: Sets the resolution of the return value of the "analogRead" function.
Parameters:

  • bits: Sets the analog read resolution (range: 1-16, the specific usable values refer to the chip specifications; ESP32-S3 defaults to 13 bits, and other chips default to 12 bits)

Example:

analogReadResolution(10);  // Sets the resolution to 10 bits

PWM

Note: Each ESP32 has PWM channels of different types. Please refer to the corresponding ESP32 datasheet.

analogWrite

void analogWrite(uint8_t pin, int value);

Function: Sets the GPIO to output PWM waves (same function as Arduino).
Parameters:

  • pin: GPIO pin number
  • value: Duty cycle (0-255)

Return value: true or false

Example:

analogWrite(3, 150);  // GPIO3 outputs a duty cycle of 150

ledcAttach

bool ledcAttach(uint8_t pin, uint32_t freq, uint8_t resolution);

Function: Sets the PWM frequency and resolution of the specified GPIO.
Parameters:

  • pin: GPIO pin number
  • freq: PWM frequency
  • resolution: Resolution of the PWM channel (1-14 bits; 1-20 bits for ESP32)

Return value: true or false

Example:

ledcAttach(3, 5000, 12);  // Sets the PWM frequency of GPIO3 to 5000Hz and the resolution to 12 bits

ledcWrite

bool ledcWrite(uint8_t pin, uint32_t duty);

Function: Sets the duty cycle of the specified GPIO.
Parameters:

  • pin: GPIO pin number
  • duty: Duty cycle (0-255)

Return value: true or false

Example:

ledcAttach(3, 5000, 12);  // Sets the PWM frequency of GPIO3 to 5000Hz and the resolution to 12 bits
ledcWrite(3, 150);  // Sets the duty cycle of GPIO3 to 150

ledcWriteTone

uint32_t ledcWriteTone(uint8_t pin, uint32_t freq);

Function: Sets the GPIO to a 50% PWM tone at the selected frequency (can be used to control buzzers).
Parameters:

  • pin: GPIO pin number
  • freq: PWM frequency

Return value: The frequency set for the pin; returns 0 if an error occurs

Example:

ledcAttach(3, 5000, 12);  // Sets the PWM frequency of GPIO3 to 5000Hz and the resolution to 12 bits
ledcWriteTone(3, 500);  // Sets the frequency of GPIO3 to 500Hz

ledcDetach

bool ledcDetach(uint8_t pin);

Function: Detaches the PWM function from the GPIO.
Parameters:

  • pin: GPIO pin number

Return value: true or false

Example:

ledcAttach(3, 5000, 12);  // Sets the PWM frequency of GPIO3 to 5000Hz and the resolution to 12 bits
ledcDetach(3);  // Detaches the PWM function from GPIO3

ledcFade

bool ledcFade(uint8_t pin, uint32_t start_duty, uint32_t target_duty, int max_fade_time_ms);

Function: Sets and starts the fade-in and fade-out of the GPIO.
Parameters:

  • pin: GPIO pin number
  • start_duty: Initial duty cycle
  • target_duty: End duty cycle
  • max_fade_time_ms: Fade-in and fade-out duration (in milliseconds)

Return value: true or false

Example:

ledcAttach(3, 5000, 12);  // Sets the PWM frequency of GPIO3 to 5000Hz and the resolution to 12 bits
ledcFade(3, 0, 255, 2000); // The duty cycle of GPIO3 increases from 0 to 255 within 2000ms

TOUCH

Some GPIOs of the ESP32 can be used as touch buttons to replace mechanical buttons.

Note: Not every ESP32 has touch peripherals. Please refer to the datasheet of the corresponding ESP32.

touchRead

touch_value_t touchRead(uint8_t pin);

Function: Reads the return data from the touch pin.
Parameters:

  • pin: GPIO pin number

Return value: uint16_t for ESP32, uint32_t for ESP32-S3/S3

Example:

touch_value_t touchvalue = touchRead(3);  // Reads the touch return value of GPIO3

touchAttachInterrupt

void touchAttachInterrupt(uint8_t pin, void (*userFunc)(void), touch_value_t threshold);

Function: Sets up a touch interrupt.
Parameters:

  • pin: GPIO pin number
  • userFunc: Interrupt callback function
  • threshold: Touch interrupt threshold

Example:

void gotTouch() {
  // Add interrupt handling code
}
 
void setup() {
  touchAttachInterrupt(3, gotTouch, 50);  // Generates an interrupt when the touch threshold of GPIO3 exceeds 50, calling the gotTouch function
}
 
void loop() {
}

touchDetachInterrupt

void touchDetachInterrupt(uint8_t pin);

Function: Detaches the touch interrupt function from the GPIO.
Parameters:

  • pin: GPIO pin number

Example:

void gotTouch() {
  // Add interrupt handling code
}
 
void setup() {
  touchAttachInterrupt(3, gotTouch, 50);  // Generates an interrupt when the touch threshold of GPIO3 exceeds 50, calling the gotTouch function
  touchDetachInterrupt(3);  // Detaches the touch interrupt function from GPIO3
}
 
void loop() {
}

touchSleepWakeUpEnable

void touchSleepWakeUpEnable(uint8_t pin, touch_value_t threshold);

Function: Sets the GPIO as a wake-up source for deep sleep (ESP32-S2/S3 only supports one touch wake-up GPIO).
Parameters:

  • pin: GPIO pin number
  • threshold: Wake-up threshold

Example:

touchSleepWakeUpEnable(3, 50);  // Sets GPIO3 as a wake-up source for deep sleep with a wake-up threshold of 50

touchInterruptGetLastStatus

bool touchInterruptGetLastStatus(uint8_t pin);

Function: Detects if the touch is continuous (ESP32-S2/S3 only).
Parameters:

  • pin: GPIO pin number

Return value: true or false

Example:

touchSleepWakeUpEnable(3, 50);  // Sets GPIO3 as a wake-up source for deep sleep with a wake-up threshold of 50
Back to Top