Your first ESP32 program

🔌 1. What is the ESP32?

The ESP32 is a tiny but powerful microcontroller — think of it as a small brain that can control electronic things! It was made by a company called Espressif Systems.

Key Facts

Unlike your big computer, the ESP32 is made to do one job really well — read sensors, blink lights, control motors, and talk to the internet!

Feature	Details
Processor	Dual-core, up to 240 MHz (super fast for its size!)
Wi-Fi	Built-in! Can connect to the internet
Bluetooth	Built-in! Can talk to your phone
GPIO Pins	Up to 34 pins you can program
Built-in Sensors	Touch sensors, Hall effect sensor, Temperature sensor
Memory	520 KB RAM + 4 MB Flash
Power	3.3V (can be powered by USB!)

Fun Fact

The ESP32 costs about $3–$8 — cheaper than a sandwich! Yet it has Wi-Fi, Bluetooth, and dozens of sensors packed inside. Thousands of smart home devices use it!

🗺️ 2. Context Diagram — The Big Picture

A context diagram shows how the ESP32 talks to the outside world. It's like a map of who's connected to whom!

ESP32 System Context Diagram

Think About It

The ESP32 sits in the center of everything. It reads data from sensors and buttons (inputs), processes the information using your code, and sends commands to LEDs and motors (outputs). It can also talk wirelessly via Wi-Fi and Bluetooth!

📌 3. Understanding GPIO Pins

GPIO stands for General Purpose Input/Output. These are the metal pins on the ESP32 board that connect to the outside world — like the hands of the microcontroller!

What Can GPIO Do?

⬇️ Digital INPUT
Read ON (1) or OFF (0). Example: Is the button pressed?

⬆️ Digital OUTPUT
Send ON (1) or OFF (0). Example: Turn LED on!

📊 Analog INPUT (ADC)
Read values 0–4095. Example: How bright is the light?

📈 Analog OUTPUT (DAC/PWM)
Send varying signals. Example: Dim an LED slowly.

GPIO Pin Map — ESP32 DevKit

Common ESP32 Pin Functions

Important

Be careful! The ESP32 works at 3.3V, not 5V. Never connect a 5V signal directly to a GPIO pin — it can damage your board. Also, some pins (GPIO 6–11) are used internally for flash memory — don't use those!

GPIO Visual Model — Inputs & Outputs

🌡️ Sensor
INPUT

🔘 Button
INPUT

GPIO 34 ←

GPIO 15 ←

ESP32

Processes Data

→ GPIO 2

→ GPIO 5

💡 LED
OUTPUT

🔊 Buzzer
OUTPUT

🔍 4. Built-in Sensors

The ESP32 has sensors already built inside the chip — you don't need to connect any extra hardware!

🖐️ Touch Sensors (Capacitive)

10 GPIO pins can detect when you touch them! Pins: GPIO 0, 2, 4, 12, 13, 14, 15, 27, 32, 33. They work by sensing the tiny electrical charge in your finger.

🧲 Hall Effect Sensor

Detects magnetic fields near the chip! Hold a magnet close to the ESP32 and it can tell — useful for detecting if a door is open or a wheel is turning.

🌡️ Internal Temperature Sensor

Measures the temperature of the chip itself (not the room). Useful for monitoring if the chip is getting too hot. Range: roughly -40°C to 125°C.

📊 ADC (Analog-to-Digital Converter)

Reads analog voltage on certain pins (0–3.3V) and converts it into a number (0–4095). This is how you read external sensors like light sensors, potentiometers, and more!

🛠️ 5. Setting Up Arduino IDE

Before we write code, we need to set up the Arduino IDE — the free software we use to write and upload programs to the ESP32.

Download Arduino IDE — Go to arduino.cc/en/software and download the free IDE for your computer (Windows, Mac, or Linux).

Add ESP32 Board Support — Open Arduino IDE → File → Preferences. In "Additional Board Manager URLs" paste:
https://dl.espressif.com/dl/package_esp32_index.json

Install ESP32 Package — Go to Tools → Board → Boards Manager. Search "ESP32" and click Install on "esp32 by Espressif Systems".

Select Your Board — Tools → Board → ESP32 Arduino → ESP32 Dev Module.

Select the Port — Connect ESP32 via USB. Go to Tools → Port and select the new COM port that appears.

Tip

If no port appears, you may need to install the CP2102 or CH340 USB driver — this depends on which USB chip your ESP32 board uses. Ask your instructor!

✨ 6. Your First Program — Blink!

Every maker's first program is Blink — making an LED turn on and off! The ESP32 has a built-in LED on GPIO 2.

The Program Flow

Start

→

setup() runs once

→

LED ON

→

Wait 1 sec

→

LED OFF

→

Wait 1 sec

→

🔁 Repeat forever

