# device.scan serial

## Function

Scan the system serial port and return the serial port information array.

## Syntax

```bt
device.scan('serial')
```

## Parameters

| Parameters | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| type | String | No | serial | Device type; currently only serial is supported. |

## Return value

| Type | Description |
| ------ | ------ |
| Array | Returns an array of serial port information objects. |

## Serial port information field

The fields of each serial port information object in the array are as follows:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| type | String | Yes | Device type, fixed to `serial`. |
| port | String | Yes | System serial port name. Common values for Windows are `COM3`; common values for Linux/macOS are `/dev/ttyUSB0`, `/dev/tty.usbserial`. Passed to `device.open({port: ...})` when opening the serial port. |
| name | String | Yes | The friendly name of the device. The USB serial port preferentially uses the product name or manufacturer name; if it cannot be recognized, it will equal `port`. |
| kind | String | Yes | Serial port source type. Common values are `usb`, `bluetooth`, `pci`, `unknown`. |
| vid | Int | No | USB Vendor ID. Only exists when the USB serial port can recognize the manufacturer ID. |
| pid | Int | No | USB Product ID. Only exists when the USB serial port can recognize the product ID. |
| serial_number | String | Yes | USB device serial number; empty string if not provided by the system. |
| manufacturer | String | Yes | USB device manufacturer name; empty string if not provided by the system. |
| product | String | Yes | USB device product name; empty string if not provided by the system. |

## Example

```bt
// Scan system serial ports and take the first port's information.
ports = device.scan('serial')
first = ports[0]

// Output the serial port's friendly name so the user can confirm it is the target device.
result = first.name

// Example output: USB Serial Port
print result
```

## Notes

- `vid` and `pid` only exist if the hardware ID is recognized by the USB serial port.
- `serial_number`, `manufacturer`, `product` fields must exist, but are empty strings when the system does not provide corresponding values.