Push Wake

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

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
    )

# 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
)

# 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")

# 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")

# 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

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)")

# 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")

# 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

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())