The Code

    C++ / Arduino
// =============================================
// Alin Li ESP32 Explorer — Blink Program
// Your FIRST program! Makes the LED blink.
// =============================================

// Step 1: Define which pin the LED is on
#define LED_PIN 2   // Built-in LED is on GPIO 2

// Step 2: setup() runs ONCE when the board starts
void setup() {
  pinMode(LED_PIN, OUTPUT);  // Tell ESP32: "GPIO 2 is an OUTPUT"
  Serial.begin(115200);      // Start talking to computer (for messages)
  Serial.println("Blink program started!");
}

// Step 3: loop() runs FOREVER, over and over
void loop() {
  digitalWrite(LED_PIN, HIGH);  // Turn LED ON  (HIGH = 3.3V)
  Serial.println("LED is ON");
  delay(1000);                   // Wait 1000ms (1 second)

  digitalWrite(LED_PIN, LOW);   // Turn LED OFF (LOW = 0V)
  Serial.println("LED is OFF");
  delay(1000);                   // Wait 1 second again
}
  

Code Breakdown

Line	What It Does	In Simple Words
`#define LED_PIN 2`	Creates a name for pin number	"Let's call GPIO 2 'LED_PIN'"
`pinMode(LED_PIN, OUTPUT)`	Sets pin as output	"Hey ESP32, this pin will SEND signals"
`Serial.begin(115200)`	Starts serial communication	"Let's talk to the computer at this speed"
`digitalWrite(LED_PIN, HIGH)`	Sends 3.3V to pin	"Send power! Turn ON!"
`digitalWrite(LED_PIN, LOW)`	Sends 0V to pin	"Stop power! Turn OFF!"
`delay(1000)`	Waits 1000 milliseconds	"Wait for 1 second"

Upload Tip

Click the → Upload button in Arduino IDE. Some ESP32 boards need you to hold the BOOT button while uploading. Release it when you see "Connecting..." in the console.

📋 7. Sequence Diagram — What Happens Step by Step

A sequence diagram shows the order of events — who does what and when. Let's see what happens when the Blink program runs!

Blink Program — Sequence Diagram

🖐️ 8. Project: Touch Sensor

Let's use the ESP32's built-in capacitive touch sensor! No extra parts needed — just touch a wire connected to a touch-capable pin.

How It Works

Finger touches wire

→

Touch value drops

→

ESP32 reads value

→

If < threshold → LED ON!

    Touch Sensor
// =============================================
// Alin Li ESP32 Explorer — Touch Sensor
// Touch GPIO 4 to turn on the LED!
// =============================================

#define LED_PIN    2     // Built-in LED
#define TOUCH_PIN  4     // Touch-capable pin (T0)
#define THRESHOLD  40    // Touch sensitivity (lower = more sensitive)

void setup() {
  pinMode(LED_PIN, OUTPUT);
  Serial.begin(115200);
  Serial.println("Touch sensor ready! Touch GPIO 4...");
}

void loop() {
  int touchValue = touchRead(TOUCH_PIN);  // Read touch value
  Serial.print("Touch value: ");
  Serial.println(touchValue);

  if (touchValue < THRESHOLD) {
    digitalWrite(LED_PIN, HIGH);  // Touched! LED ON
    Serial.println("*** TOUCHED! ***");
  } else {
    digitalWrite(LED_PIN, LOW);   // Not touched. LED OFF
  }
  delay(100);  // Small delay to avoid flooding serial
}
  

How Touch Sensing Works

Your body has a tiny electrical charge. When you touch the wire, the capacitance changes. The ESP32 measures this change — when untouched, values are high (~50–80). When touched, they drop (~10–20). The THRESHOLD of 40 is the "decision line"!

🧲 9. Project: Hall Effect Sensor

The Hall sensor is built into the ESP32 chip. It detects magnetic fields — bring a magnet close and watch the values change!

    Hall Sensor
// =============================================
// Alin Li ESP32 Explorer — Hall Effect Sensor
// Detect magnets near the ESP32 chip!
// =============================================

#define LED_PIN        2
#define MAG_THRESHOLD  50  // Adjust based on your magnet

void setup() {
  pinMode(LED_PIN, OUTPUT);
  Serial.begin(115200);
  Serial.println("Hall sensor ready! Bring a magnet close...");
}

void loop() {
  int hallValue = hallRead();  // Read magnetic field
  Serial.print("Hall value: ");
  Serial.println(hallValue);

  // Magnet detected if value goes very high or very low
  if (abs(hallValue) > MAG_THRESHOLD) {
    digitalWrite(LED_PIN, HIGH);
    Serial.println("🧲 MAGNET DETECTED!");
  } else {
    digitalWrite(LED_PIN, LOW);
  }
  delay(200);
}
  

