# device.scan

## Function

Scans system devices. The current implementation supports serial-port scanning.

## Syntax

```bt
device.scan(type)
```

## 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 device information objects. |

## Serial port information field

Currently, `device.scan()` returns an array of serial-port information objects. Each object has the following fields:

| Field | Type | Must exist | Description |
| ------ | ------ | ------ | ------ |
| type | String | Yes | Device type, currently 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 serial devices visible to the current system.
ports = device.scan('serial')

// Read the system port name of the first serial port; it can be used with device.open({port: ...}).
first = ports[0]
result = first.port

// Example output: COM3
print result
```

## Notes

- The current implementation only supports `serial`, and the serial port is scanned by default when type is not passed.
- `vid` and `pid` are not available in all serial ports; when the field does not exist, the read result is Empty.