kukucaicndy/embedded_ai_skills/esp32-dev-arduino

ESP32 Development with Arduino CLI

Platform Support

Overview

Arduino CLI is a single Go binary — no IDE, no Java. Completely independent from ESP-IDF.

Environment Setup

Step 1: Install arduino-cli

Check if already installed:

arduino-cli version

If not found:

Windows:

winget install --id=ArduinoSA.CLI -e
# Or download: https://downloads.arduino.cc/arduino-cli/arduino-cli_latest_Windows_64bit.zip

Linux:

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh
# Binary installs to ~/bin/arduino-cli, add to PATH

macOS:

brew install arduino-cli

Step 2: Configure ESP32 Support (All Platforms)

arduino-cli config init
arduino-cli config set board_manager.additional_urls "https://espressif.github.io/arduino-esp32/package_esp32_index.json"
arduino-cli core update-index

Step 3: Install ESP32 Core (~500MB)

arduino-cli config set network.connection_timeout 600s
arduino-cli core install esp32:esp32

Downloads: platform core, xtensa/riscv GDB, esptool, openocd, mkspiffs, mklittlefs.

Step 4: Verify

arduino-cli board listall | grep esp32

Chip Selection (FQBN)

FQBN = Fully Qualified Board Name. Format: esp32:<family>:<board>

Before Creating a Project

Ask the user to:

1. Connect ESP32 to computer via USB
2. Ensure the board is powered on
3. Find the port:

• Windows: Device Manager → COMx
• Linux: ls /dev/ttyUSB*
• macOS: ls /dev/cu.usbserial*

1. Auto-detect:

``bash arduino-cli board list ``

Project Lifecycle

Create a Sketch

// sketch.ino
#include <Arduino.h>
 
void setup() {
    Serial.begin(115200);
    pinMode(LED_BUILTIN, OUTPUT);
    Serial.println("Hello ESP32 Arduino!");
}
 
void loop() {
    digitalWrite(LED_BUILTIN, !digitalRead(LED_BUILTIN));
    delay(500);
}

Compile

arduino-cli compile --fqbn esp32:esp32:esp32 <sketch_dir>

Upload

# Windows
arduino-cli upload -p COM3 --fqbn esp32:esp32:esp32 <sketch_dir>
 
# Linux
arduino-cli upload -p /dev/ttyUSB0 --fqbn esp32:esp32:esp32 <sketch_dir>
 
# macOS
arduino-cli upload -p /dev/cu.usbserial-1234 --fqbn esp32:esp32:esp32 <sketch_dir>

Serial Monitor

arduino-cli monitor -p <PORT> -c baudrate=115200   # Ctrl+C to exit

Library Management

Common ESP32 Libraries

Arduino vs ESP-IDF API

Mix Arduino + IDF APIs

extern "C" {
    #include "esp_wifi.h"
    #include "esp_sleep.h"
}

Platform-Specific Troubleshooting

Windows

• Board detection: Check Device Manager for COM port
• Upload fails: Hold BOOT + tap EN

Linux

• Serial permission: sudo usermod -a -G dialout $USER (re-login)
• Port busy: sudo chmod 666 /dev/ttyUSB0

macOS

• CP210x/CH340 may need driver: https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers
• Port format: /dev/cu.usbserial-*

All Platforms

• Core download timeout: arduino-cli config set network.connection_timeout 600s
• "Servo.h not found": Use ESP32Servo, not Servo

Full CLI Reference