Try This!

Hold a refrigerator magnet near the metal can on the ESP32 (that's where the chip is). Try different sides of the magnet — North makes the value go positive, South makes it go negative!

🔘 10. Project: Button Input + LED Output

Now let's combine an external button (input) with the LED (output). Press the button → LED lights up!

Wiring Diagram

Button → ESP32 → LED Connection

    Button + LED
// =============================================
// Alin Li ESP32 Explorer — Button + LED
// Press button on GPIO 15 → LED on GPIO 2 lights up
// =============================================

#define LED_PIN    2
#define BUTTON_PIN 15

void setup() {
  pinMode(LED_PIN, OUTPUT);
  pinMode(BUTTON_PIN, INPUT_PULLUP); // Use internal pull-up resistor
  Serial.begin(115200);
  Serial.println("Button + LED ready!");
}

void loop() {
  int buttonState = digitalRead(BUTTON_PIN);

  // INPUT_PULLUP means: LOW when pressed, HIGH when released
  if (buttonState == LOW) {
    digitalWrite(LED_PIN, HIGH);
    Serial.println("Button PRESSED → LED ON");
  } else {
    digitalWrite(LED_PIN, LOW);
  }
  delay(50);  // Small delay for debouncing
}
  

What is INPUT_PULLUP?

The ESP32 has a built-in pull-up resistor inside. When you use INPUT_PULLUP, the pin reads HIGH (1) normally, and drops to LOW (0) when you press the button connecting it to GND. This means you don't need an extra resistor — the ESP32 has one inside!

💡 11. Tips & Best Practices

Tip #1 — Use Serial Monitor

Always add Serial.println() messages to your code! Open the Serial Monitor (Tools → Serial Monitor, set baud to 115200) to see what your ESP32 is doing. It's like giving your board a voice.

Tip #2 — Voltage Matters

ESP32 GPIO works at 3.3V. Never connect 5V directly. If you need to use 5V sensors, use a voltage divider or level shifter.

Tip #3 — Safe GPIO Pins

Best pins to use: GPIO 2, 4, 5, 12, 13, 14, 15, 16, 17, 18, 19, 21, 22, 23, 25, 26, 27, 32, 33. Avoid: GPIO 6–11 (flash memory), GPIO 34–39 (input-only, no pull-up).

Tip #4 — Save Your Work

Always save your code with a clear name like blink_test_v1.ino. Make a new version each time you make big changes so you can go back!

Tip #5 — Read the Errors

If uploading fails, read the orange/red text in the Arduino console! Common fixes: check USB cable, select correct board, hold BOOT button, or try a different USB port.

Tip #6 — The Power of delay()

delay(ms) pauses everything. For simple projects it's fine, but for advanced projects, learn about millis() which lets you time things without freezing your code!

🏆 12. Challenges for You!

Ready to test your skills? Try these challenges and level up!

⭐ Challenge 1 — Speed Blink

Modify the Blink program to blink 5 times fast (100ms each), then pause for 2 seconds, then repeat. Hint: use a for loop!

⭐⭐ Challenge 2 — Touch Brightness

Use the touch sensor to control LED brightness. Softer touch = dimmer, harder touch = brighter. Hint: use analogWrite() or ledcWrite() with PWM!

⭐⭐ Challenge 3 — Magnet Counter

Count how many times a magnet passes by the Hall sensor and display the count on Serial Monitor. Can you make it count only once per pass?

⭐⭐⭐ Challenge 4 — Secret Knock

Use the touch sensor to create a "secret knock" pattern. The LED only turns on if you tap the wire in the right pattern (e.g., tap-tap-pause-tap). Think about timing!

⭐⭐⭐ Challenge 5 — Multi-Sensor Dashboard

Read ALL sensors (touch, hall, and a button) at once, and print a formatted dashboard to the Serial Monitor that updates every second. Make it look nice with labels and separators!

📝 Quick Reference Card

Function	What It Does	Example
`pinMode(pin, mode)`	Set pin as INPUT or OUTPUT	`pinMode(2, OUTPUT);`
`digitalWrite(pin, val)`	Set pin HIGH (on) or LOW (off)	`digitalWrite(2, HIGH);`
`digitalRead(pin)`	Read HIGH or LOW from pin	`int v = digitalRead(15);`
`analogRead(pin)`	Read analog value (0–4095)	`int v = analogRead(34);`
`touchRead(pin)`	Read touch sensor value	`int v = touchRead(4);`
`hallRead()`	Read Hall sensor value	`int v = hallRead();`
`delay(ms)`	Pause for milliseconds	`delay(1000);` = 1 sec
`Serial.begin(baud)`	Start serial communication	`Serial.begin(115200);`
`Serial.println(text)`	Print text + new line	`Serial.println("Hi!");`