Skip to content

Commit 9b93a49

Browse files
lucasssvazlucasssvaz
committedApr 29, 2024
doc(flags): Add build system breaking changes to migration guide
1 parent cf44890 commit 9b93a49

File tree

1 file changed

+41
-29
lines changed

1 file changed

+41
-29
lines changed
 

‎docs/en/migration_guides/2.x_to_3.0.rst

+41-29
Original file line numberDiff line numberDiff line change
@@ -5,62 +5,74 @@ Migration from 2.x to 3.0
55
Introduction
66
------------
77

8-
This is a guide to highlight **breaking changes** in the API and 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.
8+
This is a guide to highlight **breaking 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.
99

1010
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.
1111

1212
For more information about all changes and new features, check project `RELEASE NOTES <https://github.com/espressif/arduino-esp32/releases>`_.
1313

14+
Build System
15+
------------
16+
17+
Extra Flags
18+
***********
19+
20+
* If your project uses extra flags in the compilation process, it will now overwrite `some required default flags <https://github.com/espressif/arduino-esp32/blob/e5330d1797accfc8334e645372595d1bfda07ba2/platform.txt#L66-L67>`_.
21+
To ensure your project compiles correctly, make sure to have the ``-MMD -c`` flags in your C and C++ extra flags.
22+
23+
APIs
24+
----
25+
1426
ADC
15-
---
27+
***
1628

1729
Removed APIs
18-
************
30+
^^^^^^^^^^^^
1931

2032
* ``analogSetClockDiv``
2133
* ``adcAttachPin``
2234
* ``analogSetVRefPin``
2335

2436
BLE
25-
---
37+
***
2638

2739
Changes in APIs
28-
***************
40+
^^^^^^^^^^^^^^^
2941

3042
* Changed APIs return and parameter type from ``std::string`` to Arduino style ``String``.
3143
* Changed UUID data type from ``uint16_t`` to ``BLEUUID`` class.
3244
* ``BLEScan::start`` and ``BLEScan::getResults`` methods return type changed from ``BLEScanResults`` to ``BLEScanResults*``.
3345

3446
Hall Sensor
35-
-----------
47+
***********
3648

3749
Hall sensor is no longer supported.
3850

3951
Removed APIs
40-
************
52+
^^^^^^^^^^^^
4153

4254
* ``hallRead``
4355

4456
I2S
45-
---
57+
***
4658

4759
The I2S driver has been completely redesigned and refactored to use the new ESP-IDF driver.
4860
For more information about the new API, check :doc:`/api/i2s`.
4961

5062
LEDC
51-
----
63+
****
5264

5365
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.
5466
For more information about the new API, check :doc:`/api/ledc`.
5567

5668
Removed APIs
57-
************
69+
^^^^^^^^^^^^
5870

5971
* ``ledcSetup``
6072
* ``ledcAttachPin``
6173

6274
New APIs
63-
********
75+
^^^^^^^^
6476

6577
* ``ledcAttach`` used to set up the LEDC pin (merged ``ledcSetup`` and ``ledcAttachPin`` functions).
6678
* ``ledcOutputInvert`` used to attach the interrupt to a timer using arguments.
@@ -69,18 +81,18 @@ New APIs
6981
* ``ledcFadeWithInterruptArg`` used to set up and start a fade on a given LEDC pin with an interrupt using arguments.
7082

7183
Changes in APIs
72-
***************
84+
^^^^^^^^^^^^^^^
7385

7486
* ``ledcDetachPin`` renamed to ``ledcDetach``.
7587
* In all functions, input parameter ``channel`` has been changed to ``pin``.
7688

7789
RMT
78-
---
90+
***
7991

8092
For more information about the new API, check :doc:`/api/rmt`.
8193

8294
Removed APIs
83-
************
95+
^^^^^^^^^^^^
8496

8597
* ``_rmtDumpStatus``
8698
* ``rmtSetTick``
@@ -90,7 +102,7 @@ Removed APIs
90102
* ``rmtReadData``
91103

92104
New APIs
93-
********
105+
^^^^^^^^
94106

95107
* ``rmtSetEOT``
96108
* ``rmtWriteAsync``
@@ -99,7 +111,7 @@ New APIs
99111

100112

101113
Changes in APIs
102-
***************
114+
^^^^^^^^^^^^^^^
103115

