Arduino Nano ESP32 Pin Numbering: D-Labels vs GPIO Numbers

Arduino Nano ESP32 Pin Numbering: D-Labels vs GPIO Numbers

The Arduino Nano ESP32 has two sets of pin numbers. The board carries classic Nano labels such as D2 and A0, while the ESP32-S3 chip underneath uses its own GPIO numbers. The two sets do not match: the pin labelled...

The Arduino Nano ESP32 has two sets of pin numbers. The board carries classic Nano labels such as D2 and A0, while the ESP32-S3 chip underneath uses its own GPIO numbers. The two sets do not match: the pin labelled D2 is GPIO5, and GPIO2 is the pin labelled A1. Because of this, the number 2 in a sketch can address two different pins, depending on one setting in the Arduino IDE.

The fix is short: write the labels in your code. D2, A0 and the other labels always address the pin that carries that label, whichever setting is active. The rest of this guide gives the complete Arduino Nano ESP32 pinout map from D-labels to GPIO numbers, explains the two numbering modes, and shows which one to use with ESP32 libraries and MicroPython. The Arduino Nano ESP32 pinout page shows where each pin sits on the board.

Arduino Nano ESP32 pinout diagram

Arduino Nano ESP32 D-Label to GPIO Map

The table below lists every labelled pin with both of its numbers. The Arduino pin number is the value the label has in the default mode, and the GPIO number is the one the ESP32-S3 uses.

Board label

Arduino pin number

ESP32-S3 GPIO

Default role

D0

0

GPIO44

UART RX (Serial0)

D1

1

GPIO43

UART TX (Serial0)

D2

2

GPIO5

D3

3

GPIO6

D4

4

GPIO7

D5

5

GPIO8

D6

6

GPIO9

D7

7

GPIO10

D8

8

GPIO17

D9

9

GPIO18

D10

10

GPIO21

SPI chip select

D11

11

GPIO38

SPI COPI

D12

12

GPIO47

SPI CIPO

D13

13

GPIO48

SPI SCK and onboard LED (LED_BUILTIN)

A0

17

GPIO1

Analog input on ADC1

A1

18

GPIO2

Analog input on ADC1

A2

19

GPIO3

Analog input on ADC1

A3

20

GPIO4

Analog input on ADC1

A4

21

GPIO11

I2C SDA, analog input on ADC2

A5

22

GPIO12

I2C SCL, analog input on ADC2

A6

23

GPIO13

Analog input on ADC2

A7

24

GPIO14

Analog input on ADC2

LED_RED

14

GPIO46

Red channel of the RGB LED, also header pin B0

LED_GREEN

15

GPIO0

Green channel of the RGB LED, also header pin B1

LED_BLUE

16

GPIO45

Blue channel of the RGB LED


Two details in the table need a comment. The Arduino pin numbers for A0 to A7 start at 17, because 14, 15 and 16 belong to the three channels of the onboard RGB LED. The header pins B0 and B1 have no D-label. They are the chip's boot pins on GPIO46 and GPIO0, the same GPIOs that drive the red and green LED channels, so leave both unconnected in a project.

Why the Same Number Can Mean Two Pins

The mismatch comes from a design choice. Arduino numbered the pins to match the Nano form factor, so that projects made for other Nano boards keep working on the Nano ESP32. Code written for other ESP32 boards expects GPIO numbers. To serve both groups, the Arduino IDE offers two modes under Tools > Pin Numbering:

  • By Arduino pin (default). A bare number is an Arduino pin number, the standard for Nano boards.

  • By GPIO number (legacy). A bare number is a GPIO number, the standard for most ESP32 boards.

Take the line pinMode(2, OUTPUT). In the default mode it configures the pin labelled D2, which is GPIO5. In legacy mode the same line configures GPIO2, which is the pin labelled A1. The sketch compiles in both cases, so nothing warns you that the output moved to another pin.

The labels remove this ambiguity. The board package defines D2 as 2 in the default mode and as 5 in legacy mode, so pinMode(D2, OUTPUT) reaches the pin labelled D2 in both. The three lines below show the difference.

pinMode(D2, OUTPUT);  // pin D2 in both modes

pinMode(2, OUTPUT);   // pin D2 only in By Arduino pin (default)

