<br />

> [!NOTE]
> **Important:** This API works **only on ChromeOS**.

<br />

<br />

## Description

Use the `chrome.serial` API to read from and write to a device connected to a serial port.

<br />

<br />

## Permissions

`serial`  

<br />

<br />

## Availability

ChromeOS only

<br />

<br />

<br />

## Types

### ConnectionInfo

#### Properties

- bitrate number optional

  See `ConnectionOptions.bitrate`. This field may be omitted or inaccurate if a non-standard bitrate is in use, or if an error occurred while querying the underlying device.
- bufferSize number

  See `ConnectionOptions.bufferSize`
- connectionId number

  The id of the serial port connection.
- ctsFlowControl boolean optional

  See `ConnectionOptions.ctsFlowControl`. This field may be omitted if an error occurred while querying the underlying device.
- dataBits [DataBits](https://developer.chrome.com/docs/apps/reference/serial#type-DataBits) optional

  See `ConnectionOptions.dataBits`. This field may be omitted if an error occurred while querying the underlying device.
- name string

  See `ConnectionOptions.name`
- parityBit [ParityBit](https://developer.chrome.com/docs/apps/reference/serial#type-ParityBit) optional

  See `ConnectionOptions.parityBit`. This field may be omitted if an error occurred while querying the underlying device.
- paused boolean

  Flag indicating whether the connection is blocked from firing onReceive events.
- persistent boolean

  See `ConnectionOptions.persistent`
- receiveTimeout number

  See `ConnectionOptions.receiveTimeout`
- sendTimeout number

  See `ConnectionOptions.sendTimeout`
- stopBits [StopBits](https://developer.chrome.com/docs/apps/reference/serial#type-StopBits) optional

  See `ConnectionOptions.stopBits`. This field may be omitted if an error occurred while querying the underlying device.

### ConnectionOptions

#### Properties

- bitrate number optional

  The requested bitrate of the connection to be opened. For compatibility with the widest range of hardware, this number should match one of commonly-available bitrates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, 115200. There is no guarantee, of course, that the device connected to the serial port will support the requested bitrate, even if the port itself supports that bitrate. `9600` will be passed by default.
- bufferSize number optional

  The size of the buffer used to receive data. The default value is 4096.
- ctsFlowControl boolean optional

  Flag indicating whether or not to enable RTS/CTS hardware flow control. Defaults to false.
- dataBits [DataBits](https://developer.chrome.com/docs/apps/reference/serial#type-DataBits) optional

  `"eight"` will be passed by default.
- name string optional

  An application-defined string to associate with the connection.
- parityBit [ParityBit](https://developer.chrome.com/docs/apps/reference/serial#type-ParityBit) optional

  `"no"` will be passed by default.
- persistent boolean optional

  Flag indicating whether or not the connection should be left open when the application is suspended (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is "false." When the application is loaded, any serial connections previously opened with persistent=true can be fetched with `getConnections`.
- receiveTimeout number optional

  The maximum amount of time (in milliseconds) to wait for new data before raising an `onReceiveError` event with a "timeout" error. If zero, receive timeout errors will not be raised for the connection. Defaults to 0.
- sendTimeout number optional

  The maximum amount of time (in milliseconds) to wait for a `send` operation to complete before calling the callback with a "timeout" error. If zero, send timeout errors will not be triggered. Defaults to 0.
- stopBits [StopBits](https://developer.chrome.com/docs/apps/reference/serial#type-StopBits) optional

  `"one"` will be passed by default.

### DataBits

#### Enum

"seven"   
"eight"   

<br />

### DeviceControlSignals

#### Properties

- cts boolean

  CTS (Clear To Send).
- dcd boolean

  DCD (Data Carrier Detect) or RLSD (Receive Line Signal/ Detect).
- dsr boolean

  DSR (Data Set Ready).
- ri boolean

  RI (Ring Indicator).

### DeviceInfo

#### Properties

- displayName string optional

  A human-readable display name for the underlying device if one can be queried from the host driver.
- path string

  The device's system path. This should be passed as the `path` argument to `chrome.serial.connect` in order to connect to this device.
- productId number optional

  A USB product ID if one can be determined for the underlying device.
- vendorId number optional

  A PCI or USB vendor ID if one can be determined for the underlying device.

### HostControlSignals

#### Properties

- dtr boolean optional

  DTR (Data Terminal Ready).
- rts boolean optional

  RTS (Request To Send).

### ParityBit

#### Enum

"no"   
"odd"   
"even"   

<br />

### ReceiveError

#### Enum

"disconnected"   
The connection was disconnected.
"timeout"   
No data has been received for `receiveTimeout` milliseconds.
"device_lost"   
The device was most likely disconnected from the host.
"break"   
The device detected a break condition.
"frame_error"   
The device detected a framing error.
"overrun"   
A character-buffer overrun has occurred. The next character is lost.
"buffer_overflow"   
An input buffer overflow has occurred. There is either no room in the input buffer, or a character was received after the end-of-file (EOF) character.
"parity_error"   
The device detected a parity error.
"system_error"   
A system error occurred and the connection may be unrecoverable.

<br />

### ReceiveErrorInfo

#### Properties

- connectionId number

  The connection identifier.
- error [ReceiveError](https://developer.chrome.com/docs/apps/reference/serial#type-ReceiveError)

  An error code indicating what went wrong.

### ReceiveInfo

#### Properties

- connectionId number

  The connection identifier.
- data ArrayBuffer

  The data received.

### SendError

#### Enum

"disconnected"   
The connection was disconnected.
"pending"   
A send was already pending.
"timeout"   
The send timed out.
"system_error"   
A system error occurred and the connection may be unrecoverable.

<br />

### SendInfo

#### Properties

- bytesSent number

  The number of bytes sent.
- error [SendError](https://developer.chrome.com/docs/apps/reference/serial#type-SendError) optional

  An error code if an error occurred.

### StopBits

#### Enum

"one"   
"two"   

<br />

## Methods

### clearBreak()

Promise Chrome 45+

```typescript
chrome.serial.clearBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>
```

Restore character transmission on a given connection and place the transmission line in a nonbreak state.

#### Parameters

- connectionId number

  The id of the connection.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### connect()

Promise

```typescript
chrome.serial.connect(
  path: string,
  options?: ConnectionOptions,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo>
```

Connects to a given serial port.

#### Parameters

- path string

  The system path of the serial port to open.
- options [ConnectionOptions](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionOptions) optional

  Port configuration options.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (connectionInfo: ConnectionInfo) => void
  ```

  <br />

  - connectionInfo [ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)

#### Returns

- Promise\<[ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### disconnect()

Promise

```typescript
chrome.serial.disconnect(
  connectionId: number,
  callback?: function,
): Promise<boolean>
```

Disconnects from a serial port.

#### Parameters

- connectionId number

  The id of the opened connection.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### flush()

Promise

```typescript
chrome.serial.flush(
  connectionId: number,
  callback?: function,
): Promise<boolean>
```

Flushes all bytes in the given connection's input and output buffers.

#### Parameters

- connectionId number
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getConnections()

Promise

```typescript
chrome.serial.getConnections(
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo[]>
```

Retrieves the list of currently opened serial port connections owned by the application.

#### Parameters

- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (connectionInfos: ConnectionInfo[]) => void
  ```

  <br />

  - connectionInfos [ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)\[\]

#### Returns

- Promise\<[ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)\[\]\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getControlSignals()

Promise

```typescript
chrome.serial.getControlSignals(
  connectionId: number,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-DeviceControlSignals>
```

Retrieves the state of control signals on a given connection.

#### Parameters

- connectionId number

  The id of the connection.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (signals: DeviceControlSignals) => void
  ```

  <br />

  - signals [DeviceControlSignals](https://developer.chrome.com/docs/apps/reference/serial#type-DeviceControlSignals)

#### Returns

- Promise\<[DeviceControlSignals](https://developer.chrome.com/docs/apps/reference/serial#type-DeviceControlSignals)\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getDevices()

Promise

```typescript
chrome.serial.getDevices(
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-DeviceInfo[]>
```

Returns information about available serial devices on the system. The list is regenerated each time this method is called.

#### Parameters

- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (ports: DeviceInfo[]) => void
  ```

  <br />

  - ports [DeviceInfo](https://developer.chrome.com/docs/apps/reference/serial#type-DeviceInfo)\[\]

#### Returns

- Promise\<[DeviceInfo](https://developer.chrome.com/docs/apps/reference/serial#type-DeviceInfo)\[\]\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### getInfo()

Promise

```typescript
chrome.serial.getInfo(
  connectionId: number,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo>
```

Retrieves the state of a given connection.

#### Parameters

- connectionId number

  The id of the opened connection.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (connectionInfo: ConnectionInfo) => void
  ```

  <br />

  - connectionInfo [ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)

#### Returns

- Promise\<[ConnectionInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionInfo)\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### send()

Promise

```typescript
chrome.serial.send(
  connectionId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/serial#type-SendInfo>
```

Writes data to the given connection.

#### Parameters

- connectionId number

  The id of the connection.
- data ArrayBuffer

  The data to send.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (sendInfo: SendInfo) => void
  ```

  <br />

  - sendInfo [SendInfo](https://developer.chrome.com/docs/apps/reference/serial#type-SendInfo)

#### Returns

- Promise\<[SendInfo](https://developer.chrome.com/docs/apps/reference/serial#type-SendInfo)\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### setBreak()

Promise Chrome 45+

```typescript
chrome.serial.setBreak(
  connectionId: number,
  callback?: function,
): Promise<boolean>
```

Suspends character transmission on a given connection and places the transmission line in a break state until the clearBreak is called.

#### Parameters

- connectionId number

  The id of the connection.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### setControlSignals()

Promise

```typescript
chrome.serial.setControlSignals(
  connectionId: number,
  signals: HostControlSignals,
  callback?: function,
): Promise<boolean>
```

Sets the state of control signals on a given connection.

#### Parameters

- connectionId number

  The id of the connection.
- signals [HostControlSignals](https://developer.chrome.com/docs/apps/reference/serial#type-HostControlSignals)

  The set of signal changes to send to the device.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### setPaused()

Promise

```typescript
chrome.serial.setPaused(
  connectionId: number,
  paused: boolean,
  callback?: function,
): Promise<void>
```

Pauses or unpauses an open connection.

#### Parameters

- connectionId number

  The id of the opened connection.
- paused boolean

  Flag to indicate whether to pause or unpause.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  () => void
  ```

  <br />

#### Returns

- Promise\<void\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

### update()

Promise

```typescript
chrome.serial.update(
  connectionId: number,
  options: ConnectionOptions,
  callback?: function,
): Promise<boolean>
```

Update the option settings on an open serial port connection.

#### Parameters

- connectionId number

  The id of the opened connection.
- options [ConnectionOptions](https://developer.chrome.com/docs/apps/reference/serial#type-ConnectionOptions)

  Port configuration options.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (result: boolean) => void
  ```

  <br />

  - result boolean

#### Returns

- Promise\<boolean\>
  Chrome 117+


  Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

## Events

### onReceive

```typescript
chrome.serial.onReceive.addListener(
  callback: function,
)
```

Event raised when data has been read from the connection.

#### Parameters

- callback function


  The `callback` parameter looks like:

  ```typescript
  (info: ReceiveInfo) => void
  ```

  <br />

  - info [ReceiveInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ReceiveInfo)

### onReceiveError

```typescript
chrome.serial.onReceiveError.addListener(
  callback: function,
)
```

Event raised when an error occurred while the runtime was waiting for data on the serial port. Once this event is raised, the connection may be set to `paused`. A `"timeout"` error does not pause the connection.

#### Parameters

- callback function


  The `callback` parameter looks like:

  ```typescript
  (info: ReceiveErrorInfo) => void
  ```

  <br />

  - info [ReceiveErrorInfo](https://developer.chrome.com/docs/apps/reference/serial#type-ReceiveErrorInfo)

<br />