An embedded Wi-Fi web module needs a dependable lifecycle: join a network, expose understandable data, retain the right settings, and recover when the network or power disappears. Build a read-only status endpoint first, then prove those transitions before adding configuration controls.
This guide is for a developer with a supported evaluation board and SDK. The example architecture uses a sensor value served locally to an authorized client. Pin the actual module, SDK, sample revision and build configuration in your project; the documentation examples below refer to Espressif's ESP32 programming guide, whose stable pages identify version 6.1 at this review.
Define the device states
Write down what the device does when unconfigured, joining, connected, disconnected and being reset. Give each state an observable indication that a technician can understand. Keep a recoverable way to enter provisioning when saved network credentials no longer work.
Espressif's provisioning documentation describes supported approaches and points to its network_provisioning component. Choose a documented method for the selected SDK and transport. Specify how the installer identifies the physical unit and supplies credentials; avoid leaving an unrestricted setup mode active after commissioning.
Scroll the table horizontally; keyboard users can focus it and use the arrow keys.
| State or event | Required behavior to define | Evidence to save |
|---|---|---|
| Unconfigured | An authorized installer can identify and provision this unit. | Identity shown, access method and completion result. |
| Connected | The client can find the device and read an authenticated, meaningful status response. | Address or discovery name, request result and decoded fields. |
| Network lost | The device reports connection loss and retries with bounded resource use. | State transitions, retry spacing and stale-data behavior. |
| Power restored | Valid committed settings return and startup reaches the expected state. | Boot identifier, retained settings and time to usable service. |
| Ownership reset | The documented reset removes credentials and other owner data as designed. | Which settings were cleared and how reprovisioning was verified. |
Expose a small, explicit data contract
Espressif's HTTP server component provides URI-handler building blocks. Your application supplies the data model, authorization, input validation and failure behavior. Begin with a read-only endpoint so connectivity and representation can be tested without changing device settings.
Fictional response design: this JSON illustrates a contract for GET /api/status; it is not the output of an Espressif sample or tested firmware.
{
"schema_version": 1,
"device_id": "bench-01",
"boot_id": "trial-007",
"sample_seq": 42,
"quantity": "ambient_temperature",
"value": 23.5,
"unit": "degC",
"sample_age_ms": 850,
"quality": "valid"
}Define the fields before writing the client. Here, age means elapsed time since the device acquired this sample, using its monotonic clock. Sequence belongs to this boot; the boot identifier changes after restart. The temperature quantity assumes a suitable ambient sensor, which must be selected and verified separately.
For a failed reading, define a representation such as value: null and quality: "sensor_error". If serving an older value, label it stale and retain its growing age. Specify a client freshness threshold from the application need. A cached page must not silently present old data as a new observation.
Make access and persistence deliberate
Use encrypted transport and an authentication method supported by the product architecture. Espressif's HTTPS server documentation describes its TLS server component and certificate configuration. Certificate trust, renewal and client identity remain deployment choices; a browser warning needs its cause resolved rather than normalized as the daily connection process.
Start on a controlled local network and restrict the service to intended clients. Keep credentials out of URLs and routine logs. If a browser can change settings, design authorization and request-origin protections for that interaction and validate every field on the device.
Separate persistent configuration from transient readings. Define which settings are committed together, how invalid stored values are detected, and which defaults are recoverable. Use the SDK's supported storage and update mechanisms. A successful “save” response should correspond to a documented durable state, with interruption tests confirming what happens before and after the commit.
Test recovery with observable outcomes
- Record a normal boot and status response with versions and network conditions.
- Use a wrong network credential on the bench; verify a clear failure and a usable return to provisioning.
- Remove the test access point, wait through several retries, then restore it. Check service recovery, memory use and duplicate connections.
- Restart the device after a completed configuration save. Verify the intended settings return.
- Exercise a documented reset and confirm which credentials and data disappear.
- Make the sensor unavailable using its supported test method. Confirm the client displays the explicit failure or stale state.
The web-module acceptance worksheet captures expected and observed outcomes, timing and unresolved defects. Once this lifecycle works, add configuration features one at a time. For a data path arriving from another protocol, the gateway mapping guide helps preserve units and status across that boundary.