Turn off device screen

Tool Name: airdroid_business_turn_off_device_screen

Risk Level: 🟠 Medium Risk

Execution Mode: ⏳ Asynchronous

Category: Remote Commands

Quick Start (Copy & Use)

One-liner: Remotely turn off the device screen (screen rest)

What you need: DeviceId (device ID)

Success criteria: StatusCode = 200 and ErrorMessage is an empty string; returns Pid for tracking

What to do next: Use Get an Activity Log with the Pid to poll execution status

Minimal request example:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Minimal response example:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Recipes (Common Recipes)

Recipe 1: Turn off screen to save power

Scenario: Turn off the screen when the device is idle to save power

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Recipe 2: Batch screen off

Scenario: Turn off display device screens after business hours

1. Use Get All Devices to get the target device list
2. Iterate through devices and call Turn Off Device Screen

{
  "DeviceId": "device_id_1"
}

Recipe 3: Track screen-off status with Pid

Scenario: After turning off the screen, confirm whether the operation succeeded

1. Call Turn Off Device Screen to get the Pid
2. Use the Get an Activity Log tool to query status:

{
  "Pid": "1770854462319857000"
}

Polling logic:

• Progress = "Executing" → continue polling (interval 5 seconds)
• Progress = "Success" → screen off succeeded
• Progress = "Failure" → check the FailReason field

1. Overview

1.1 Description

Remotely turn off the screen of a device managed by AirDroid Business (screen rest). This is a lightweight operation that does not affect the device's running state — only the display is turned off.

1.2 When to Use

• Power saving: Turn off the screen when idle to extend battery life
• Display device management: Turn off display screens after business hours
• Privacy protection: Temporarily turn off the screen to prevent bystanders from viewing
• Remote maintenance: Turn off the screen before performing remote operations

1.3 Execution Mode & Response

This operation is asynchronous — after the command is sent, the device typically responds within seconds.

• Return value: Pid (activity log ID)
• Tracking method: Use the Get an Activity Log tool with the Pid to query execution status
• Prerequisite: The device must be online to receive the command
• Typical duration: Usually completes within 1-5 seconds

1.4 Prerequisites

1.5 Prerequisite Tools

1.6 Comparison with Similar Tools

2. Inputs

2.1 Parameter List

2.2 Parameter Details

`DeviceId`

Device unique identifier.

• Type: string
• Format: Non-empty string
• Source:
  1. Obtained via the Get All Devices tool; use the device_id field from the response
  2. Obtained via the Get a Device by Name tool for exact name lookup
• How to fill in a GI node:
  • Constant: Enter the device ID string directly, e.g. fa6edcff65ab444e8b5e0eb08df4175d
  • Upstream reference: Map from the Get All Devices node's Devices[0].device_id field
• Example:

  "fa6edcff65ab444e8b5e0eb08df4175d"

2.3 Parameter Combination Logic

• Only one required parameter: DeviceId
• Simple operation; no additional confirmation parameters needed

3. Outputs

3.1 Response Examples

Success response:

{
  "Pid": "1770854462319857000",
  "StatusCode": 200,
  "ErrorMessage": ""
}

Parameter error response:

{
  "Pid": "",
  "StatusCode": -1,
  "ErrorMessage": "device_id is required. Obtain via 'Get All Devices' or 'Get A Device By Name' tool."
}

Network error response:

{
  "Pid": "",
  "StatusCode": 500,
  "ErrorMessage": "Request timeout after 60 seconds."
}

3.2 Field Descriptions

3.3 Pid Tracking

Use the returned Pid with the Get an Activity Log tool to track execution status:

4. Examples

4.1 Basic Example: Turn off device screen

Request:

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Response:

{
  "Pid": "789012",
  "StatusCode": 200,
  "ErrorMessage": ""
}

4.2 Advanced Example: Batch screen off with tracking

Step 1: Call the screen-off endpoint

{
  "DeviceId": "fa6edcff65ab444e8b5e0eb08df4175d"
}

Step 2: Use the returned Pid to query the activity log

{
  "Pid": "789012"
}

Step 3: Determine completion based on Progress

4.3 Error Example: Empty device ID

Request:

{
  "DeviceId": ""
}

Response:

{
  "Pid": "",
  "StatusCode": -1,
  "ErrorMessage": "device_id is required. Obtain via 'Get All Devices' or 'Get A Device By Name' tool."
}

5. Error Handling

5.1 AB Three-Layer Error Codes

Core principle: AB uses a three-layer error code strategy. The agent should decide how to handle based on StatusCode.

5.2 Common Errors

5.3 Agent Self-Healing Decision Table

6. Best Practices

6.1 Performance Tips

• Confirm device is online: Check device status before turning off the screen to avoid sending commands to offline devices
• Batch operations: Screen-off commands can be sent in parallel; no need to wait for the previous one to complete

6.2 Security Considerations

🟢 Low Risk: This operation only turns off the screen and does not affect device operation. No special security confirmation is needed.

Operation notes:

• The device continues running; only the screen is turned off
• Users can wake the screen by touching it or pressing the power button
• No data loss or interruption to running applications

6.3 Idempotency

Idempotency: Naturally idempotent.

• Sending a screen-off command to an already-off screen has no side effects
• Multiple calls produce the same result; safe to retry

6.4 Async Operation Tracking

Use the returned Pid with Get an Activity Log to track execution status:

Polling recommendations:

• Interval: 5 seconds
• Max polling attempts: 6 (approx. 30 seconds)
• On timeout: Prompt the user to manually check device status

7. Related Tools

7.1 Prerequisite Tools

7.2 Follow-up Tools

7.3 Similar Tools Comparison

8. Tool Chains

8.1 Batch Screen Off Pattern

Scenario: Turn off display device screens after business hours

Tool chain:

Get All Devices (filter display group) → [Loop] Turn Off Device Screen → Get an Activity Log

Steps:

1. Call Get All Devices with Keyword={"group_name":"display-devices"} to get the target device list
2. Iterate through devices and call Turn Off Device Screen for each
3. Collect all Pid values and use Get an Activity Log to batch-track status

8.2 Power Saving Pattern

Scenario: Automatically turn off screens at specific times to save power

Tool chain:

Get All Devices (filter online devices) → [Loop] Turn Off Device Screen

Steps:

1. Call Get All Devices with Keyword={"online":"Online"} to get all online devices
2. Iterate through devices and call Turn Off Device Screen to turn off screens

8.3 Remote Operation Preparation

Scenario: Turn off the screen before performing remote operations

Tool chain:

Turn Off Device Screen → [Remote operations] → (user wakes screen manually)

Steps:

1. Call Turn Off Device Screen to turn off the target device screen
2. Perform remote operations (e.g. push apps, update configurations)
3. After operations complete, the user can wake the screen manually