L2CAP Extension Vendor Specific API¶
L2CAP Extension Commands¶
All L2CAP commands have the following format (this is also displayed for each command description):
Name |
Size (bytes) |
Description |
Opcode |
2 |
|
connectionHandle, CID, or PSM |
2 |
Connection Handle, Channel ID, or Protocol/Service Multiplexer |
Command PDU |
Variable |
Command Parameters |
For the command parameters, please see the corresponding command description below.
Note: The connection handle of 0xFFFE is considered as the loopback connection. All message sent to this connection will be looped back to the local host.
LE Protocol/Service Multiplexer (PSM) values are separated into two ranges: - Fixed (0x0001 – 0x007F): Values in the first range are assigned by the Bluetooth SIG and indicate protocols. - Dynamic (0x0080 – 0x00FF): Values in the second rage are dynamically allocated and used in conjunction with services defined in the GATT server.
L2CAP_SendData¶
- Opcode
0xFCF0
- Command Description
The L2CAP Data command is used to send an SDU on a Connection Oriented Channel established with the peer device.
Command Parameters
- CID
Local Channel ID
- Size
2 byte(s)
- Default
0x0040
- Range
0x0040 - 0x007F
- SDU
SDU to be sent on the channel
- Size
input byte(s)
- Default
“”
- Range
to L2CAP_SDU_SIZE octets
Events Generated
When this command is received, the host will send the CommandStatus Event. When the SDU transmission is done to the peer device, the L2CAP Send SDU Done Event (L2CAP_SendSduDone) will be generated. If the local channel runs out of credits required to send the SDU, the L2CAP Out of Credit Event (L2CAP_OutOfCredit) will be generated.
L2CAP_RegisterPsm¶
- Opcode
0xFCF1
- Command Description
The L2CAP Register PSM command is used to register a Protocol/Service Multiplexer (PSM) with the L2CAP layer.
Command Parameters
- PSM
Local Protocol/Service Multiplexer (PSM)
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
- MTU
Maximum SDU size that can be received by PSM
- Size
2 byte(s)
- Default
0x0017
- Range
Any 2 byte value
- initialPeerCredits
Number of packets that peer device can send to local device
- Size
2 byte(s)
- Default
0x0001
- Range
Any 2 byte value
- peerCreditThreshold
Low threshold for peer credits
- Size
2 byte(s)
- Default
0x0000
- Range
Any 2 byte value
- maxNumChannels
Maximum number of Connection Oriented Channels supported by PSM
- Size
1 byte(s)
- Default
0x01
- Range
Any 1 byte value
- enableSecurityVerification
Indicates whether to enable security verification by the application for any incoming connection request
- Size
1 byte(s)
- Default
0x00
- Range
Value
Description
0x00
No
0x01
Yes
Events Generated
When this command is received, the local device will send the CommandStatus Event. If the application wishes to perform its own security verification (by setting enableSecurityVerification to TRUE) for any incoming connection request then an L2CAP Connection Request (L2CAP_ConnectReq) event will be sent up to the application, which must then send an L2CAP Connection Response (L2CAP_ConnectRsp) command back. When the peer credit count reaches the peer credit threshold (specified by peerCreditThreshold), the L2CAP Peer Credit Threshold Event (L2CAP_PeerCreditThreshold) will be generated.
L2CAP_DeregisterPsm¶
- Opcode
0xFCF2
- Command Description
The L2CAP Deregister PSM command is sent to deregister a Protocol/Service Multiplexer (PSM) with the L2CAP layer.
Command Parameters
- PSM
Local Protocol/Service Multiplexer (PSM) to be deregistered with L2CAP
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
Events Generated
When this request is received, the local device will send the CommandStatus Event.
L2CAP_PsmInfo¶
- Opcode
0xFCF3
- Command Description
The L2CAP PSM Info command is used to get the current information about a given PSM registered with the L2CAP layer.
Command Parameters
- PSM
Local Protocol/Service Multiplexer (PSM)
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
Events Generated
When this request is received, the local device will send the CommandStatus Event.
Additional Command Status Return Parameters
- dataLen
- Size
1 byte(s)
- Range
- MTU
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- MPS
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- initialPeerCredits
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerCreditThreshold
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- maxNumChannels
- Condition
( StatStatus==0x00)
- Size
1 byte(s)
- Range
- numActiveChannels
- Condition
( StatStatus==0x00)
- Size
1 byte(s)
- Range
L2CAP_PsmChannels¶
- Opcode
0xFCF4
- Command Description
The L2CAP PSM Channels command is used to get the list of all the active Connection Oriented Channels for a given PSM registered with the L2CAP layer.
Command Parameters
- PSM
Local Protocol/Service Multiplexer (PSM)
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
Events Generated
When this request is received, the local device will send the CommandStatus Event.
Additional Command Status Return Parameters
- dataLen
- Size
1 byte(s)
- Range
An array of size “dataLen/2” will be returned containing the parameters starting here:
- CID
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
The array of parameters ends here.
L2CAP_ChannelInfo¶
- Opcode
0xFCF5
- Command Description
The L2CAP Channel Info command is used to get the current information about an active Connection Oriented Channel.
Command Parameters
- CID
Local Channel ID
- Size
2 byte(s)
- Default
0x0040
- Range
0x0040 - 0x007F
Events Generated
When this request is received, the local device will send the CommandStatus Event.
Additional Command Status Return Parameters
- dataLen
- Size
1 byte(s)
- Range
- state
- Condition
( StatStatus==0x00)
- Size
1 byte(s)
- Range
Value
Description
0x0000
L2CAP_CLOSED
0x0001
L2CAP_OPEN
0x0002
L2CAP_PENDING_CONN_RSP
0x0003
L2CAP_PENDING_DISCONN_RSP
0x0004
L2CAP_PENDING_PARAM_UPDATE_RSP
0x0005
L2CAP_PENDING_INFO_RSP
0x0006
L2CAP_PENDING_SEC_VERIFY
- PSM
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- CID
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- MTU
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- MPS
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- credits
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerCID
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerMTU
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerMPS
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerCredits
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
- peerCreditThreshold
- Condition
( StatStatus==0x00)
- Size
2 byte(s)
- Range
L2CAP_ConnectReq¶
- Opcode
0xFC94
- Command Description
The L2CAP Connection Request command is used to create and configure a Connection Oriented Channel between the local and the peer device.
Command Parameters
- Connection Handle
Identifies the connection.
- Size
2 byte(s)
- Default
0x0000
- Range
0x0000 to 0xFFFD
- PSM
Local Protocol/Service Multiplexer (PSM)
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
- peerPSM
Peer Protocol/Service Multiplexer (PSM)
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0x00FF
Events Generated
When this command is received, the local device will send the CommandStatus Event with the Status parameter after sending an LE Credit Based Connection Request to the peer device. When a new channel has been established, the L2CAP Channel Established Event (L2CAP_ChannelEstablished) will be generated.
L2CAP_ConnectRsp¶
- Opcode
0xFC95
- Command Description
When a device receives an LE Credit Based Connection Request, it must send an LE Credit Based Connection Response back, which is done automatically by the L2CAP layer. However, if the application wishes to perform its own security verification (configurable at PSM registration), then a Connection Request (L2CAP_ConnectReq) event will be sent up to the application which must then send a Connection Response (L2CAP_ConnectRsp) command back indicating the outcome of the connection request.
Command Parameters
- Connection Handle
Identifies the connection.
- Size
2 byte(s)
- Default
0x0000
- Range
0x0000 to 0xFFFD
- id
Identifier to match responses with requests
- Size
1 byte(s)
- Default
0x01
- Range
0x01 - 0xFF
- result
Indicates outcome of connection request
- Size
2 byte(s)
- Default
0x0000
- Range
Value
Description
0x0000
L2CAP_CONN_SUCCESS
0x0001
Reserved
0x0002
L2CAP_CONN_PSM_NOT_SUPPORTED
0x0003
Reserved
0x0004
L2CAP_CONN_NO_RESOURCES
0x0005
L2CAP_CONN_INSUFFICIENT_AUTHEN
0x0006
L2CAP_CONN_INSUFFICIENT_AUTHOR
0x0007
L2CAP_CONN_INSUFFICIENT_KEY_SIZE
0x0008
L2CAP_CONN_INSUFFICIENT_ENCRYPT
0x0009
L2CAP_CONN_INVALID_SRC_CID
0x000A
L2CAP_CONN_SRC_CID_ALREADY_ALLOC
Events Generated
When this request is received, the local device will send the CommandStatus Event with the Status parameter after sending an LE Credit Based Connection Response back to the peer device.
L2CAP_DisconnectReq¶
- Opcode
0xFC86
- Command Description
The L2CAP Disconnection Request is sent to terminate a Connection Oriented Channel established between the local and the peer device.
Command Parameters
- CID
Local Channel ID
- Size
2 byte(s)
- Default
0x0040
- Range
0x0040 - 0x007F
Events Generated
When this command is received, the local device will send the CommandStatus Event with the Status parameter after forwarding the request to the peer device. When the channel is terminated, the L2CAP Channel Terminated Event (L2CAP_ChannelTerminated) will be generated.
L2CAP_FlowCtrlCredit¶
- Opcode
0xFC96
- Command Description
The LE Flow Control Credit commands are sent when the local device is capable of receiving additional LE-frames on an established L2CAP channel.
Command Parameters
- CID
Local Channel ID
- Size
2 byte(s)
- Default
0x0040
- Range
0x0040 - 0x007F
- peerCredits
Number of LE-frames that can be sent to local device
- Size
2 byte(s)
- Default
0x0001
- Range
0x0001 - 0xFFFF
Events Generated
When this request is received, the local device will send the CommandStatus Event with the Status parameter after forwarding the request to the peer device. When the peer credit count reaches a specified low threshold (configurable at PSM registration), the L2CAP Peer Credit Threshold Event (L2CAP_PeerCreditThreshold) will be generated.
L2CAP_InfoReq¶
- Opcode
0xFC8A
- Command Description
L2CAP Info Request
Command Parameters
- Connection Handle
Identifies the connection.
- Size
2 byte(s)
- Default
0x0000
- Range
0x0000 to 0xFFFD
- infoType
The type of implementation specific information being requested
- Size
2 byte(s)
- Default
0x0002
- Range
Value
Description
0x0001
CONNECTIONLESS_MTU
0x0002
EXTENDED_FEATURES
0x0003
FIXED_CHANNELS
Events Generated
When this request is received, the local device will send the CommandStatus Event with the Status parameter after forwarding the request to the peer device. After receiving a response from the peer device, the L2CAP_InfoRsp will be generated.
L2CAP_ConnParamUpdateReq¶
- Opcode
0xFC92
- Command Description
The Connection Parameter Update Request is sent from the LE slave device to the LE master device. This request allows the LE slave Host to request a set of new connection parameters.
Command Parameters
- Connection Handle
Identifies the connection.
- Size
2 byte(s)
- Default
0x0000
- Range
0x0000 to 0xFFFD
- intervalMin
The minimum value for the connection event interval
- Size
2 byte(s)
- Default
80
- Range
6 - 3200
- intervalMax
The maximum value for the connection event interval
- Size
2 byte(s)
- Default
160
- Range
6 - 3200
- slaveLatency
The slave latency parameter
- Size
2 byte(s)
- Default
0
- Range
0 - 500
- timeoutMultiplier
The connection timeout parameter
- Size
2 byte(s)
- Default
1000
- Range
10 - 3200
Events Generated
When this request is received, the LE slave host will send the CommandStatus Event with the Status parameter after forwarding the request to the LE master host. The LE master host will send the Connection Parameter Update Response (L2CAP_ConnParamUpdateRsp) event back. If the LE slave host receives this request, it will respond with a Command Reject (L2CAP_CmdReject) with reason 0x0000 (command not understood).
L2CAP Extension Events¶
All L2CAP event have the following format (this is also displayed for each event description):
Name |
Size (bytes) |
Description |
Opcode |
2 |
PDU operation code |
Status |
1 |
Event Status |
Connection Handle |
2 |
Connection handle of the link |
Event PDU |
Variable |
Event parameters |
For the event parameters, please see the corresponding section below.
L2CAP_CmdReject¶
- Opcode
0x0481
- Event Description
The Command Reject is sent in response to a command with an unknown command code or when sending the corresponding response is inappropriate
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link.
- Size
2 byte(s)
- Range
- reason
Reason for rejection.
- Size
2 byte(s)
- Range
Value
Description
0x0000
CMD_NOT_UNDERSTOOD
0x0001
SIGNAL_MTU_EXCEED
0x0002
REJECT_INVALID_CID
- signalingMTU
- Condition
( CmdRejectReason==0x0001)
- Size
2 byte(s)
- Range
- localCID
- Condition
( CmdRejectReason==0x0002)
- Size
2 byte(s)
- Range
- remoteCID
- Condition
( CmdRejectReason==0x0002)
- Size
2 byte(s)
- Range
L2CAP_ConnectReq¶
- Opcode
0x0494
- Event Description
This Connection Request event is sent to the application since the application has wished to perform its own security verification (configured at PSM registration). After receiving a Connection Request, the application must respond back with a Connection Response (L2CAP_ConnectRsp) command indicating the outcome of the connection request.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- id
Identifier to match responses with requests (i.e., id to send back with L2CAP Connect Response command)
- Condition
( bStatus==0x00)
- Size
1 byte(s)
- Range
- PSM
Local PSM receiving connect request
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- sourceCID
Represents CID on device sending connect request and receiving connect response (i.e., peer CID)
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- MTU
Specifies maximum SDU size that can be received on this channel on the peer device
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- MPS
Specifies maximum payload size that can be received on this channel on the peer device
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- initialCredits
Indicates number of LE-frames that peer device can receive on this channel
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
L2CAP_ConnParamUpdateRsp¶
- Opcode
0x0493
- Event Description
This Connection Parameter Update Response is sent from the LE master device to the LE slave device. This response is sent by the master Host when it receives a Connection Parameter Update Request packet.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- result
Result of the update.
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
Value
Description
0x0000
CONN_PARAMS_ACCEPTED
0x0001
CONN_PARAMS_REJECTED
L2CAP_ChannelEstablished¶
- Opcode
0x04E0
- Event Description
This Channel Established Event is generated when a Connection Oriented Channel has been established with the peer device. If result is successful (0x0000) then all other fields of the event will be present and can be accessed.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- result
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
Value
Description
0x0000
L2CAP_CONN_SUCCESS
0x0001
Reserved
0x0002
L2CAP_CONN_PSM_NOT_SUPPORTED
0x0003
Reserved
0x0004
L2CAP_CONN_NO_RESOURCES
0x0005
L2CAP_CONN_INSUFFICIENT_AUTHEN
0x0006
L2CAP_CONN_INSUFFICIENT_AUTHOR
0x0007
L2CAP_CONN_INSUFFICIENT_KEY_SIZE
0x0008
L2CAP_CONN_INSUFFICIENT_ENCRYPT
0x0009
L2CAP_CONN_INVALID_SRC_CID
0x000A
L2CAP_CONN_SRC_CID_ALREADY_ALLOC
- PSM
Local PSM that channel belongs to
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- CID
Local Channel ID
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- MTU
Maximum SDU size that can be received by the local device on this channel
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- MPS
Maximum payload size that can be received by the local device
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- credits
Number of LE-frames that the local device can send
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- peerCID
Remote Channel ID
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- peerMTU
Maximum SDU size that can be received by the peer device
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- peerMPS
Maximum payload size that can be received by the peer device
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- peerCredits
Number of LE-frames that the peer device can send
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
- peerCreditThreshold
Low threshold for the peer credit count
- Condition
( bStatus==0x00 resultValue==0x0000)
- Size
2 byte(s)
- Range
L2CAP_ChannelTerminated¶
- Opcode
0x04E1
- Event Description
This Channel Terminated Event is generated when a Connection Oriented Channel has been terminated between the local and the peer device.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- CID
Local Channel ID
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- peerCID
Remote Channel ID
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
- reason
Reason Channel was termianted
- Condition
( bStatus==0x00)
- Size
2 byte(s)
- Range
Value
Description
0x0000
L2CAP_TERM_LINK_DOWN
0x0001
L2CAP_TERM_BY_PSM
0x0002
L2CAP_TERM_BY_PEER_PSM
0x0003
L2CAP_TERM_MAX_CREDIT_EXCEED
0x0004
L2CAP_TERM_SDU_LEN_EXCEED
0x0005
L2CAP_TERM_PSM_MTU_EXCEED
0x0006
L2CAP_TERM_RX_PKT_NO_CREDIT
0x0007
L2CAP_TERM_RX_ERROR
0x0008
L2CAP_TERM_TX_ERROR
0x0009
L2CAP_TERM_MEM_ALLOC_ERROR
L2CAP_OutOfCredit¶
- Opcode
0x04E2
- Event Description
This Out Of Credit Event is generated when a Connection Oriented Channel runs out of credits needed to transmit an SDU to the peer device.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- CID
Local Channel ID
- Size
2 byte(s)
- Range
- peerCID
Remote Channel ID
- Size
2 byte(s)
- Range
- creditsNeeded
Number of credits needed to transmit the remaining part of the current SDU
- Size
2 byte(s)
- Range
L2CAP_PeerCreditThreshold¶
- Opcode
0x04E3
- Event Description
This Peer Credit Threshold Event is generated when an L2CAP Connection Oriented Channel reaches a low threshold specified for the peer credit count (configured at PSM registration).
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- CID
Local Channel ID
- Size
2 byte(s)
- Range
- peerCID
Remote Channel ID
- Size
2 byte(s)
- Range
- peerCreditThreshold
Low threshold for the peer credit count
- Size
2 byte(s)
- Range
L2CAP_SendSduDone¶
- Opcode
0x04E4
- Event Description
This Send SDU Done Event is generated when the transmission of an SDU is completed on a Connection Oriented Channel established with the peer device.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- CID
Local Channel ID
- Size
2 byte(s)
- Range
- credits
Remaining local credits
- Size
2 byte(s)
- Range
- peerCID
Remote Channel ID
- Size
2 byte(s)
- Range
- peerCredits
Remaining peer credits
- Size
2 byte(s)
- Range
- totalLen
Total length of the SDU being transmitted
- Size
2 byte(s)
- Range
- txLen
Total number of octets transmitted
- Size
2 byte(s)
- Range
L2CAP_SendData¶
- Opcode
0x04F0
- Event Description
This Data Event is generated when an SDU is received on a Connection Oriented Channel from the peer device.
Event Parameters
- Status
- Size
1 byte(s)
- Range
Value
Description
0x00
SUCCESS
0x12
bleIncorrectMode
0x02
INVALIDPARAMETER
- connectionHandle
Connection handle of the link
- Size
2 byte(s)
- Range
Any 2 byte value
- CID
Local Channel ID
- Size
2 byte(s)
- Range
- len
Total length of the SDU being received
- Size
2 byte(s)
- Range
- SDU
Received SDU
- Size
payloadLen byte(s)
- Range