ESP32 Bench Reference

The DevKit V1, the MIN132 and the Freenove boards all carry the same ESP32-WROOM-32 silicon. The -32E on the Freenove is a later module revision — smaller package options, updated eFuse defaults — not a different part from the programmer's side.

Practical effect: one binary, one board target, one pin map covers 8 of the 12 boards. The remaining four are the two C3 Super Minis and the two Heltecs, and those are where the divergences in §02 apply.

These hold across all 12 boards and are the reason a single sheet works:

Rather than remembering the table, let the preprocessor refuse to build the wrong thing:

// arduino-esp32 defines exactly one of these
#if defined(CONFIG_IDF_TARGET_ESP32)
  #include <BluetoothSerial.h>   // classic BT: this family only
  #define HAS_DAC   1
#elif defined(CONFIG_IDF_TARGET_ESP32C3)
  #define HAS_DAC   0
  #define SINGLE_CORE 1
#elif defined(CONFIG_IDF_TARGET_ESP32S3)
  #define HAS_DAC   0
#else
  #error "Unhandled ESP32 target"
#endif

The #error is the useful half — it turns "wrong board selected" from a runtime mystery into a build failure on the line that says so.

GPIO11–17 are the SPI flash and are not brought out. GPIO18/19 are the native USB D−/D+ and are also not on the header.

Most of this board's pins are already wired to something. These are the assignments you need before any free GPIO matters:

# once
arduino-cli config init
arduino-cli config add board_manager.additional_urls \
  https://espressif.github.io/arduino-esp32/package_esp32_index.json
arduino-cli core update-index
arduino-cli core install esp32:esp32

# per project
arduino-cli board list                    # find the port
arduino-cli compile -b esp32:esp32:esp32doit-devkit-v1 .
arduino-cli upload  -b esp32:esp32:esp32doit-devkit-v1 -p /dev/cu.usbserial-0001 .
arduino-cli monitor -p /dev/cu.usbserial-0001 -c baudrate=115200

Build options that are menu items in the IDE become --build-property or a :-suffixed FQBN, e.g. esp32:esp32:esp32c3:CDCOnBoot=cdc.

[env]
platform = espressif32
framework = arduino
monitor_speed = 115200
build_flags = -DCORE_DEBUG_LEVEL=3

[env:devkit]
board = esp32doit-devkit-v1

[env:c3]
board = esp32-c3-devkitm-1
build_flags = ${env.build_flags}
  -DARDUINO_USB_MODE=1
  -DARDUINO_USB_CDC_ON_BOOT=1

[env:heltec]
board = heltec_wifi_lora_32_V3
lib_deps = jgromes/RadioLib

One [env] per board, one shared src/. pio run -e c3 -t upload builds and flashes just that target — the cleanest way to keep a sketch honest across all three families.

. $HOME/esp/esp-idf/export.sh
idf.py set-target esp32c3       # esp32 | esp32c3 | esp32s3
idf.py menuconfig
idf.py build
idf.py -p /dev/cu.usbmodem101 flash monitor

The Arduino core is a component on top of IDF — anything in this sheet's IDF column is callable from an Arduino sketch by including the right header.

# flash the interpreter
esptool.py --chip esp32 -p PORT erase_flash
esptool.py --chip esp32 -p PORT -b 460800 \
  write_flash 0x1000 ESP32_GENERIC-20250415.bin

# C3 and S3 load at 0x0, not 0x1000
esptool.py --chip esp32c3 -p PORT write_flash 0x0 ESP32_GENERIC_C3-*.bin

Different firmware binary per family, same language. Handy on the C3, where the native USB means the REPL appears the instant the board enumerates.

# identify before you write
esptool.py --port PORT chip_id
esptool.py --port PORT flash_id     # size + manufacturer

# wipe (also clears NVS and any filesystem)
esptool.py --chip esp32 --port PORT erase_flash

# bootloader offset differs by family
#   esp32    -> 0x1000
#   esp32c3  -> 0x0
#   esp32s3  -> 0x0
esptool.py --chip esp32 --port PORT -b 460800 write_flash \
  0x1000 bootloader.bin 0x8000 partitions.bin 0x10000 firmware.bin

# pull an image off a board before overwriting it
esptool.py --port PORT read_flash 0 0x400000 backup.bin

Replacing a DAC portably: LEDC at a few hundred kHz into a 1 kΩ / 1 µF RC gives a clean slow analog voltage. For audio, an external I²S DAC is the right answer on every family including the ESP32.

#include <Wire.h>
Wire.begin(SDA_PIN, SCL_PIN);      // always name them
Wire.setClock(400000);           // 100k std, 400k fast

Wire.beginTransmission(0x27);
Wire.write(0x00);
uint8_t err = Wire.endTransmission();  // 0 = ACKed

