ArduinoOTA: upload a sketch over WiFi from the IDE
ArduinoOTA ships with the ESP32 and ESP8266 Arduino cores and lets the Arduino IDE or PlatformIO upload a new sketch over WiFi instead of USB. Once a sketch with OTA is running, the board announces itself on the local network through mDNS and shows up under Tools, Port as a network port, named after its host name. Pick it, press Upload, and the board flashes itself.
Built in on Mokxi: #include <ArduinoOTA.h> and it builds, with nothing to install. Free, and no account needed.
What ArduinoOTA (ESP cores) does
The pattern is short: connect WiFi, optionally set a host name and a password, attach callbacks for start, progress, end and error, call ArduinoOTA.begin(), and call ArduinoOTA.handle() on every pass of loop(). The callbacks are the place to stop motors or close files before the board restarts on its new firmware.
Every uploaded sketch must keep the OTA code, or the next update has to go over USB again. In Mokxi the library compiles and the example runs, but no update can arrive over the simulated network: begin() prints a line saying so and handle() does nothing. The callbacks never fire here; use Run to load a new build instead.
| Library Manager name | ArduinoOTA (ESP cores) |
|---|---|
| Author | Espressif, ESP8266 Community |
| Include | #include <ArduinoOTA.h> |
| Boards | ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi |
| In the simulator | Builds and runs, and says plainly that the hardware behind it is not simulated. |
Install it
It builds on ESP32-C3, ESP32-C6, Seeed XIAO ESP32-C3, ESP32-C3 SuperMini, Seeed XIAO ESP32-C6, ESP32 DevKit, ESP32-DevKitC V4, LOLIN32 Lite, Wemos D1 R32, Cheap Yellow Display, TTGO T-Display, ESP32-S3-DevKitC-1, Seeed XIAO ESP32-S3, Arduino Nano ESP32, ESP8266 NodeMCU, Raspberry Pi Pico W, Arduino Uno R4 WiFi.
In Mokxi it is built in: #include <ArduinoOTA.h> and the sketch compiles, with no download, no zip and no Library Manager.
On a real board, install "ArduinoOTA (ESP cores)" by Espressif, ESP8266 Community from the Arduino IDE’s Library Manager (Sketch, Include Library, Manage Libraries), or add ArduinoOTA (ESP cores) to lib_deps in PlatformIO. Mokxi follows the calls of release arduino-esp32 3.3.12, so a sketch written here builds there too.
What to know in the simulator: No update can arrive over the simulated network: begin() prints a line saying so and handle() does nothing.
The calls you will use
In the order a sketch meets them.
ArduinoOTA.setHostname("garage-door")
The name the board announces, which the IDE shows as the network port. Set it before begin().
ArduinoOTA.setPassword("secret")
Requires a password for each upload; the IDE asks for it. Without one, anyone on the network can replace your sketch.
ArduinoOTA.onStart(otaStart)
Registers a function run as an update begins. Switch outputs to a safe state here.
ArduinoOTA.onProgress(otaProgress)
Registers a function given bytes received and total size, for a percentage on Serial or a display.
ArduinoOTA.onProgress([](unsigned int done, unsigned int total) {
Serial.printf("%u%%\r", done * 100 / total);
});ArduinoOTA.onError(otaError)
Registers a function given an ota_error_t such as OTA_AUTH_ERROR or OTA_RECEIVE_ERROR when an update fails.
ArduinoOTA.begin()
Starts listening for uploads and the mDNS announcement. Call it after WiFi is connected.
ArduinoOTA.handle()
Checks for an incoming upload and runs it. Call it on every pass of loop(); a long delay() makes uploads time out.
Example: OTA in a web server sketch
On the ESP32-C3-DevKitM-1. It runs in the browser exactly as printed.
#include <WiFi.h>
#include <ArduinoOTA.h>
void setup() {
Serial.begin(115200);
WiFi.begin("Mokxi-Lab", "breadboard");
ArduinoOTA.setHostname("mokxi-board");
ArduinoOTA.onStart([]() { Serial.println("Start updating"); });
ArduinoOTA.onEnd([]() { Serial.println("End"); });
ArduinoOTA.onError([](ota_error_t error) { Serial.print("Error "); Serial.println((int)error); });
ArduinoOTA.begin();
Serial.println("Ready");
}
void loop() {
ArduinoOTA.handle();
}Common errors and how to fix them
No network port appears under Tools, Port
The IDE finds boards through mDNS, which needs the computer and the board on the same network and subnet, and a firewall that allows it. Check that begin() ran after WiFi connected, restart the IDE, and try a phone hotspot to rule out the router.
Error[2]: Connect Failed, or the upload stops partway
The board did not answer in time, usually because loop() blocks and handle() runs too rarely. Replace delay() calls with millis() timers, and allow the IDE through the computer’s firewall, since the board connects back to it.
OTA worked once, then the port vanished for good
The sketch that was uploaded had no ArduinoOTA code, so the board stopped listening. Upload once more over USB with OTA included, and keep the OTA block in every sketch you send over the air.
Questions and answers
Can I update a board that is not on my home network?
Not with ArduinoOTA, which works on the local network only. For boards elsewhere, have them download firmware from a server with HTTPUpdate, or use a cloud service built for it.
Try ArduinoOTA (ESP cores) without installing anything
Open the example, change the sketch, and keep your version in a free account.