Wi-Fi roaming not working — configure saved networks and Esper Settings access

Android

When a device's primary Wi-Fi access point goes offline or is out of range, the device may fail to reconnect to other known networks — or end users on kiosk-mode devices may have no way to manually switch networks without being exposed to the full Android Settings panel. Both problems are solved through Blueprint configuration and, where needed, Esper Settings.

Why this happens

Android will only automatically roam between saved networks if those networks are provisioned at the Blueprint level and the correct synchronization flags are enabled. Networks added only at the device level via API are not recognized by the roaming logic. Similarly, kiosk-mode devices typically block Android Settings entirely, leaving end users with no path to switch networks unless Esper Settings is explicitly enabled.

Option 1: Set up automatic Wi-Fi roaming

Use this option when devices should silently fail over to another saved network with no user interaction.

1. Open the Esper Console and navigate to Blueprints → [Blueprint Name] → Connectivity → Wi-Fi Access Points.
2. Add every intended Wi-Fi network — including its SSID and credentials — to the blueprint. Networks added only via API at the device level are not included in the roaming logic and will be ignored during failover.
3. Enable both of the following settings in the Wi-Fi section:
   • Strict Wi-Fi Access Point Synchronization
   • Use Only Saved Wi-Fi Access Points
   These flags instruct the Esper Agent to enforce and manage the saved network list, which is required for automatic failover to function.
4. Save and publish the blueprint, then apply it to your target device or group.

Verify: Take the primary access point offline. The device should automatically connect to another saved network within a few minutes. Confirm the active connection in Devices & Groups → [Device Name] → Device Details. Also confirm the blueprint status shows Applied (not Pending) under Devices & Groups → [Device Name] → Blueprints.

Option 2: Allow manual Wi-Fi switching without exposing Android Settings

Use this option when end users need to choose a network themselves, but the device runs in kiosk mode and full Android Settings must remain blocked.

1. Navigate to Blueprints → [Blueprint Name] and confirm that access to full native Android Settings is not enabled in the kiosk or Settings configuration section. Granting full Android Settings access on a kiosk device exposes controls outside your managed scope.
2. In the same blueprint, enable Esper Settings. This gives end users a controlled Settings interface that exposes only the sections you permit — including Wi-Fi — without opening the full Android Settings panel.
3. Ensure all permitted Wi-Fi networks are saved on the device via the blueprint or API before deploying.
4. Save and publish the blueprint, then apply it to your target device or group.

Verify: Open Esper Settings on the device. Only the Wi-Fi section should be visible and selectable. Only the provisioned networks should appear in the list. The device should have no path to the full Android Settings panel.

Troubleshooting

Devices are not auto-reconnecting after enabling the blueprint flags

Confirm the blueprint has been fully applied. Navigate to Devices & Groups → [Device Name] → Blueprints and check that the status reads Applied. A status of Pending means the device has not yet received or processed the latest blueprint version — wait for the device to check in, or verify it has an active network connection.

WPA2-secured networks added via the Blueprint API are not working

There is a known limitation with the Blueprint API endpoint PUT /v2/blueprints/{blueprint_id}: the password field for WPA2-secured Wi-Fi networks may not be included in the request schema, causing those networks to be saved without credentials. Add WPA2-secured networks directly through the Esper Console instead of the API until this is resolved.

If this doesn't resolve it

Contact Esper Support with the following information:

• The device serial number or Esper device ID
• The blueprint name and version applied to the device
• A screenshot of the blueprint's Wi-Fi Access Points section showing the configured networks and enabled flags
• The blueprint status shown under Devices & Groups → [Device Name] → Blueprints
• For API issues: the full request payload sent to PUT /v2/blueprints/{blueprint_id} and the response received

Still need help?

If Wi-Fi roaming issues persist after configuring saved networks and Esper Settings access, submit a support ticket and include your device model, Esper Settings configuration details, and the specific roaming behavior you're experiencing.