chrome.bluetoothSocket

Description

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

Manifest

The following keys must be declared in the manifest to use this API.

"bluetooth"

Types

AcceptError

Enum

"system_error"
A system error occurred and the connection may be unrecoverable.

"not_listening"
The socket is not listening.

AcceptErrorInfo

Properties

  • error

    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.

ReceiveErrorInfo

Properties

  • error

    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). The default value is false. When the application is loaded, any sockets previously opened with persistent=true can be fetched with getSockets.

Methods

close()

Promise 
chrome.bluetoothSocket.close(
  socketId: number,
  callback?: function,
)

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: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

connect()

Promise 
chrome.bluetoothSocket.connect(
  socketId: number,
  address: string,
  uuid: string,
  callback?: function,
)

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: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

create()

Promise 
chrome.bluetoothSocket.create(
  properties?: SocketProperties,
  callback?: function,
)

Creates a Bluetooth socket.

Parameters

  • properties

    SocketProperties optional

    The socket properties (optional).

  • callback

    function optional

    The callback parameter looks like: 

    (createInfo: CreateInfo) => void

    • createInfo

      CreateInfo

      The result of the socket creation.

Returns

  • Promise<CreateInfo>

    Chrome 91+

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

disconnect()

Promise 
chrome.bluetoothSocket.disconnect(
  socketId: number,
  callback?: function,
)

Disconnects the socket. The socket identifier remains valid.

Parameters

  • socketId

    number

    The socket identifier.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

getInfo()

Promise 
chrome.bluetoothSocket.getInfo(
  socketId: number,
  callback?: function,
)

Retrieves the state of the given socket.

Parameters

  • socketId

    number

    The socket identifier.

  • callback

    function optional

    The callback parameter looks like: 

    (socketInfo: SocketInfo) => void

    • socketInfo

      SocketInfo

      Object containing the socket information.

Returns

  • Promise<SocketInfo>

    Chrome 91+

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

getSockets()

Promise 
chrome.bluetoothSocket.getSockets(
  callback?: function,
)

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

Parameters

  • callback

    function optional

    The callback parameter looks like: 

    (sockets: SocketInfo[]) => void

Returns

  • Promise<SocketInfo[]>

    Chrome 91+

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

listenUsingL2cap()

Promise 
chrome.bluetoothSocket.listenUsingL2cap(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
)

Listen for connections using the L2CAP protocol.

Parameters

  • socketId

    number

    The socket identifier.

  • uuid

    string

    Service UUID to listen on.

  • options

    ListenOptions optional

    Optional additional options for the service.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

listenUsingRfcomm()

Promise 
chrome.bluetoothSocket.listenUsingRfcomm(
  socketId: number,
  uuid: string,
  options?: ListenOptions,
  callback?: function,
)

Listen for connections using the RFCOMM protocol.

Parameters

  • socketId

    number

    The socket identifier.

  • uuid

    string

    Service UUID to listen on.

  • options

    ListenOptions optional

    Optional additional options for the service.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

send()

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

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: 

    (bytesSent: number) => void

    • 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 
chrome.bluetoothSocket.setPaused(
  socketId: number,
  paused: boolean,
  callback?: function,
)

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 onReceiveevent 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: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

update()

Promise 
chrome.bluetoothSocket.update(
  socketId: number,
  properties: SocketProperties,
  callback?: function,
)

Updates the socket properties.

Parameters

  • socketId

    number

    The socket identifier.

  • properties

    SocketProperties

    The properties to update.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 91+

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

Events

onAccept

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: 

    (info: AcceptInfo) => void

onAcceptError

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

onReceive

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

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

Parameters

onReceiveError

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