24  ESP32 Wi-Fi Programming

Keywords

ESP32 Wi-Fi basics, ESP32 station mode evidence, ESP32 provisioning review, IoT Wi-Fi connection recovery, Wi-Fi implementation evidence

24.1 Start With the Wireless Story

ESP32 Wi-Fi work begins with a small state machine. The device must scan, join, receive events, recover from drops, expose a service, save power, and leave enough logs that a support team can tell whether firmware or the network failed.

24.2 In 60 Seconds

This chapter reviews the first usable ESP32 Wi-Fi implementation for an IoT device. The goal is not to paste a long sketch into a board and stop when the serial monitor says connected. The goal is to prove that the device joins the intended network profile, reaches the service it needs, handles common failure paths, protects credentials, and leaves a record that another reviewer can inspect.

Use this chapter when an ESP32-class device is moving from “Wi-Fi example works” to “this implementation is ready for a focused lab or pilot review.” Keep the claim bounded: this chapter can support an implementation decision, but it does not replace installed-site coverage, long-term power validation, or the deeper security review.

Phoebe’s Field Notes: The One Band ESP32 Has Is Also Its Best Diffraction Argument

Phoebe’s Why

A classic ESP32 only ever gives this chapter one band to review – 802.11 b/g/n on 2.4 GHz – and that single number, run through \(c=f\lambda\), decides more than antenna size. Wavelength also sets how well a wave bends around an obstruction instead of being blocked by it: a wave whose wavelength is comparable to an obstacle’s size diffracts around it efficiently, while a much shorter wavelength casts a sharper “radio shadow.” A doorframe, furniture edge, or a person walking through the link path is a partial obstruction, not a wall – and the same obstruction geometry costs more decibels at a shorter wavelength. That is a genuine, physical reason the “association and usable service” record this chapter asks for should note the band, not just treat 2.4 GHz as a fixed given.

The Derivation

Wavelength from the wave-speed relationship:

\[\lambda = \frac{c}{f}\]

Single knife-edge diffraction is governed by the Fresnel-Kirchhoff diffraction parameter \(\nu\), where \(h\) is the obstruction height above the direct line of sight and \(d_1\), \(d_2\) are the distances from transmitter and receiver to the obstruction:

\[\nu = h\sqrt{\frac{2(d_1+d_2)}{\lambda\,d_1 d_2}}\]

A standard single-edge diffraction-loss approximation (valid for \(\nu > -0.7\)):

\[L_d(\mathrm{dB}) = 6.9 + 20\log_{10}\!\left(\sqrt{(\nu-0.1)^2+1}+\nu-0.1\right)\]

Worked Numbers: One Obstruction, Two Candidate Bands

Same obstruction geometry both times – a 0.3 m partial blockage centered on a 6 m path (\(d_1=d_2=3\) m), such as a person or door edge crossing the link:

• 2.4 GHz (\(\lambda=0.125\) m): \(\nu=0.3\sqrt{2(6)/(0.125\times9)}=0.980\); \(L_d=6.9+20\log_{10}(1.332+0.880)=13.79\) dB
• 5 GHz (\(\lambda=0.060\) m): \(\nu=0.3\sqrt{2(6)/(0.060\times9)}=1.414\); \(L_d=6.9+20\log_{10}(1.651+1.314)=16.34\) dB
• Delta: \(16.34-13.79=2.55\) dB more diffraction loss at 5 GHz, for the identical physical obstruction

2.55 dB is on top of the roughly 6.4 dB that 5 GHz already loses to plain free-space spreading at the same distance – diffraction and free-space loss are two separate, additive penalties for going up in frequency. A classic ESP32’s fixed 2.4 GHz radio is not just “the band it happens to have”; at a given obstruction, it is measurably the more forgiving choice for a body, door, or piece of furniture crossing the link, which is worth a line in this chapter’s own scan-and-join evidence record when a join looks unexpectedly weak.

24.3 Learning Objectives

By the end of this chapter, you will be able to:

• scope the ESP32 Wi-Fi behavior that must be reviewed before a device leaves the bench
• separate station-mode join success from usable service readiness
• decide when a setup access point is appropriate and when it should be disabled
• record connection, failure, recovery, credential, service, and support evidence
• identify common ESP32 Wi-Fi implementation mistakes before they become field problems
• prepare a clean handoff to HTTP, WebSocket, power, and security implementation chapters

Quick Check: Wi-Fi ESP32

