Ota Deployment Guardian

OTA Deployment Guardian

Use this skill when a device is updated remotely and losing the update path would be expensive.

Resources

• references/ota-safe-sketch.md - minimum sketch-side OTA contract and guardrails
• references/discovery-and-network-ports.md - IDE, mDNS, IP reachability, and disappearing network port triage
• references/recovery-and-rollback.md - rollout safety, rollback, and last-resort recovery planning
• ../../docs/board-support/uno-r4-family.md - Uno R4 Minima and Uno R4 WiFi board-family caveats

When to Use

Use this skill when the request involves:

• OTA uploads for ESP32, Nano ESP32, or Uno R4 WiFi
• network port appears briefly or disappears
• IDE can ping the device but cannot upload
• keeping a remote weather station or deployed board updateable
• avoiding self-bricking after an OTA deployment

Do not use this skill for ordinary bench USB uploads unless the user is clearly preparing for later OTA deployment.

Workflow

1. Confirm the board family:

• ESP32 or Nano ESP32 -> open references/ota-safe-sketch.md
• Uno R4 WiFi -> also open ../../docs/board-support/uno-r4-family.md

2. Separate discovery failures from sketch failures:

• ping works but network port disappears -> open

references/discovery-and-network-ports.md

• OTA works once, then disappears after the new sketch runs -> verify the new

sketch still implements the OTA path in ota-safe-sketch.md 3. Before suggesting a rollout, check references/recovery-and-rollback.md for recovery path, rollback strategy, and what must stay available over USB. 4. Treat core-version changes as a possible variable when OTA previously worked and later became unreliable.

Core Rules

• Never assume OTA remains available after a new sketch unless the sketch keeps

the OTA path alive.

• Distinguish reachability from OTA discovery. Ping success does not prove the

IDE can discover or upload.

• Keep at least one recovery path in reserve for high-cost remote devices.
• For Uno R4 WiFi, keep board-family caveats explicit. Its WiFi side is not the

same operational model as a plain ESP32 board.

Verification

• Confirm the sketch still connects to the intended network and services the OTA

path after boot.

• Confirm whether the failure is discovery-only, upload-only, or full device

reachability loss.

• For remote deployments, confirm the rollback or physical recovery plan before

recommending an update.

• If board or core versions changed recently, capture the exact versions before

concluding the failure is in user code.

Integration

• Pair with arduino-cli-skill when the user needs command-line upload or port

inspection.

• Pair with field-power-and-connectivity-triager when the OTA path fails only

off USB or in field power conditions.

• Pair with error-message-explainer when the OTA sketch itself does not build.

Discovery And Network Port Triage

Use this reference when the board is reachable on the network but the IDE or tooling cannot keep the OTA target visible.

Common Failure Shapes

Ping works, network port disappears

Likely causes:

• mDNS or network-port discovery instability
• IDE-side discovery issue
• board core or tool-version regression

Next checks:

• confirm the device remains reachable by IP
• confirm whether the failure is only discovery, not application reachability
• test a direct-IP or non-discovery-dependent workflow if available

OTA works once, then vanishes after reboot

Likely cause:

• the uploaded sketch did not preserve OTA support or network initialization

Next checks:

• re-read ota-safe-sketch.md
• compare the working OTA sketch against the newly uploaded one

Port appears only briefly after boot

Likely causes:

• startup timing issue
• board-family-specific OTA caveat
• toolchain or board package change

Next checks:

• capture exact board and tool versions
• on Uno R4 WiFi, open ../../docs/board-support/uno-r4-family.md

Notes For ESP32-Class Boards

• mDNS instability can look like a device failure even when the application is

still running and reachable

• if a previous machine still discovers the device while a recently updated one

does not, treat tool or core drift as a first-class suspect

Notes For Uno R4 WiFi

• built-in IDE "network" port OTA is not an officially supported path in the

same way it is on some ESP32 workflows

• third-party OTA flows can work, but they have extra constraints and timing

sensitivity

OTA-Safe Sketch Contract

Use this reference when the question is whether the uploaded sketch itself can continue to accept OTA updates.

Minimum Contract

The updated sketch must continue to:

• initialize the intended network path
• initialize OTA support
• keep servicing OTA in the main runtime path
• avoid blocking the event path for long periods

If the old sketch supported OTA but the new sketch does not, OTA may work once and then disappear after reboot. Treat that as expected behavior, not as a mystery transport bug.

Guardrails

• keep credentials and network mode explicit
• verify the board actually joins the network before assuming OTA is available
• avoid long blocking sections early in boot that starve network startup
• avoid assuming example code for one board family is correct for another

Evidence To Collect

• does the device still get an IP address after the new sketch boots?
• does the device respond over the expected network path?
• is OTA service initialized in the new sketch?
• is OTA handling still exercised regularly enough to remain usable?

High-Risk Cases

• updating a deployed device without recent USB recovery access
• changing Wi-Fi credentials, network mode, or boot flow in the same rollout
• switching board core versions at the same time as sketch behavior changes
• trying Uno R4 WiFi OTA without checking board-family-specific caveats

Recovery And Rollback Planning

Use this reference before recommending OTA for a device whose physical access is limited.

Pre-Deployment Questions

• Is there still a practical USB or serial recovery path?
• Can the device be power-cycled safely if the update fails?
• Is the rollout changing networking, boot flow, or storage layout?
• Is there a known-good version to return to?

Recovery Principles

• do not spend the only recovery path in the same rollout that changes network

behavior

• prefer one variable at a time for remote updates
• capture exact board core, library, and tooling versions when the old build is

known good

Rollback Checklist

• keep a known-good binary or sketch revision available
• preserve enough logging to distinguish boot failure from discovery failure
• avoid making the first remote rollout also the largest architectural change

Uno R4 WiFi Note

Uno R4 WiFi has additional connectivity-side complexity. Before treating it like a generic OTA board, review the shared board-family reference at ../../docs/board-support/uno-r4-family.md.