Why your Arduino sketches keep failing (and how an AI mentor fixes it)
Every maker knows the loop: you buy an ESP32, wire up a sensor, copy a sketch from a forum, hit Upload — and get 40 lines of red compiler errors. The gap between "I want a smart home" and "my code compiles" is where most projects die. The Arduino IDE's own error messages are notoriously terse, and forum answers are often written for a different board revision than yours.
This is exactly where a large language model earns its keep. Not as a magic code generator, but as a debugging partner that knows the ESP32's esp_sleep API, remembers that the DHT22 needs a 10k pull-up resistor, and can explain why analogWrite() doesn't exist on GPIO 34. Below are 10 prompts I use regularly — each with a real task, a copy-paste example, and notes on what to verify yourself.
A caveat before we start: an LLM will confidently invent pin numbers and library names. Always cross-check against official sources — the Arduino Language Reference, Espressif's ESP-IDF docs, and the PlatformIO registry are your ground truth. Treat the AI as a fast junior engineer, not an oracle.
1. The "Explain the error, don't just fix it" prompt
Task: You pasted a compile error and want to understand its root cause, not just a patch.
Prompt:
I'm compiling for ESP32 (Arduino core 3.x) in PlatformIO. Here's the error:
<PASTE FULL ERROR OUTPUT>
Here's the relevant code:
<PASTE CODE>
1. Explain in plain terms what the compiler is complaining about.
2. Identify if this is a syntax, include, or type issue.
3. Give the minimal fix, and tell me which official doc page describes this API.
4. If the error is version-specific, say which core version introduced the change.
Example: A classic error: 'ledcSetup' was not declared in this scope usually means you're on Arduino-ESP32 core 3.x, where the LEDC API was reworked. The prompt forces the model to name the version instead of guessing.
Verify: Check the arduino-esp32 releases for breaking changes.
2. Component selection with real electrical constraints
Task: Pick parts that actually work together — voltage, current, and logic levels included.
Prompt:
I want to build a battery-powered soil moisture sensor that reports over Wi-Fi.
Constraints: 3.7V LiPo, must run 3+ months on 2000mAh, ESP32 or ESP8266.
List: sensor options (capacitive only), voltage regulator, and a wake strategy.
For each part give the real quiescent current figure and a source.
Flag anything where you're unsure — don't invent datasheet numbers.
Why it works: The "flag uncertainty" instruction is critical. Without it, models fabricate microamp figures. A capacitive sensor like the DFRobot SEN0193 avoids the corrosion problem of resistive probes — a real failure mode in outdoor builds.
3. Power budget calculator
Task: Stop guessing why your project dies in two days.
Prompt:
Build a power budget table for this ESP32 project:
- Deep sleep current: <VALUE> mA (from datasheet)
- Active Wi-Fi TX peak: <VALUE> mA
- Awake duration per report: <VALUE> s
- Report interval: <VALUE> min
- Battery: <VALUE> mAh, 80% usable
Output a Markdown table with columns: State
| Current (mA) | Duration | mAh per cycle.
Then compute days of runtime. Show the formula.
Reality check: ESP32 deep sleep is typically ~10 µA on a bare module but jumps to several mA with an onboard LDO and USB-serial chip. If the AI quotes 10 µA, ask it to include board-level overhead. This is the single most common reason hobby IoT devices underperform their estimates.
4. MQTT integration with Home Assistant discovery
Task: Get your sensor auto-appearing in Home Assistant without YAML editing.
Prompt:
Write an Arduino sketch for ESP32 that publishes temperature to MQTT
and uses Home Assistant MQTT Discovery.
Requirements:
- Use PubSubClient
- Discovery topic: homeassistant/sensor/<node>/<object>/config
- Include a unique_id, state_topic, device block with identifiers
- Retain the discovery message, do NOT retain state
- Reconnect logic with backoff
Reference the HA MQTT discovery schema (2024+ format).
Key detail: The device block groups entities under one device in HA — this is the official discovery format. Retaining state messages is a common bug; it makes HA show stale values after a reboot.
5. Telegram bot on ESP32 (with the real gotcha)
Task: Push alerts to your phone without a cloud broker.
Prompt:
ESP32 sketch: read a PIR sensor, send a Telegram message on motion.
Use the Telegram Bot API sendMessage endpoint over HTTPS.
Use WiFiClientSecure with setInsecure() for testing, and explain
how to pin the root CA for production.
Do not hardcode the bot token — show a config.h approach.
Gotcha: WiFiClientSecure with setInsecure() skips certificate validation — fine for a weekend prototype, unacceptable for anything exposed. For production, embed the Telegram root CA and use setCACert(). The Telegram API docs live at core.telegram.org/bots/api.
6. The "debug my wiring" prompt
Task: When the code is fine but nothing happens.
Prompt:
My ESP32 reads a constant 0 from an analog sensor on GPIO 34.
Wiring: sensor VCC -> 3.3V, GND -> GND, OUT -> GPIO 34.
Sensor is a 0-3.3V analog output.
List the 5 most likely causes in order of probability,
with a specific test for each. Include ADC attenuation settings.
Why: GPIO 34–39 on the ESP32 are input-only and have no internal pull-ups — a fact that trips up nearly every beginner. The ESP32 ADC documentation explains attenuation and the non-linear region near 0V and 3.3V.
7. OTA updates so you stop unplugging the board
Task: Update firmware over Wi-Fi once the device is mounted on a wall.
Prompt:
Add ArduinoOTA to an existing ESP32 sketch.
Show: hostname, password protection, and a callback for progress.
Explain what happens if power fails mid-update.
Mention the minimum partition scheme needed (two app partitions).
Fact to know: OTA requires a partition table with two OTA app slots — the default "Default 4MB with spiffs" often doesn't fit. See the OTA update docs.
8. Sensor fusion and calibration
Task: Turn raw readings into trustworthy numbers.
Prompt:
I have raw ADC values from a soil moisture sensor: dry air = <VALUE>, in water = <VALUE>.
Write a function that maps raw to 0-100% with clamping.
Add a moving average filter (window 5) and explain why median
may be better than mean for sensor spikes.
Note: Calibrate per-sensor — capacitive probes vary batch to batch. Median filtering rejects the occasional wild ADC read caused by Wi-Fi transmission noise, which a mean filter would smear into your data.
9. Code review prompt
Task: Catch blocking calls and memory leaks before they bite.
Prompt:
Review this ESP32 sketch for embedded best practices:
<PASTE CODE>
Check for: blocking delay() in the main loop, String usage that
fragments heap, missing yield()/vTaskDelay, uninitialized pins,
and watchdog risks. Suggest fixes with minimal diffs.
Why it matters: String concatenation in a loop fragments the ESP32's heap — a well-documented cause of crashes after hours of uptime. Prefer char buffers or snprintf. This is standard embedded hygiene, not AI magic.
10. From prototype to enclosure and PCB
Task: The last mile — making it a finished object.
Prompt:
I have a working ESP32 weather station (BME280 + OLED + LiPo).
Suggest: an enclosure approach (3D-printed, IP-rated options),
a minimal PCB layout for the sensor breakout, and
which connectors to use for field-replaceable sensors.
Give reasoning, not just part names.
Practical tip: For outdoor builds, use JST-SH or waterproof M8 connectors rather than soldered wires — you will replace the sensor at some point. The BME280 datasheet from Bosch Sensortec documents its I²C address options (0x76/0x77), which matters when you stack multiple sensors.
The habit that separates finished projects from dead breadboards
The prompts above share one pattern: they ask the AI to explain, cite, and flag uncertainty rather than just emit code. That single shift turns a hallucination-prone chatbot into a reliable engineering assistant. When an answer includes a datasheet figure, open the datasheet. When it names a library, check the registry. When it quotes a current draw, sanity-check against the module you actually own.
Tools like ASI Biont's AI-guided learning approach apply the same principle — pairing generated explanations with verifiable references, so you build real understanding instead of copy-pasting sketches you can't debug. Start with prompt #1 on your next broken build. The red error lines are not a wall; they're a conversation waiting to happen.
Comments