24.4 ESP32 Implementation Route

Use Figure 24.1 to keep a basic ESP32 Wi-Fi review in order.

Figure 24.1: ESP32 Wi-Fi implementation route

The route has seven checkpoints:

• scope the device role, service need, power pattern, and support workflow
• define the intended network profile and the profile that is out of scope
• implement station-mode join behavior without blocking the rest of the device indefinitely
• prove usable service after address assignment, name resolution, authentication, and application reachability
• handle failure, retry, backoff, and visible state after a weak signal or service outage
• keep credentials out of source code and provide a bounded setup or reset path
• decide whether the implementation is ready for the next chapter, a focused lab, or a design change

24.5 Connection Evidence Record

Use Figure 24.2 to collect evidence that is stronger than a single “connected” print.

Figure 24.2: ESP32 Wi-Fi connection evidence record

A useful record contains:

• firmware build or configuration under review
• network profile used for the test
• station join result and address assignment result
• service reachability result
• failure event and recovery behavior
• credential provisioning and reset behavior
• operator or user-visible state
• remaining limits and next decision

24.6 Focused Lab Evidence

The merged hands-on lab material narrows ESP32 review to one question per exercise. A lab should prove a bounded behavior, state what changed, and record what still needs field validation.

A useful lab record states:

• the question, device, firmware, AP profile, antenna, enclosure, and test network
• controlled variables and variables left uncontrolled
• observed join, service, retry, latency, traffic, power, and recovery behavior
• failure cases attempted, conclusion supported by the evidence, limits, and retest triggers

Carry these practice areas into the basic ESP32 record:

• association and usable service, including address assignment and recovery after AP restart
• channel or coexistence observations that explain weak joins or retries
• onboarding, segmentation, revocation, reset, and update-access checks
• power observations for boot, scan, join, command windows, retry, sleep, and setup mode
• traffic evidence for telemetry, commands, diagnostics, updates, and maintenance transfers
• troubleshooting records that move from symptom to layer, test, fix, retest, and next owner

24.7 What ESP32 Basics Means

The basic ESP32 Wi-Fi implementation has a few responsibilities:

• Station behavior: the device joins an existing access point as a client.
• Setup behavior: the device may temporarily host a setup network or use another provisioning path.
• State behavior: the device tracks connecting, connected, usable service, degraded, retrying, and stopped states.
• Service behavior: the device proves that the required application path works after network join.
• Credential behavior: the device receives, stores, replaces, and clears credentials through a supportable workflow.
• Recovery behavior: the device reacts to wrong credentials, missing access point, poor signal, service outage, restart, and reset.

This chapter does not require one specific framework. Arduino-style libraries, ESP-IDF event APIs, and higher-level device frameworks can all work if the resulting behavior and evidence are clear.

24.8 Scope Before Implementation

Before writing or accepting firmware, record the device context:

• device role: sensor, actuator, display, gateway, camera, mobile tool, or maintenance device
• required service: local broker, cloud endpoint, controller, update server, or local web service
• traffic type: telemetry, command, alert, diagnostic, update, or setup exchange
• power pattern: always powered, duty cycled, battery assisted, or battery primary
• network profile: band, SSID class, authentication method, segmentation boundary, and service reachability
• setup path: preloaded profile, setup access point, phone-assisted provisioning, support tool, or managed enrollment
• support path: reset, replacement, credential rotation, logs, visible state, and update ownership

The scope should also name what this basic review will not prove. Examples include installed building coverage, long-term battery life, fleet monitoring, and final security approval.

24.9 Station Join Path

A basic station join path should be event aware. A blocking loop that waits forever can hide failures and starve sensors, controls, watchdogs, or user feedback.

Record these behaviors:

• how the firmware starts the Wi-Fi radio and selects station mode
• which stored or newly provisioned profile it attempts first
• how long it waits before declaring a join attempt failed
• whether retry behavior uses backoff rather than constant rapid reconnects
• what state is shown to the user, log, or support channel during each phase
• what the application is allowed to do before usable service is confirmed

Join success is not the same as service success. The device may be associated to the access point but still unable to reach the application service because address assignment, name resolution, routing, authentication, or service authorization failed.

24.10 Usable Service Check

The first service check should match the device requirement. Do not use a generic internet ping if the device actually needs a local broker, controller, update server, or application endpoint.

Useful evidence includes:

