> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phones.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Device & USB

> Device enumerations, serial port descriptors, USB OTG multiplexer states, and battery level monitoring endpoints.

## 1.Overview

### Device Management

iClick provides comprehensive device management interfaces to get, manage, and control connected iOS devices.

### Device Connection Flow

```
iOS Device → Lightning Cable → USB Hub → iClick Hardware → Computer
                                                        ↓
                                            WebSocket API Call
```

### Core Concepts

#### Device ID

Each connected device has a unique **Device ID** used to identify and operate that device.

```
// Device ID example
"P72578581E07"
```

#### Device Status

Devices have two key statuses:

| Status | Field | Description |
| - | - | - |
| **Online Status** | - | Device appears in device list |
| **USB Status** | `plugged` | Whether USB hardware is ready, operations can only be performed when `true` |

### Available Interfaces

#### Query Operations

| Interface | Description | Documentation |
| - | - | - |
| `getDevices` | Get all device list and detailed information | View Documentation |

#### Management Operations

| Interface | Description | Status |
| - | - | - |
| `renameDevice` | Modify device name | 📝 To be completed |
| `removeDevice` | Remove device | 📝 To be completed |

### Quick Start

#### Get Device List

```
// Get all devices
const devices = await apiInvoke('getDevices');

// Iterate devices
for (const deviceId in devices) {
    const device = devices[deviceId];
    console.log(`Device: ${device.info.deviceName}`);
    console.log(`  ID: ${deviceId}`);
    console.log(`  Resolution: ${device.info.screenWidth}x${device.info.screenHeight}`);
    console.log(`  Status: ${device.plugged ? 'Ready' : 'Not Ready'}`);
}
```

#### Select Available Device

```
// Get first available device
async function getFirstDevice() {
    const devices = await apiInvoke('getDevices');
    
    for (const deviceId in devices) {
        if (devices[deviceId].plugged) {
            return deviceId;
        }
    }
    
    throw new Error('No available devices');
}

// Usage
const deviceId = await getFirstDevice();
console.log('Selected device:', deviceId);
```

### Device Information Fields

#### info Object

Each device's `info` object contains the following fields:

```
{
    deviceName: "My iPhone",               // Device name
    deviceIdentifier: "iPhone15,2",        // Device model identifier
    deviceChip: "COM3",                    // USB chip ID
    screenWidth: 1179,                     // Screen width
    screenHeight: 2556,                    // Screen height
    orientation: 1,                        // Orientation (1=portrait, 2=landscape)
    screenScale: 3.0,                      // Screen scale ratio
    deviceVersion: "17.0",                 // iOS version
    deviceRounded: true                    // Whether rounded screen
}
```

### Common Issues

#### ❓ What to do if device list is empty?

Check:

1. ✅ Is the iOS device connected to iClick hardware
2. ✅ Is iClick hardware connected to the computer
3. ✅ Is the device displayed in the iClick app
4. ✅ Is network connection normal

#### ❓ What does plugged false mean?

It means the device is online (connected via network), but USB hardware is not ready. Possible reasons:

* USB cable not plugged in properly
* iClick hardware not started
* USB Hub insufficient power supply

#### ❓ How to distinguish different device models?

Use the `deviceIdentifier` field, different models have different identifiers (e.g., `iPhone15,2` represents iPhone 14 Pro).

#### ❓ When does screen information change?

* When device switches between portrait and landscape, `screenWidth` and `screenHeight` will swap
* `orientation` value will change (1=portrait, 2=landscape)

### Next Steps

