OS Update Management on Esper-Managed Devices: Blueprint Maintenance Windows, API Limitations, and Best Practices

Windows

Title: OS updates not installing on schedule — configure Blueprint maintenance windows

When OS updates are configured on Esper-managed devices, updates may fail to download or install at the expected time, leaving devices on outdated firmware despite an active update policy.

Why this happens

Esper delegates OS update delivery to your device OEM's update infrastructure. This means the OEM controls critical behaviors — such as whether updates can download over mobile data — independent of any policy set in the Esper Console. A Blueprint maintenance window tells the device when to install an available update, but the update must first be downloaded according to the OEM's own rules, typically requiring Wi-Fi.

Schedule OS updates using a Blueprint maintenance window

The recommended approach for all standard OEM Android devices (Samsung, Zebra, Honeywell, and others) is to define an installation window inside a Blueprint.

1. Open the Esper Console and navigate to Blueprints.
2. Select an existing blueprint applied to your target device group, or create a new one.
3. Within the blueprint editor, go to System Updates.
4. Set the update policy to Windowed. This restricts installation to your defined time range, preventing updates from interrupting device operation during business hours.
5. Set your installation window start and end times (for example, 2:00 AM – 4:00 AM). Times apply in the device's local time zone.
6. Save and publish the blueprint, then apply it to your target device group.

Ensure devices are ready to receive updates

Even with the correct Blueprint policy in place, updates will not download or install if the device conditions are not met. Before the maintenance window runs, confirm each device meets the following requirements:

• Connected to Wi-Fi — most OEMs only allow OTA downloads over Wi-Fi by default. A device on mobile data only will not download the update package.
• Plugged in or charging — many OEM update clients block installation if battery level is below a threshold, typically 30–50%.
• Auto-download over Wi-Fi enabled — on the device, navigate to Settings → About Device → Software Update and confirm this setting is active. This setting is controlled by the OEM and cannot be overridden by Esper.

Verify: After the maintenance window closes, navigate to Devices & Groups → [Device Name] → Device Info in the Esper Console and confirm the OS build number reflects the expected update. Allow up to 30 minutes after window end for the status to sync.

Trigger OS updates programmatically (Esper Foundation devices only)

If your devices run Esper Foundation — Esper's custom AOSP OS — you can initiate updates via the Esper API rather than waiting for a scheduled window. This method is not available for standard OEM Android devices.

1. Use the Esper API to retrieve the available OTA metadata for your Esper Foundation build.
2. Send a Command API request targeting your device or device group to initiate the update.
3. Monitor command execution status in Devices & Groups → [Device Name] → Activity Feed, or by polling the Command API for status changes.
4. Navigate to Devices & Groups → [Device Name] → Device Info and confirm the OS version reflects the applied update.

Troubleshoot updates that are not installing

1. On the device, open Settings → About Device → Software Update and check whether an update is pending download, pending installation, or shows an error. This confirms whether the OEM update client has received the package.
2. Verify the device was connected to Wi-Fi for the full duration of the maintenance window. If the device drops to mobile data, the OEM may pause or cancel the download.
3. Confirm the Blueprint with the Windowed policy is actively applied to the device's group by navigating to Devices & Groups → [Group Name] and reviewing the assigned blueprint.
4. If the device is on a mobile-data-only deployment and your OEM supports cellular OTA, check your OEM's device management documentation to determine whether cellular downloads can be enabled at the OEM level.

Verify: After addressing any connectivity or policy gaps, wait for the next scheduled maintenance window. Confirm the build number has advanced in Devices & Groups → [Device Name] → Device Info.

If this doesn't resolve it

If updates are still not installing after confirming Wi-Fi connectivity, charging state, and Blueprint policy, contact Esper Support and include the following information:

• Device serial number and IMEI
• OEM make, model, and current OS build number (from Devices & Groups → [Device Name] → Device Info)
• Name of the Blueprint applied and its configured maintenance window
• A screenshot of Settings → About Device → Software Update from the affected device
• Whether the device is on Wi-Fi or mobile data during the maintenance window

Still need help?

If the steps above don't resolve the issue, submit a support ticket with your device model, Android version, Esper Agent version, and a description of what you've already tried — this helps the support team investigate without a follow-up.