Automatic Wi-Fi roaming across saved access points: blueprint config + Esper Settings workaround for restricted Android Settings access

Android

This article explains how to configure automatic Wi-Fi roaming across multiple saved access points on your devices, and how to allow end users to manually switch Wi-Fi networks without exposing the full Android Settings panel.

Before you begin

You need to decide which approach works best for your use case:

• Automatic roaming: Devices automatically reconnect to any saved Wi-Fi network when the current connection drops. No user interaction required.
• User-controlled switching: End users can manually choose which saved Wi-Fi network to connect to, but cannot access full Android Settings (important for kiosk-mode devices).

How to set up automatic Wi-Fi roaming

If you want devices to automatically fail over to alternate saved networks when the primary access point goes offline, follow these steps:

1. In the Esper Console, navigate to Blueprints → [Your Blueprint Name] → Connectivity → Wi-Fi Access Points.
2. Add all intended Wi-Fi networks (SSIDs and credentials) to the Blueprint. Do not rely solely on networks added via API at the device level — they must also be present in the Blueprint for roaming to work.
3. Enable these settings in the Wi-Fi section:
   • Strict Wi-Fi Access Point Synchronization
   • Use Only Saved Wi-Fi Access Points
4. Save and publish the Blueprint, then apply it to your target device or group.
5. To verify the setup: take the primary access point offline and confirm the device automatically connects to another saved network within a reasonable reconnection window. You can check device connectivity status in Devices & Groups → [Device Name] → Device Details.

How to allow user-controlled Wi-Fi switching without full Android Settings access

If you want end users to manually select which saved Wi-Fi network to connect to — while preventing access to full Android Settings (which is important for kiosk-mode devices) — use Esper Settings instead:

1. In your Blueprint, do not enable full native Android Settings access.
2. Instead, enable Esper Settings in the Blueprint (under the Settings/Kiosk configuration section).
3. Ensure all permitted Wi-Fi networks are saved on the device via the Blueprint or API.
4. To verify: open Esper Settings on the device and confirm that only the Wi-Fi section is accessible. Only the provisioned networks should appear, and users should not be able to navigate to full Android Settings.

Troubleshooting

Devices are not auto-reconnecting even after enabling the Blueprint flags:

• Verify the Blueprint has been successfully applied to the device. Go to Devices & Groups → [Device Name] → Blueprint tab and confirm the status shows "Applied" (not "Pending").

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

• There is a known limitation with the Blueprint API (PUT /v2/blueprints/{blueprint_id}): the password field for WPA2-secured Wi-Fi networks may not appear in the response or payload schema. For now, add WPA2-secured networks through the Esper Console instead of the API. Contact Esper Support if you need assistance configuring WPA2 networks via API.

Esper Settings is not appearing as an option in the Blueprint:

• Confirm your device is running a supported Esper Esper Agent version that includes the Esper Settings feature. Update your device if needed.

Still need help?

If automatic roaming continues to fail despite correct Blueprint configuration, or if you encounter other issues, submit a support ticket and include the device name, Blueprint name, and a description of the behavior you're seeing.