* See [Get Device List ](#get-device-list-1)for detailed usage
* See [Automation Operations](https://docs.phones.farm/api-reference/automation.md) to learn how to control devices
* See [Multi-language Clients](https://docs.phones.farm/api-reference/multi-language-client.md) to learn how to connect to the API

## 2.Get Device List

Get list of all devices and their detailed information.

### Endpoint Description

#### Endpoint Type

```
getDevices
```

#### Response Payload

Returns an object with device ID as key and device details as value:

```
{
    "P72578581E07": {
        "info": {
            "deviceId": 'P72578581E07',
            "deviceName": "Device Name",
            "deviceIdentifier": "Device Identifier",
            "deviceChip": "USB Chip ID",
            "screenWidth": 750,
            "screenHeight": 1334,
            "orientation": 0,
            "screenScale": 2,
            "deviceVersion": "iOS Version",
            "deviceRounded": false
        },
        "plugged": true  // Whether USB is plugged in,
        "online": true   // Online
    },
    //...
}
```

### Return Field Description

#### info Object Fields

| Field Name | Type | Description | Example Value |
| - | - | - | - |
| `deviceName` | string | Device name (customizable) | `"My iPhone"` |
| `deviceIdentifier` | string | Device unique identifier | `"P72578581E07"` |
| `deviceChip` | string | USB chip ID | `XXXXXXXXXXX` |
| `screenWidth` | number | Screen width (pixels) | `1179` |
| `screenHeight` | number | Screen height (pixels) | `2556` |
| `orientation` | number | Screen orientation | `1` (portrait) / `2` (landscape) |
| `screenScale` | number | Screen scale ratio | `3.0` |
| `deviceVersion` | string | iOS system version | `"17.0"` |
| `deviceRounded` | boolean | Whether rounded screen | `true` / `false` |

## 3.Rename Device

Modify the device display name for easy identification and management of multiple devices.

### Endpoint Description

#### Endpoint Type

```
renameDevice
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `deviceName` | string | ✅ | New device name (max 18 characters) |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Rename device
await apiInvoke('renameDevice', {
    deviceId: 'P72578581E07',
    deviceName: 'Test Device 1'
});
```

## 4.Remove Device

Remove the specified device record from the device list.

### Endpoint Description

#### Endpoint Type

```
removeDevice
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Remove device (device must be offline)
await apiInvoke('removeDevice', {
    deviceId: 'P72578581E07'
});
```

### ⚠️ Notes

1. **Device Must Be Offline**
   * Can only remove **offline** devices (`online: false`)
   * Online devices cannot be removed and will throw an error
   * Need to disconnect device first, then perform removal

## 5.Stop Replay

Stop the device's auto-replay or broadcast functionality.

### Endpoint Description

#### Endpoint Type

```
stopReplay
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Stop device replay
await apiInvoke('stopReplay', {
    deviceId: 'P72578581E07'
});

console.log('Replay stopped');
```

### Feature Description

This interface sends a stop broadcast command to the device, used for:

* 📡 Stop device video stream broadcast
* 🔄 Interrupt automation task execution

## 6.Set Device Busy State

Set the busy state of a device to identify whether the device is executing tasks, facilitating device conflict avoidance during multi-script collaboration.

### Endpoint Description

#### Endpoint Type

```
setDeviceBusy
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |
| `state` | boolean | ✅ | Busy state, true=busy, false=idle |

#### Response Payload

```
true  // Returns true on successful operation
```

#### Event Notifications

When setting the state, events are triggered and broadcast via WebSocket:

* Triggers `device:busy` event when set to busy
* Triggers `device:idle` event when set to idle

### Basic Usage

```
// Set device to busy state
await apiInvoke('setDeviceBusy', {
    deviceId: 'P72578581E07',
    state: true
});

// Execute tasks...

// Set to idle state after task completion
await apiInvoke('setDeviceBusy', {
    deviceId: 'P72578581E07',
    state: false
});
```

### Notes

> [!WARNING]
>
> Device Lock
>
> When a device is set to busy state (`state: true`), the system will automatically lock the corresponding device control panel to prevent interference from accidental operations during script execution.

> [!NOTE]
>
> Tips
>
> * The device's `busying` state can be obtained through the `getDevices` interface
> * It is recommended to promptly restore to idle state after task completion or exception to unlock the control panel

## 7.Auto Screen Mirroring

Automatically control device to come online and start screen mirroring without manual device operation.

### Endpoint Description

#### Endpoint Type

```
autoReplay
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

```
// Start device auto screen mirroring
await apiInvoke('autoReplay', {
    deviceId: 'P72578581E07'
});

console.log('Device is automatically coming online for screen mirroring...');
```

### Prerequisites

> [!WARNING]
>
> ⚠️ Must Complete Configuration First
>
> Before using this feature, you must complete the following configuration:
>
> 1. **Bind Chip** - Device must be bound to USB chip
> 2. **Configure Shortcuts** - Device must have iClick shortcuts installed and configured

## 8.Reboot Device

Reboot iOS devices through system shortcut keys.

### Endpoint Description

#### Endpoint Type

```
rebootDevice
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `deviceId` | string | ✅ | Device ID |

#### Response Payload

```
true  // Returns true on successful operation
```

### Basic Usage

#### Reboot Device

```
// Reboot specified device
await apiInvoke('rebootDevice', {
    deviceId: 'P72578581E07'
});
```

### How It Works

The interface triggers reboot operation through shortcut keys

> [!WARNING]
>
> Important Notes
>
> * Device will disconnect after executing reboot operation
> * No operations can be performed during device reboot (typically takes 30-60 seconds)

## 9.Get Chip List

Get list of USB control chips currently connected to the computer.

### Endpoint Description

#### Endpoint Type

```
getChipboards
```

#### Parameters

No parameters required.

#### Response Payload

Returns array of chip serial numbers:

```
[
    "Serial Number",
    "Serial Number",
    "Serial Number"
]
```

### Basic Usage

```
// Get list of connected chips
const chipboards = await apiInvoke('getChipboards');

console.log(`${chipboards.length} chips connected:`);
chipboards.forEach((serialId, index) => {
    console.log(`${index + 1}. ${serialId}`);
});
```

## 10.Bind USB Device

Bind device to specified USB chip, establishing association between device and chip.

### Endpoint Description

#### Endpoint Type

```
bindChipboard
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| deviceId | string | Yes | Device ID |
| serialId | string | Yes | USB chip serial number |

#### Response Payload

```
true  // Returns true on successful binding
```

### Basic Usage

```
// Bind device to specified chip
await apiInvoke('bindChipboard', {
    deviceId: 'P72578581E07',
    serialId: 'TEST_SERIALID'
});

console.log('Device successfully bound to chip');
```

### Feature Description

#### Binding Purpose

After device is bound to chip:

* 🎮 **Hardware Control** - Implement hardware-level device control through chip
* 📱 **Simulate Operations** - Simulate real touch and key operations
* 🔄 **Auto Screen Mirroring** - Work with shortcuts to implement automatic online screen mirroring

#### Binding Relationship

* **One-to-One Binding** - One device can only bind to one chip
* **Chip Exclusive** - One chip can only bind to one device
* **Persistent Save** - Binding relationship is persistently saved
* **Auto Initialize** - Chip automatically initializes device configuration after binding

## 11.Set USB LED

Control the LED indicator light on/off status on the USB chip, used to indicate chip working status.

### Endpoint Description

#### Endpoint Type

```
setChipboardLed
```

#### Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| serialId | string | Yes | Device serial number (used to find corresponding chip) |
| status | boolean | Yes | LED status, true=on, false=off |

#### Response Payload

```
true  // Returns true on successful setting
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.