Pull-ups: 4.7 kΩ to 3.3 V. Most breakout modules fit their own; three modules on one bus means three sets of pull-ups in parallel, which is often too strong.

// scanner — the first thing to run on any new bus
for (uint8_t a = 1; a < 127; a++) {
  Wire.beginTransmission(a);
  if (Wire.endTransmission() == 0) Serial.printf("0x%02X\n", a);
}

#include <SPI.h>
SPI.begin(SCK, MISO, MOSI, SS);
SPI.beginTransaction(SPISettings(10000000, MSBFIRST, SPI_MODE0));
digitalWrite(SS, LOW);
SPI.transfer(0x9F);
digitalWrite(SS, HIGH);
SPI.endTransaction();

Serial.begin(115200);              // console
Serial1.begin(9600, SERIAL_8N1, RX, TX);

// any pins, thanks to the GPIO matrix
Serial2.begin(115200, SERIAL_8N1, 16, 17);

WiFi.mode(WIFI_AP);
WiFi.softAP("esp32-setup", "12345678");
Serial.println(WiFi.softAPIP());   // 192.168.4.1

// both at once, for a config portal
WiFi.mode(WIFI_AP_STA);

#include <HTTPClient.h>
HTTPClient http;
http.begin("http://example.com/api");
int code = http.GET();
if (code == 200) Serial.println(http.getString());
http.end();

#include <ESPmDNS.h>
MDNS.begin("sensor1");        // -> sensor1.local
MDNS.addService("http", "tcp", 80);

configTime(0, 0, "pool.ntp.org");
setenv("TZ", "EST5EDT,M3.2.0,M11.1.0", 1); tzset();

#include <NimBLEDevice.h>

NimBLEDevice::init("esp32-node");
NimBLEServer *s   = NimBLEDevice::createServer();
NimBLEService *sv = s->createService("180F");   // battery
NimBLECharacteristic *c = sv->createCharacteristic(
    "2A19", NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::NOTIFY);
sv->start();
s->getAdvertising()->start();
c->setValue(pct); c->notify();

#include <Preferences.h>
Preferences prefs;

prefs.begin("net", false);          // namespace, read-write
prefs.putString("ssid", ssid);
prefs.putUInt("boots", prefs.getUInt("boots", 0) + 1);
String s = prefs.getString("ssid", "");   // default if unset
prefs.end();

#include <LittleFS.h>
LittleFS.begin(true);              // true = format if unmountable

File f = LittleFS.open("/log.txt", FILE_APPEND);
f.printf("%lu,%.2f\n", millis(), temp);
f.close();

File d = LittleFS.open("/");
while (File e = d.openNextFile()) Serial.println(e.name());

#include <esp_sleep.h>
RTC_DATA_ATTR int wakeCount = 0;

esp_sleep_enable_timer_wakeup(60ULL * 1000000);  // 60 s
esp_deep_sleep_start();               // never returns

void sensorTask(void *arg) {
  for (;;) {
    readSensor();
    vTaskDelay(pdMS_TO_TICKS(1000));   // yields
  }
}

// portable: let the scheduler choose
xTaskCreate(sensorTask, "sensor", 4096, nullptr, 1, nullptr);

// dual-core only (ESP32, S3) — not the C3
xTaskCreatePinnedToCore(sensorTask, "sensor", 4096,
                        nullptr, 1, nullptr, 0);

#include <RadioLib.h>
// NSS, DIO1, RST, BUSY
SX1262 radio = new Module(8, 14, 12, 13);

SPI.begin(9, 11, 10);      // SCK, MISO, MOSI
int st = radio.begin(
    905.2,   // MHz — must match your band
    125.0,   // bandwidth kHz
    9,       // spreading factor 5..12
    7,       // coding rate 4/7
    0x34,    // sync word
    14);     // TX power dBm
if (st != RADIOLIB_ERR_NONE) Serial.println(st);

radio.transmit("hello");
String in; radio.receive(in);

// 1. power the Vext rail (ACTIVE LOW)
pinMode(36, OUTPUT); digitalWrite(36, LOW);
delay(50);

// 2. reset the panel
pinMode(21, OUTPUT);
digitalWrite(21, LOW);  delay(20);
digitalWrite(21, HIGH);

// 3. its own I2C bus, separate from anything you add
Wire1.begin(17, 18);

SSD1306, 128×64, address 0x3C. Skipping step 1 gives a display that never responds and an I²C scan that finds nothing — indistinguishable from a dead panel.

#include <esp_log.h>
static const char* TAG = "sensor";

ESP_LOGE(TAG, "error %d", err);   // error
ESP_LOGW(TAG, "warn");            // warning
ESP_LOGI(TAG, "temp=%.2f", t);    // info
ESP_LOGD(TAG, "debug");           // debug

esp_log_level_set("wifi", ESP_LOG_WARN);  // quieten one tag