Skip to Content

Push Wake

TL;DR

Push wake uses Apple Push Notification Service (APNs) to wake a suspended CMDOP iOS app so it can execute operations. When the SDK sends a request to an offline device, the control plane delivers a silent push notification that wakes the app, restores the connection, and completes the operation β€” typically within 2 to 30 seconds.

iOS suspends apps in the background. Push wake uses Apple Push Notifications to wake the CMDOP app and execute operations.

What problem does push wake solve?

Without Push Wake:
  iPhone app β†’ background β†’ suspended β†’ connection lost
  SDK request β†’ timeout β†’ fail

With Push Wake:
  iPhone app β†’ background β†’ suspended
  SDK request β†’ push notification β†’ app wakes β†’ connection restored β†’ success

How does push wake work?

How do I enable push wake?

How do I enable push wake in the iOS app?

  1. Open CMDOP app
  2. Go to Settings
  3. Enable β€œBackground Operations”
  4. Allow notifications when prompted

How do I use push wake from the SDK?

Push wake is automatic when the device is offline:

from cmdop import AsyncCMDOPClient
 
# Open a remote client session; push_wake defaults to True
async with AsyncCMDOPClient.remote(api_key="cmd_xxx") as client:
    # If the device is asleep, a silent push notification wakes it first
    files = await client.files.list(
        "marks-iphone",
        "/Documents",
        push_wake=True  # Default is True
    )

How do I configure push wake?

How do I set a custom push wake timeout?

# Extend the timeout to 60 seconds for devices on slow networks
files = await client.files.list(
    "marks-iphone",
    "/Documents",
    push_wake=True,
    push_wake_timeout=60  # Wait up to 60 seconds
)

How do I disable push wake?

# Skip push wake and fail immediately if the device is offline
try:
    files = await client.files.list(
        "marks-iphone",
        "/Documents",
        push_wake=False
    )
except DeviceOfflineError:
    print("Device is not connected")

What are the push wake session states?

StatePush Wake NeededWake Time
CONNECTEDNoInstant
BACKGROUNDNo< 1 second
SUSPENDEDYes2-10 seconds
TERMINATEDYes5-30 seconds

What are the best practices for push wake?

How should I handle push wake timeouts?

# Wrap the call in asyncio.wait_for to enforce a hard timeout
try:
    result = await asyncio.wait_for(
        client.files.list("marks-iphone", "/Documents"),
        timeout=30
    )
except asyncio.TimeoutError:
    print("Device didn't wake in time")

How should I batch operations after a wake?

# Good: One wake, multiple operations back-to-back
# The device stays awake for ~30 seconds after the first request
await client.files.list("marks-iphone", "/Documents")
await client.files.read("marks-iphone", "/Documents/file.txt")
await client.files.download("marks-iphone", "/Documents/data.db", "./data.db")
# Device stays awake for ~30 seconds
 
# Avoid: Letting the device sleep between requests triggers extra wakes
await asyncio.sleep(60)  # Device goes back to sleep
await client.files.list("marks-iphone", "/Documents")  # Another wake

How should I handle push wake failures?

from cmdop.exceptions import PushWakeError, DeviceOfflineError
 
# Catch specific exceptions to distinguish push delivery failures from offline
try:
    files = await client.files.list("marks-iphone", "/Documents")
except PushWakeError:
    print("Push notification failed to deliver")
except DeviceOfflineError:
    print("Device is offline (no network)")

How should I check device status before expensive operations?

# Query device status before starting a long-running operation
status = await client.system.status("marks-iphone")
 
if status.online:
    # Device is reachable; proceed without push wake overhead
    await expensive_operation()
else:
    # Device is offline; consider notifying the user or queuing the task
    print("Device offline, operation queued")

What are the push wake limitations?

What iOS restrictions affect push wake?

  • App must not be force-quit by user
  • Background App Refresh must be enabled
  • Device must have network connection
  • Push notifications must be allowed

How does push wake affect battery life?

  • Frequent wake-ups drain battery
  • iOS may throttle repeated wakes
  • Consider batching operations

What network requirements does push wake have?

  • Push requires network on phone
  • If phone is in airplane mode, push won’t work

Troubleshooting

Push Wake Not Working

  1. Check notification permissions
  2. Check Background App Refresh is enabled
  3. Ensure app wasn’t force-quit
  4. Verify device has network
# Check the current connection status of all registered devices
cmdop machines
 
# HOSTNAME       STATUS
# marks-iphone   suspended  # Can be woken
# marks-iphone   offline    # No network or force-quit

Slow Wake Times

Push delivery depends on:

  • Network conditions
  • iOS power management
  • APNS server load

Typical times:

  • Wi-Fi + charging: 2-5 seconds
  • Cellular + battery: 5-15 seconds
  • Low power mode: 10-30 seconds

Rate Limiting

iOS limits background execution:

  • Don’t wake more than once per minute
  • Batch operations when possible

How do I set up scheduled sync with push wake?

import asyncio
from datetime import datetime
 
async def scheduled_sync():
    """Sync files every hour using push wake to reach the device."""
 
    while True:
        try:
            # Wake the device and list remote files for syncing
            remote = await client.files.list("marks-iphone", "/Documents")
 
            # Download each file that matches the backup criteria
            for file in remote:
                if should_backup(file):
                    await client.files.download(
                        "marks-iphone",
                        file.path,
                        f"./backup/{file.name}"
                    )
 
            print(f"Sync completed at {datetime.now()}")
 
        except Exception as e:
            print(f"Sync failed: {e}")
 
        # Wait 1 hour before the next sync cycle
        await asyncio.sleep(3600)
 
asyncio.run(scheduled_sync())

Next

Last updated on
Overview