• address assignment or static address configuration result
• route or service discovery result
• application endpoint reachability result
• authentication or session result when the service requires it
• result after device restart
• result after service restart or service outage
• visible state when network join works but service reachability fails

For a telemetry device, usable service may mean a message is accepted and acknowledged by the intended broker. For a command device, usable service may mean a command can be received and acted on within the allowed window. For a setup tool, usable service may mean the local configuration page is reachable only during the intended setup window.

24.11 Setup Access Point And Provisioning

A setup access point is useful when a device has no screen, keyboard, or wired management path. It is a setup tool, not a permanent network design.

Review these points:

• the setup access point starts only when credentials are missing, reset, or explicitly requested
• the setup window has a defined timeout or physical trigger
• setup traffic is limited to credential entry, diagnostics, or local configuration needed for onboarding
• credentials are not embedded in source code, documentation examples, or shared builds
• stored credentials can be replaced or cleared without reflashing the device
• a failed setup leaves the device in a clear support state
• setup mode cannot be confused with normal connected operation

Other provisioning paths can also be valid. The reviewer should focus on the evidence: how credentials enter the device, how they are stored, how they are cleared, and how failures are visible.

24.12 Network Scanning

Scanning can help a device choose or diagnose an access point, but it should not become the whole implementation.

Use scan evidence to answer focused questions:

• Is the expected network profile visible at the test location?
• Is the signal clearly weak, unstable, or crowded enough to explain a failure?
• Did the device choose the intended profile rather than a misleading nearby profile?
• Does scanning happen at a reasonable time instead of disrupting normal service?
• Is scan output recorded in a way that protects private network names when evidence is shared?

Avoid building a decision only on one scan. A scan is an observation from one place and time, not a site approval.

24.13 Failure And Recovery

Review recovery before calling the implementation ready.

Test at least these paths:

• wrong or expired credentials
• expected access point unavailable
• weak or obstructed signal
• address assignment failure
• service endpoint unavailable
• device restart during an outage
• support reset followed by reprovisioning

Strong recovery behavior includes:

• bounded retry and backoff
• visible state for the user or support workflow
• clear separation between network connected and service usable
• buffering or dropping policy for data created during an outage
• a safe way to return to setup or support mode
• records that show what failed, what recovered, and what still needs manual action

24.14 Power And Radio Behavior

Wi-Fi power behavior is dominated by transitions, not only by idle state. Even a basic review should observe the phases that matter for the device.

Record:

• boot and radio start
• scan and join
• service check
• normal traffic
• retry during outage
• command or receive window
• setup mode
• update or maintenance transfer if supported
• idle or sleep behavior

Do not turn this into a battery-life claim unless the chapter has the hardware and time evidence to support it. The useful output here is a power behavior record that can be carried into Wi-Fi Power Consumption.

24.15 Security And Support Boundaries

The basic implementation should not weaken the network or make support impossible.

Check:

• credentials are not stored in source code
• reset and reprovisioning are intentional, observable, and documented
• setup mode is bounded and not left open after normal onboarding
• service credentials or device identity are scoped to the device role
• retired, lost, or replaced devices can be denied service
• logs expose state without exposing secrets
• firmware update or maintenance access is considered before pilot testing

This is not the full security chapter, but it should prevent the most obvious implementation drift.

24.16 Worked Review: Room Sensor

Scenario:

• A room sensor wakes, joins Wi-Fi, sends telemetry, receives occasional configuration, and returns to a lower-power state.

Evidence route:

• Scope: sensor role, telemetry service, configuration path, power pattern, and reset workflow.
• Station: join the intended profile and record address assignment.
• Service: show telemetry acceptance and one configuration exchange.
• Recovery: repeat after access point restart and after a wrong credential test.
• Power: record wake, join, service, retry, and idle phases.
• Security: verify credentials are provisioned rather than embedded in the firmware source.

Review decision:

• Ready for the next lab only if service reachability, recovery, and credential handling are recorded with limits.

24.17 Worked Review: Setup Access Point Device

Scenario:

• A device starts a temporary setup network when no credentials are stored, accepts new credentials, then joins the normal network.

Evidence route:

• Scope: setup window, setup trigger, allowed setup actions, and failure state.
• Setup: verify the setup network appears only when intended.
• Credential: record how credentials are received, saved, replaced, and cleared.
• Transition: prove the device leaves setup mode and enters station mode after successful onboarding.
• Recovery: repeat with wrong credentials and support reset.
• Support: record the visible state for setup success and setup failure.