104116
* In all functions, input parameter ``rmt_obj_t* rmt`` has been changed to ``int pin``.
105117
* ``rmtInit`` return parameter changed to bool.
@@ -114,37 +126,37 @@ Changes in APIs
114126
* ``rmtSetCarrier`` input parameters ``uint32_t low, uint32_t high`` have been changed to ``uint32_t frequency_Hz, float duty_percent``.
115127

116128
SigmaDelta
117-
----------
129+
**********
118130

119131
SigmaDelta has been refactored to use the new ESP-IDF driver.
120132
For more information about the new API, check :doc:`/api/sigmadelta`.
121133

122134
Removed APIs
123-
************
135+
^^^^^^^^^^^^
124136

125137
* ``sigmaDeltaSetup``
126138
* ``sigmaDeltaRead``
127139

128140
New APIs
129-
********
141+
^^^^^^^^
130142

131143
* ``sigmaDeltaAttach`` used to set up the SigmaDelta pin (channel is acquired automatically).
132144
* ``timerGetFrequency`` used to get the actual frequency of the timer.
133145
* ``timerAttachInterruptArg`` used to attach the interrupt to a timer using arguments.
134146

135147
Changes in APIs
136-
***************
148+
^^^^^^^^^^^^^^^
137149

138150
* ``sigmaDeltaDetachPin`` renamed to ``sigmaDeltaDetach``.
139151
* ``sigmaDeltaWrite`` input parameter ``channel`` has been changed to ``pin``.
140152

141153
Timer
142-
-----
154+
*****
143155

144156
Timer has been refactored to use the new ESP-IDF driver and its API got simplified. For more information about the new API check :doc:`/api/timer`.
145157

146158
Removed APIs
147-
************
159+
^^^^^^^^^^^^
148160

149161
* ``timerGetConfig``
150162
* ``timerSetConfig``
@@ -164,30 +176,30 @@ Removed APIs
164176
* ``timerAttachInterruptFlag``
165177

166178
New APIs
167-
********
179+
^^^^^^^^
168180

169181
* ``timerAlarm`` used to set up Alarm for the timer and enable it automatically (merged ``timerAlarmWrite`` and ``timerAlarmEnable`` functions).
170182
* ``timerGetFrequency`` used to get the actual frequency of the timer.
171183
* ``timerAttachInterruptArg`` used to attach the interrupt to a timer using arguments.
172184

173185
Changes in APIs
174-
***************
186+
^^^^^^^^^^^^^^^
175187

176188
* ``timerBegin`` has now only 1 parameter (frequency). There is an automatic calculation of the divider using different clock sources
177189
to achieve the selected frequency.
178190
* ``timerAttachInterrupt`` has now only 2 parameters. The ``edge`` parameter has been removed.
179191

180192
UART (HardwareSerial)
181-
---------------------
193+
*********************
182194

183195
Changes in APIs
184-
***************
196+
^^^^^^^^^^^^^^^
185197

186198
* ``setHwFlowCtrlMode`` input parameter ``uint8_t mode`` has been changed to ``SerialHwFlowCtrl mode``.
187199
* ``setMode`` input parameter ``uint8_t mode`` has been changed to ``SerialMode mode``.
188200

189201
Functional changes
190-
******************
202+
^^^^^^^^^^^^^^^^^^
191203

192204
* Default pins for some SoCs have been changed to avoid conflicts with other peripherals:
193205
* ESP32's UART1 RX and TX pins are now GPIO26 and GPIO27, respectively;
@@ -203,10 +215,10 @@ Functional changes
203215
* If the application only uses RX or TX, ``begin(baud, -1, tx)`` or ``begin(baud, rx)`` will change only the assigned pin and keep the other unchanged.
204216

205217
WiFi
206-
----
218+
****
207219

208220
Functional changes
209-
******************
221+
^^^^^^^^^^^^^^^^^^
210222

211223
* In Arduino (and other frameworks) the method named ``flush()`` is intended to send out the transmit buffer content. ``WiFiClient`` and ``WiFiUDP`` method ``flush()`` won't clear the receive buffer anymore. A new method called ``clear()`` is now used for that. Currently ``flush()`` does nothing in ``WiFiClient``, ``WiFiClientSecure`` and ``WiFiUDP``.
212224
* ``WiFiServer`` has functions ``accept()`` and ``available()`` with the same functionality. In Arduino, ``available()`` should work differently so it is now deprecated.

0 commit comments

Comments
 (0)