Migration from 2.x to 3.0

Introduction

This is a guide to highlightbreaking changes in the API and build system to help the migration of projects from versions 2.X (based on ESP-IDF 4.4) to version 3.0 (based on ESP-IDF 5.1) of the Arduino ESP32 core.

All the examples on the version 3.0.0 were updated to be compatible to the new API. The old examples from the versions below 3.0.0 will be not compatible with the version 3.0.0 or newer releases.

For more information about all changes and new features, check projectRELEASE NOTES.

Build System

Compilation Flags

Functional changes

  • If your project uses extra flags in the compilation process, it will now overwritesome required default flags.To ensure your project compiles correctly, make sure to have the-MMD-c flags in your C and C++ extra flags.

APIs

ADC

Removed APIs

  • analogSetClockDiv

  • adcAttachPin

  • analogSetVRefPin

BLE

Changes in APIs

  • Changed APIs return and parameter type fromstd::string to Arduino styleString.

  • Changed UUID data type fromuint16_t toBLEUUID class.

  • BLEScan::start andBLEScan::getResults methods return type changed fromBLEScanResults toBLEScanResults*.

Hall Sensor

Hall sensor is no longer supported.

Removed APIs

  • hallRead

I2S

The I2S driver has been completely redesigned and refactored to use the new ESP-IDF driver.For more information about the new API, checkI2S.

LEDC

The LEDC API has been changed in order to support the Peripheral Manager and make it easier to use, as LEDC channels are now automatically assigned to pins.For more information about the new API, checkLED Control (LEDC).

Removed APIs

  • ledcSetup

  • ledcAttachPin

New APIs

  • ledcAttach used to set up the LEDC pin (mergedledcSetup andledcAttachPin functions).

  • ledcOutputInvert used to attach the interrupt to a timer using arguments.

  • ledcFade used to set up and start a fade on a given LEDC pin.

  • ledcFadeWithInterrupt used to set up and start a fade on a given LEDC pin with an interrupt.

  • ledcFadeWithInterruptArg used to set up and start a fade on a given LEDC pin with an interrupt using arguments.

Changes in APIs

  • ledcDetachPin renamed toledcDetach.

  • In all functions, input parameterchannel has been changed topin.

RMT

For more information about the new API, checkRemote Control (RMT).

Removed APIs

  • _rmtDumpStatus

  • rmtSetTick

  • rmtWriteBlocking

  • rmtEnd

  • rmtBeginReceive

  • rmtReadData

New APIs

  • rmtSetEOT

  • rmtWriteAsync

  • rmtTransmitCompleted

  • rmtSetRxMinThreshold

Changes in APIs

  • In all functions, input parameterrmt_obj_t*rmt has been changed tointpin.

  • rmtInit return parameter changed to bool.

  • rmtInit input parameterbooltx_not_rx has been changed tormt_ch_dir_tchannel_direction.

  • rmtInit new input parameteruint32_tfrequency_Hz to set frequency of RMT channel (as functionrmtSetTick was removed).

  • rmtWrite now sending data in blocking mode. It only returns after sending all data or through a timeout. For Async mode use the newrmtWriteAsync function.

  • rmtWrite new input parameteruint32_ttimeout_ms.

  • rmtLoop renamed tormtWriteLooping.

  • rmtRead input parameters changed tointpin,rmt_data_t*data,size_t*num_rmt_symbols,uint32_ttimeout_ms.

  • rmtReadAsync input parameters changed tointpin,rmt_data_t*data,size_t*num_rmt_symbols.

  • rmtSetRxThreshold renamed tormtSetRxMaxThreshold and input parameteruint32_tvalue has been changed touint16_tidle_thres_ticks.

  • rmtSetCarrier input parametersuint32_tlow,uint32_thigh have been changed touint32_tfrequency_Hz,floatduty_percent.

SigmaDelta

SigmaDelta has been refactored to use the new ESP-IDF driver.For more information about the new API, checkSigmaDelta.

Removed APIs

  • sigmaDeltaSetup

  • sigmaDeltaRead

New APIs

  • sigmaDeltaAttach used to set up the SigmaDelta pin (channel is acquired automatically).

  • timerGetFrequency used to get the actual frequency of the timer.

  • timerAttachInterruptArg used to attach the interrupt to a timer using arguments.

Changes in APIs

  • sigmaDeltaDetachPin renamed tosigmaDeltaDetach.

  • sigmaDeltaWrite input parameterchannel has been changed topin.

Timer

Timer has been refactored to use the new ESP-IDF driver and its API got simplified. For more information about the new API checkTimer.

Removed APIs

  • timerGetConfig

  • timerSetConfig

  • timerSetDivider

  • timerSetCountUp

  • timerSetAutoReload

  • timerGetDivider

  • timerGetCountUp

  • timerGetAutoReload

  • timerAlarmEnable

  • timerAlarmDisable

  • timerAlarmWrite

  • timerAlarmEnabled

  • timerAlarmRead

  • timerAlarmReadMicros

  • timerAlarmReadSeconds

  • timerAttachInterruptFlag

New APIs

  • timerAlarm used to set up Alarm for the timer and enable it automatically (mergedtimerAlarmWrite andtimerAlarmEnable functions).

  • timerGetFrequency used to get the actual frequency of the timer.

  • timerAttachInterruptArg used to attach the interrupt to a timer using arguments.

Changes in APIs

  • timerBegin has now only 1 parameter (frequency). There is an automatic calculation of the divider using different clock sourcesto achieve the selected frequency.

  • timerAttachInterrupt has now only 2 parameters. Theedge parameter has been removed.

UART (HardwareSerial)

Changes in APIs

  • setHwFlowCtrlMode input parameteruint8_tmode has been changed toSerialHwFlowCtrlmode.

  • setMode input parameteruint8_tmode has been changed toSerialModemode.

Functional changes

  • Default pins for some SoCs have been changed to avoid conflicts with other peripherals:* ESP32’s UART1 RX and TX pins are now GPIO26 and GPIO27, respectively;* ESP32’s UART2 RX and TX pins are now GPIO4 and GPIO25, respectively;* ESP32-S2’s UART1 RX and TX pins are now GPIO4 and GPIO5, respectively.

  • It is now possible to detach UART0 pins by callingend() with no previous call ofbegin().

  • It is now possible to callsetPins() beforebegin() or in any order.

  • setPins() will detach any previous pins that have been changed.

  • begin(baud,rx,tx) will detach any previous attached pins.

  • setPins() orbegin(baud,rx,tx) when called at first, will detach console RX0/TX0, attached in boot.

  • Any pin set as -1 inbegin() orsetPins() won’t be changed nor detached.

  • begin(baud) will not change any pins that have been set before this call, through a previousbegin(baud,rx,tx) orsetPin().

  • If the application only uses RX or TX,begin(baud,-1,tx) orbegin(baud,rx) will change only the assigned pin and keep the other unchanged.

Wi-Fi

Functional changes

  • In Arduino (and other frameworks) the method namedflush() is intended to send out the transmit buffer content.WiFiClient andWiFiUDP methodflush() won’t clear the receive buffer anymore. A new method calledclear() is now used for that. Currentlyflush() does nothing inWiFiClient,WiFiClientSecure andWiFiUDP.

  • WiFiServer has functionsaccept() andavailable() with the same functionality. In Arduino,available() should work differently so it is now deprecated.

  • WiFiServer had unimplemented write functions inherited fromPrint class. These are now removed. Also unimplemented methodstopAll() is removed. The methods were unimplemented becauseWiFiServer doesn’t manage connectedWiFiClient objects for print-to-all-clients functionality.