pinMode(5, OUTPUT);   // pin D2 only in By GPIO number (legacy)

A change of mode takes effect with the next upload. To check which mode a sketch was compiled in, print the value of two labels:

void setup() {

  Serial.begin(115200);

  delay(2000);

  Serial.print("D2 = ");

  Serial.println(D2);

  Serial.print("A0 = ");

  Serial.println(A0);

}


void loop() {

}


In the default mode the sketch prints D2 = 2 and A0 = 17. In legacy mode it prints D2 = 5 and A0 = 1.

When to Switch to GPIO Numbering

The default mode works for the Arduino functions, such as digitalWrite() and analogRead(). Third-party ESP32 libraries are the exception. Arduino names OneWire, FastLED and ESP32Servo as libraries that do not support the pin numbers printed on the board and need the GPIO number.

Suppose a sketch in the default mode passes D6 to one of these libraries. D6 equals 6 in that mode, the library sends 6 to the chip as a GPIO number, and the signal appears on GPIO6, which is the pin labelled D3.

Arduino's answer is to select By GPIO number (legacy) whenever a sketch uses third-party ESP32 libraries. Keep the labels in your code after the switch. In legacy mode D6 equals 9, so the Arduino functions and the library both reach GPIO9, the pin labelled D6.

MicroPython follows the ESP32 convention as well. Its Pin() function takes GPIO numbers, so the LED on D13 is Pin(48), and Pin(11) addresses the pin labelled A4.

The same translation applies when you copy a sketch from a generic ESP32 tutorial. Its bare numbers are GPIO numbers, so either compile the sketch in legacy mode or replace each number with the label of the pin you wired. The table below summarizes all four situations.

Situation

What to write

Arduino functions such as digitalWrite() and analogRead()

D and A labels, in either mode

Third-party ESP32 library

Select By GPIO number (legacy) and keep the labels

MicroPython

GPIO numbers from the map above

Sketch copied from a generic ESP32 tutorial

Compile in legacy mode, or replace each number with a label

Pins That Share a Function

Numbering is the main trap on this board. A few pins add smaller ones, because each of them does two jobs:

  • D13 carries the onboard LED (LED_BUILTIN) and the SPI clock, so the LED flickers during SPI transfers.

  • D0 and D1 are the header UART. In a sketch they belong to Serial0, while Serial is the USB port.

  • A4 and A5 are the default I2C pins. A second bus on Wire1 can use any free pair of pins, for example Wire1.begin(D4, D5).

  • A4 to A7 use ADC2, which Wi-Fi also uses, so readings on these pins can fail while Wi-Fi runs. A0 to A3 use ADC1 and are the analog inputs to choose in a Wi-Fi project.

  • The RGB LED is active-low. Writing LOW to LED_RED, LED_GREEN or LED_BLUE turns that color on. On some boards from the first production batch, the green and blue pins are swapped.

  • Every D and A pin supports analogWrite(), but the board can generate only five PWM signals at the same time.

Troubleshooting

The table below maps each symptom from this guide to its cause and fix.

Symptom

Cause

Fix

A different pin switches than the one you wired

The sketch uses a bare number in the other numbering mode

Replace the number with the D or A label

A third-party ESP32 library has no effect on its pin

The library treats the pin number as a GPIO number

Select Tools > Pin Numbering > By GPIO number (legacy) and upload again

No data on D0 and D1

The sketch uses Serial, which is the USB port

Use Serial0

Analog readings fail after Wi-Fi connects

The pin is on ADC2 (A4 to A7)

Move the signal to A0, A1, A2 or A3

An RGB LED color lights when you write HIGH to turn it off

The RGB LED is active-low

Write LOW to turn a color on and HIGH to turn it off

Green and blue are swapped on the RGB LED

Some first-batch boards carry a different RGB LED

See Arduino's Help Center article

Conclusion

The Arduino Nano ESP32 has two numbering schemes, and the labels printed on the board work in both. Write D2 and A0 in place of bare numbers, switch to By GPIO number (legacy) when a sketch uses a third-party ESP32 library, and use the GPIO column of the map for MicroPython. For pin positions and the complete function list, see the Arduino Nano ESP32 pinout page.

Sources