<br />

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

<br />

<br />

## Description

Use the `chrome.bluetoothSocket` API to send and receive data to Bluetooth devices using RFCOMM and L2CAP connections.

<br />

<br />

<br />

## Availability

ChromeOS only

<br />

<br />

## Manifest

The following keys must be declared [in the manifest](https://developer.chrome.com/docs/extensions/mv3/manifest) to use this API.
`"bluetooth"`  

<br />

<br />

## Types

### AcceptError

#### Enum

"system_error"   
A system error occurred and the connection may be unrecoverable.
"not_listening"   
The socket is not listening.

<br />

### AcceptErrorInfo

#### Properties

- error [AcceptError](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-AcceptError)

  An error code indicating what went wrong.
- errorMessage string

  The error message.
- socketId number

  The server socket identifier.

### AcceptInfo

#### Properties

- clientSocketId number

  The client socket identifier, i.e. the socket identifier of the newly established connection. This socket identifier should be used only with functions from the `chrome.bluetoothSocket` namespace. Note the client socket is initially paused and must be explictly un-paused by the application to start receiving data.
- socketId number

  The server socket identifier.

### CreateInfo

#### Properties

- socketId number

  The ID of the newly created socket. Note that socket IDs created from this API are not compatible with socket IDs created from other APIs, such as the `[`sockets.tcp`](../sockets_tcp/)` API.

### ListenOptions

#### Properties

- backlog number optional

  Length of the socket's listen queue. The default value depends on the operating system's host subsystem.
- channel number optional

  The RFCOMM Channel used by `listenUsingRfcomm`. If specified, this channel must not be previously in use or the method call will fail. When not specified, an unused channel will be automatically allocated.
- psm number optional

  The L2CAP PSM used by `listenUsingL2cap`. If specified, this PSM must not be previously in use or the method call with fail. When not specified, an unused PSM will be automatically allocated.

### ReceiveError

#### Enum

"disconnected"   
The connection was disconnected.
"system_error"   
A system error occurred and the connection may be unrecoverable.
"not_connected"   
The socket has not been connected.

<br />

### ReceiveErrorInfo

#### Properties

- error [ReceiveError](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-ReceiveError)

  An error code indicating what went wrong.
- errorMessage string

  The error message.
- socketId number

  The socket identifier.

### ReceiveInfo

#### Properties

- data ArrayBuffer

  The data received, with a maxium size of `bufferSize`.
- socketId number

  The socket identifier.

### SocketInfo

#### Properties

- address string optional

  If the underlying socket is connected, contains the Bluetooth address of the device it is connected to.
- bufferSize number optional

  The size of the buffer used to receive data. If no buffer size has been specified explictly, the value is not provided.
- connected boolean

  Flag indicating whether the socket is connected to a remote peer.
- name string optional

  Application-defined string associated with the socket.
- paused boolean

  Flag indicating whether a connected socket blocks its peer from sending more data, or whether connection requests on a listening socket are dispatched through the `onAccept` event or queued up in the listen queue backlog. See `setPaused`. The default value is "false".
- persistent boolean

  Flag indicating if the socket remains open when the event page of the application is unloaded (see `SocketProperties.persistent`). The default value is "false".
- socketId number

  The socket identifier.
- uuid string optional

  If the underlying socket is connected, contains information about the service UUID it is connected to, otherwise if the underlying socket is listening, contains information about the service UUID it is listening on.

### SocketProperties

#### Properties

- bufferSize number optional

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

  An application-defined string associated with the socket.
- persistent boolean optional

  Flag indicating whether the socket is left open when the event page of the application is unloaded (see [Manage App Lifecycle](https://developer.chrome.com/docs/apps/app_lifecycle)). The default value is `false.` When the application is loaded, any sockets previously opened with persistent=true can be fetched with [`getSockets`](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#method-getSockets).

## Methods

### close()

Promise

```typescript
chrome.bluetoothSocket.close(
  socketId: number,
  callback?: function,
): Promise<void>
```

Disconnects and destroys the socket. Each socket created should be closed after use. The socket id is no longer valid as soon at the function is called. However, the socket is guaranteed to be closed only when the callback is invoked.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### connect()

Promise

```typescript
chrome.bluetoothSocket.connect(
  socketId: number,
  address: string,
  uuid: string,
  callback?: function,
): Promise<void>
```

Connects the socket to a remote Bluetooth device. When the `connect` operation completes successfully, `onReceive` events are raised when data is received from the peer. If a network error occur while the runtime is receiving packets, a `onReceiveError` event is raised, at which point no more `onReceive` event will be raised for this socket until the `setPaused(false)` method is called.

#### Parameters

- socketId number

  The socket identifier.
- address string

  The address of the Bluetooth device.
- uuid string

  The UUID of the service to connect to.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### create()

Promise

```typescript
chrome.bluetoothSocket.create(
  properties?: SocketProperties,
  callback?: function,
): Promise<https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-CreateInfo>
```

Creates a Bluetooth socket.

#### Parameters

- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketProperties) optional

  The socket properties (optional).
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (createInfo: CreateInfo) => void
  ```

  <br />

  - createInfo [CreateInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-CreateInfo)

    The result of the socket creation.

#### Returns

- Promise\<[CreateInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-CreateInfo)\>
  Chrome 91+


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

### disconnect()

Promise

```typescript
chrome.bluetoothSocket.disconnect(
  socketId: number,
  callback?: function,
): Promise<void>
```

Disconnects the socket. The socket identifier remains valid.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### getInfo()

Promise

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

Retrieves the state of the given socket.

#### Parameters

- socketId number

  The socket identifier.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (socketInfo: SocketInfo) => void
  ```

  <br />

  - socketInfo [SocketInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketInfo)

    Object containing the socket information.

#### Returns

- Promise\<[SocketInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketInfo)\>
  Chrome 91+


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

### getSockets()

Promise

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

Retrieves the list of currently opened sockets owned by the application.

#### Parameters

- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (sockets: SocketInfo[]) => void
  ```

  <br />

  - sockets [SocketInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketInfo)\[\]

    Array of object containing socket information.

#### Returns

- Promise\<[SocketInfo](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketInfo)\[\]\>
  Chrome 91+


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

### listenUsingL2cap()

Promise

```typescript
chrome.bluetoothSocket.listenUsingL2cap(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
): Promise<void>
```

Listen for connections using the L2CAP protocol.

#### Parameters

- socketId number

  The socket identifier.
- uuid string

  Service UUID to listen on.
- options [ListenOptions](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-ListenOptions) optional

  Optional additional options for the service.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### listenUsingRfcomm()

Promise

```typescript
chrome.bluetoothSocket.listenUsingRfcomm(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
): Promise<void>
```

Listen for connections using the RFCOMM protocol.

#### Parameters

- socketId number

  The socket identifier.
- uuid string

  Service UUID to listen on.
- options [ListenOptions](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-ListenOptions) optional

  Optional additional options for the service.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### send()

Promise

```typescript
chrome.bluetoothSocket.send(
  socketId: number,
  data: ArrayBuffer,
  callback?: function,
): Promise<number>
```

Sends data on the given Bluetooth socket.

#### Parameters

- socketId number

  The socket identifier.
- data ArrayBuffer

  The data to send.
- callback function optional


  The `callback` parameter looks like:

  ```typescript
  (bytesSent: number) => void
  ```

  <br />

  - bytesSent number

    The number of bytes sent.

#### Returns

- Promise\<number\>
  Chrome 91+


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

### setPaused()

Promise

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

Enables or disables a connected socket from receiving messages from its peer, or a listening socket from accepting new connections. The default value is "false". Pausing a connected socket is typically used by an application to throttle data sent by its peer. When a connected socket is paused, no `onReceive`event is raised. When a socket is connected and un-paused, `onReceive` events are raised again when messages are received. When a listening socket is paused, new connections are accepted until its backlog is full then additional connection requests are refused. `onAccept` events are raised only when the socket is un-paused.

#### Parameters

- socketId number
- paused boolean
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

### update()

Promise

```typescript
chrome.bluetoothSocket.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
): Promise<void>
```

Updates the socket properties.

#### Parameters

- socketId number

  The socket identifier.
- properties [SocketProperties](https://developer.chrome.com/docs/apps/reference/bluetoothSocket#type-SocketProperties)

  The properties to update.
- callback function optional


  The `callback` parameter looks like:

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

  <br />

#### Returns

- Promise\<void\>
  Chrome 91+


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

## Events

### onAccept

```typescript
chrome.bluetoothSocket.onAccept.addListener(
  callback: function,
)
```

Event raised when a connection has been established for a given socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

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

  <br />

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

### onAcceptError

```typescript
chrome.bluetoothSocket.onAcceptError.addListener(
  callback: function,
)
```

Event raised when a network error occurred while the runtime was waiting for new connections on the given socket. Once this event is raised, the socket is set to `paused` and no more `onAccept` events are raised for this socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

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

  <br />

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

### onReceive

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

Event raised when data has been received for a given socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

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

  <br />

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

### onReceiveError

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

Event raised when a network error occured while the runtime was waiting for data on the socket. Once this event is raised, the socket is set to `paused` and no more `onReceive` events are raised for this socket.

#### Parameters

- callback function


  The `callback` parameter looks like:

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

  <br />

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

<br />