Review decision:

• Ready only if setup mode is bounded, credential handling is clear, and failed onboarding does not leave the device in an ambiguous state.

24.18 Worked Review: Maintenance Tool

Scenario:

• A handheld maintenance tool joins site Wi-Fi and communicates with a local controller during service visits.

Evidence route:

• Scope: mobile area, controller service, command path, and support owner.
• Station: record join and usable service at representative locations.
• Service: test diagnostics and commands separately.
• Recovery: observe movement through weak areas and service outage behavior.
• Security: confirm replacement or revocation can be handled.
• Support: show what the technician sees when network join works but service is unavailable.

Review decision:

• Ready for pilot only if the record separates movement limits, service limits, and support actions.

24.19 Knowledge Check: Join Versus Service

24.20 Knowledge Check: Setup Mode

24.21 Match Evidence To ESP32 Wi-Fi Review Area

24.22 Order The Basic ESP32 Wi-Fi Review

24.23 Common Mistakes

Stopping at connected:

• Problem: the firmware reports a connected station state, but the required service was never tested.
• Repair: record both station evidence and usable-service evidence.

Using a forever loop:

• Problem: the device waits indefinitely for Wi-Fi and stops doing other useful work.
• Repair: use bounded connection attempts, visible state, and recovery policy.

Leaving setup mode open:

• Problem: a setup network or setup page remains available during normal operation.
• Repair: start setup only under defined conditions and close it after onboarding.

Embedding credentials:

• Problem: credentials are placed in source code or a shared firmware build.
• Repair: use a provisioning path, stored credentials, replacement, and reset workflow.

Overusing scan results:

• Problem: one scan is treated as proof that the site has good Wi-Fi.
• Repair: use scans as observations and carry coverage questions into deployment validation.

Ignoring service-specific failures:

• Problem: the device can reach the network but cannot reach the application service.
• Repair: test the service path that matches the device role.

24.24 Final Checklist

Before accepting a basic ESP32 Wi-Fi implementation, confirm that the record includes:

• device role and service requirement
• intended network profile
• station join evidence
• address assignment or configured addressing evidence
• usable-service evidence
• setup or provisioning path
• credential replacement and reset behavior
• failure and recovery behavior
• user or support-visible state
• power behavior observations for the main operating phases
• security and support limits
• readiness decision, owner, and next action

24.25 The ESP32 Wi-Fi Radio and Its Modes

The ESP32 is a low-cost microcontroller family with integrated Wi-Fi. A classic ESP32 design uses an 802.11 b/g/n radio on the 2.4 GHz band, a single spatial stream, and 20/40 MHz channels. Its rate ceiling is far below a laptop’s, but that is normally acceptable for telemetry, commands, setup pages, and small maintenance transfers. The reviewer should still confirm the exact module or variant, because security modes, coexistence behavior, antenna layout, and SDK support can differ across boards.

It can run in three roles: station (STA), joining an existing AP; SoftAP, hosting its own network for other devices or for onboarding; or STA+AP simultaneously. Choosing the mode is the first decision in any ESP32 Wi-Fi project, but the mode choice is only the start. A usable implementation also needs a state model for scanning, joining, address assignment, service readiness, outage, retry, setup, reset, and stopped behavior.

For review purposes, do not treat an example sketch as the implementation. The basic question is whether the firmware can prove the specific service path it claims to support. A sensor may need one acknowledged MQTT publish, a maintenance tool may need a local controller command, and a setup page may need a bounded onboarding window. In each case the evidence should separate radio join, network address, application reachability, credential handling, and recovery. That separation keeps a serial log that says “connected” from being mistaken for a release decision. The record should name the firmware build, SDK path, board, antenna, test access point, and service endpoint.

Baseline facts: ESP32 Wi-Fi is a small state machine around a 2.4 GHz radio. The implementation is ready only when station/setup mode, service readiness, recovery, credentials, and support visibility are all bounded.

24.25.1 Overview Knowledge Check

24.26 The Event-Driven Connection Flow

ESP-IDF drives Wi-Fi through an event loop, not blocking calls. A station bring-up initialises non-volatile storage and the network interface, then: esp_wifi_init() → set mode STA → load SSID/password → esp_wifi_start() → esp_wifi_connect(). Progress arrives as events:

Event	Meaning	Typical action
WIFI_EVENT_STA_START	Radio ready	Call esp_wifi_connect()
WIFI_EVENT_STA_CONNECTED	Associated at layer 2	Wait for IP
IP_EVENT_STA_GOT_IP	DHCP lease obtained	Start app/sockets
WIFI_EVENT_STA_DISCONNECTED	Link lost/failed	Retry with backoff

The critical subtlety: STA_CONNECTED means the radio associated, but the device has no usable IP yet. Application sockets must wait for IP_EVENT_STA_GOT_IP. Opening a socket on connection rather than on got-IP is a classic beginner bug.

A practitioner implementation should also put policy around those events. Use a connection timeout rather than an endless wait, retry with backoff rather than a tight reconnect loop, and publish a visible state that support can read without exposing the SSID or password. Keep application work behind a service_usable state that is set only after the actual broker, controller, or update endpoint responds. If data is created during an outage, record whether it is buffered, summarized, dropped, or marked stale.

Provisioning needs the same discipline. A setup access point should start only under a defined condition such as missing credentials, a physical reset gesture, or an explicit support command. It should close after onboarding or timeout, and it should leave a clear failure state when credentials are wrong. A reviewer should be able to reproduce replacement, credential rotation, support reset, and firmware update access without editing source code or reflashing a shared secret into every device.

Worked example. A firmware opens an MQTT socket inside the STA_CONNECTED handler and it fails intermittently. The reason: DHCP has not yet assigned an address. Moving the socket open into the IP_EVENT_STA_GOT_IP handler fixes the immediate bug. Adding a bounded reconnect in the DISCONNECTED handler, a service-specific publish acknowledgment, and a support-visible degraded state makes the device robust to AP restarts, broker outages, and wrong-credential recovery.

24.26.1 Practitioner Knowledge Check

24.27 The 802.11 Association Sequence Beneath the Events

Those tidy ESP-IDF events wrap a standard 802.11 exchange. When the ESP32 connects it: scans (passive listening for beacons or active probe request/response) to find the SSID and best channel; performs authentication (the lightweight Open System exchange for WPA2/WPA3, which by itself proves nothing); sends an association request and gets an association response with an AID; and for a secured network runs the 4-way handshake to derive encryption keys. Only then can data (including DHCP) flow.

Understanding this maps failures to stages. Wrong password fails at the 4-way handshake, surfacing as STA_DISCONNECTED with a reason code, not at association. A hidden SSID needs an active probe because passive scanning will not reveal it. A weak signal shows as repeated association timeouts. The reason code in the disconnect event points straight at the failing stage.

The state machine also protects the rest of the firmware. Sensors, actuators, watchdogs, local storage, and user feedback should not freeze while Wi-Fi retries. A clean implementation records the last network stage, the disconnect reason, retry count, next retry time, and whether application traffic is allowed. That evidence lets a reviewer distinguish a radio problem from a DHCP problem, a DNS problem, an authorization problem, or a broker outage.

Worked example. A device associates but immediately disconnects with reason code 15, a 4-way handshake timeout. That is not a generic coverage conclusion; it is usually authentication or security negotiation, such as a wrong PSK or a WPA mode mismatch. Reading the reason code instead of blindly retrying turns “Wi-Fi will not connect” into a precise fix. The release record should show the failed stage, the corrected key or mode, the retest result, and whether the support state changed from retrying to usable service.

24.27.1 Under-the-Hood Knowledge Check

24.28 Summary

ESP32 Wi-Fi basics are not just API calls. A useful implementation proves the whole connection path from scoped requirement to station join, usable service, recovery, provisioning, support state, and bounded readiness decision.

Keep the evidence modest and specific. This chapter can show that a basic ESP32 Wi-Fi implementation is ready for the next focused review, but it should not claim installed coverage, long-term power behavior, or full security approval by itself.

24.29 Key Takeaway

Wi-Fi Implementation: ESP32 Basics should leave deployment evidence for association, throughput, latency, security setup, power behavior, failure recovery, and tested device constraints.

24.30 What’s Next

Use Wi-Fi HTTP & WebSocket when the weak point is application communication over Wi-Fi.

Use Wi-Fi Power Consumption when the device’s operating cycle needs deeper power work.

Use Wi-Fi Security and Provisioning when onboarding, credentials, reset, revocation, or update access is the main risk.

Use Wi-Fi Comprehensive Lab when the implementation is ready for a broader release-evidence review.

Use Wi-Fi for IoT: Implementations to compare this ESP32 path with other Wi-Fi implementation patterns.