Connectivity:STM32WB-WBA Connection Oriented Channel – COC

1. STM32WB-WBA - Connection Oriented Channel

A Connection Oriented Channel - COC allows the exchange of Bluetooth^® Low Energy data at L2CAP layer without GATT layer. There is no notion of client/server, only central and peripheral.
To set a COC logical link, it is necessary to establish first a Bluetooth^® Low Energy link. Over this Bluetooth^® Low Energy link, one or several COCs can be established.
The central or the peripheral may be a COC initiator.

Information

The number of COC links (Channel_Number parameter) must be taken into account in the number of links defined in app_conf.h file, see CFG_BLE_NUM_LINK define.

Bluetooth® LE architecture

1.1. General L2CAP terminology

Bluetooth® LE General L2CAP terminology

Term Description L2CAP channel The logical connection between two endpoints in peer devices, characterized by their Channel Identifiers (CIDs) SDU or L2CAP SDU Service Data Unit: a packet of data that L2CAP exchanges with the upper layer and transports transparently over an L2CAP channel PDU or L2CAP PDU Protocol Data Unit: a packet of data containing L2CAP protocol information fields, control information, and/or upper layer information data Maximum Transmission Unit (MTU) The maximum size of payload data, in octets, that the upper layer entity can accept (that is, the MTU corresponds to the maximum SDU size) Maximum PDU Payload Size (MPS) The maximum size of payload data in octets that the L2CAP layer entity can accept (that is, the MPS corresponds to the maximum PDU payload size)

2. L2CAP COC commands and events overview

2.1. L2CAP COC establishment

ACI_L2CAP_COC_CONNECT : This command sends a Credit Based Connection Request packet on the specified connection.

L2CAP COC connect command

Parameter Description Connection_Handle Connection handle for which the command applies SPSM Simplified Protocol/Service Multiplexer MTU Maximum Transmission Unit MPS Maximum Payload Size (in octets) Initial_Credits Number of K-frames that can be received on the created channel(s) by the L2CAP layer entity sending this packet Channel_Number Number of channels to be created. If this parameter is set to 0, it requests the creation of one LE credit based connection-oriented channel. Otherwise, it requests the creation of one or more enhanced credit based connection-oriented channels.

ACI_L2CAP_COC_CONNECT_EVENT : This event is generated when receiving a valid Credit Based Connection Request packet.

L2CAP COC connect event

Parameter Description Connection_Handle Handle of the connection where this event occurred SPSM Simplified Protocol/Service Multiplexer MTU Maximum Transmission Unit MPS Maximum Payload Size (in octets) Initial_Credits Number of K-frames that can be received on the created channel(s) by the L2CAP layer entity sending this packet Channel_Number Number of channels to be created. If this parameter is set to 0, it requests the creation of one LE credit based connection-oriented channel. Otherwise, it requests the creation of one or more enhanced credit based connection-oriented channels.

ACI_L2CAP_COC_CONNECT_CONFIRM : This command sends a Credit Based Connection Response packet. It must be used upon reception of a connection request through an ACI_L2CAP_COC_CONNECT_EVENT event.

L2CAP COC connect confirm command

Parameter Description Connection_Handle Connection handle for which the command applies MTU Maximum Transmission Unit MPS Maximum Payload Size (in octets) Initial_Credits Number of K-frames that can be received on the created channel(s) by the L2CAP layer entity sending this packet Result This parameter indicates the outcome of the request. A value of 0x0000 indicates success while a non-zero value indicates the request is refused.

ACI_L2CAP_COC_CONNECT_CONFIRM_EVENT : This event is generated when receiving a valid Credit Based Connection Response packet.

L2CAP COC connect confirm event

Parameter Description Connection_Handle Handle of the connection where this event occurred MTU Maximum Transmission Unit MPS Maximum Payload Size (in octets) Initial_Credits Number of K-frames that can be received on the created channel(s) by the L2CAP layer entity sending this packet Result This parameter indicates the outcome of the request. A value of 0x0000 indicates success while a non-zero value indicates the request is refused. Channel_Number Number of created channels (length of Channel_Index_List) Channel_Index_List List of channel indexes for which the primitive applies

• MTU frames are fragmented into K-frames of MPS size at application level on transmitter side.
  
• MTU frames are reassembled at application level on receiver side.
  
• Initial Credits are handled at application level once they have been exchanged through both previous commands.
  

2.2. L2CAP COC data exchange

ACI_L2CAP_COC_TX_DATA : This command sends a K-frame packet on the specified connection-oriented channel.

L2CAP COC Tx Data command
Parameter Description Channel_Index Index of the connection-oriented channel for which the primitive applies Length Length of data (in octets) Data Information data

• Note: for the first K-frame of the SDU, the information data contains the L2CAP SDU length coded on two octets followed by the K-frame information payload. For the next K-frames of the SDU, the Information data only contains the K-frame information payload.
  
• When the command returns the error code BLE_STATUS_INSUFFICIENT_RESOURCES (0x64), the application needs to wait for the ACI_L2CAP_COC_TX_POOL_AVAILABLE_EVENT event. This event is generated as soon as there is a free buffer available for sending K-frames.
• The application must handle MTU length, fragmentation in K-frame, length of current transmitted frame, and credits number.
  

ACI_L2CAP_COC_RX_DATA_EVENT : This event is generated when receiving a valid K-frame packet on a connection-oriented channel.

L2CAP COC Rx Data event
Parameter Description Channel_Index Index of the connection-oriented channel for which the primitive applies Length Length of data (in octets) Data Information data

• The application must handle MTU length' received in first K-frame, K-frame number, length of current received frame,' and credits number.
  

2.3. L2CAP COC flow control

ACI_L2CAP_COC_FLOW_CONTROL : This command sends a Flow Control Credit signaling packet on the specified connection-oriented channel.

L2CAP COC Flow control command
Parameter Description Channel_Index Index of the connection-oriented channel for which the primitive applies Credits Number of credits the receiving device can increment, corresponding to the number of K-frames that can be sent to the peer device sending the Flow Control Credit packet.

ACI_L2CAP_COC_FLOW_CONTROL_EVENT : This event is generated when receiving a valid Flow Control Credit signaling packet.

L2CAP COC Flow control command
Parameter Description Channel_Index Index of the connection-oriented channel for which the primitive applies Credits Number of credits the receiving device can increment, corresponding to the number of K-frames that can be sent to the peer device sending the Flow Control Credit packet.

Information

The application must handle credits number on transmitter and receiver side.

2.4. L2CAP COC additional commands and events

• ACI_L2CAP_COC_RECONF : This command sends a Credit Based Reconfigure Request packet on the specified connection.
  
• ACI_L2CAP_COC_RECONF_CONFIRM : This command sends a Credit Based Reconfigure Response packet. It must be used upon receipt of a Credit Based Reconfigure Request through an ACI_L2CAP_COC_RECONF_EVENT event.
  
• ACI_L2CAP_COC_DISCONNECT : This command sends a Disconnection Request signaling packet on the specified connection-oriented channel. The ACI_L2CAP_COC_DISCONNECT_EVENT event is received when the disconnection of the channel is effective.
  
• ACI_L2CAP_COC_RECONF_EVENT : This event is generated when receiving a valid Credit Based Reconfigure Request packet.
  
• ACI_L2CAP_COC_RECONF_CONFIRM_EVENT : This event is generated when receiving a valid Credit Based Reconfigure Response packet.
  
• ACI_L2CAP_COC_DISCONNECT_EVENT : This event is generated when a connection-oriented channel is disconnected following an L2CAP channel termination procedure.
  

3. L2CAP COC example

3.1. Bluetooth^® LE connection and COC establishment initiated by the central

3.1.1. On central side

• Initiate a Bluetooth^® Low Energy link: send aci_gap_create_connection
• Wait for HCI_LE_CONNECTION_COMPLETE_EVENT
• Initiate a CoC connection: ACI_L2CAP_COC_CONNECT
• Wait for ACI_L2CAP_COC_CONNECT_CONFIRM_EVENT (get channel_index_list)

Range of channel_index_list for the COC initiator: from 0 to 0x1F

3.1.2. On peripheral side

• Start advertising: send aci_gap_set_discoverable
• Wait for HCI_LE_CONNECTION_COMPLETE_EVENT
• Wait for ACI_L2CAP_COC_CONNECT_EVENT
• Send ACI_L2CAP_COC_CONNECT_CONFIRM
• In hci_command_complete_event, get Channel_number and Channel_Index_List values

Range of channel_index_list for the COC peripheral: from 0x20 to 0x3F

3.2. COC data exchange

In following example, the purpose is to send a 300 bytes MTU.
As MPS is equal to 248, it takes 2 K-frames to send the entire MTU.
First K-frame contains the total SDU length in its first 2 bytes (0x2C, 0x01) little indian coded. Length field is equal to 248.
Second K-frame contains remaining data, length field is equal to 300 - (248-2) = 54 bytes.

L2CAP PDU frames

The receiver manages its own credit (Periph_Initial_Credits), MTU length, K-frame number, and length of current received frame.
When the entire MTU is received, the receiver can update and send its new credit using ACI_L2CAP_COC_FLOW_CONTROL command.

The transmitter manages MTU fragmentation, peer device credit (Periph_Initial_Credits), and resource availability to send K-frames.

3.2.1. On sender side

Used ACI_L2CAP_COC_TX_DATA (Channel_Index, length, data) to send data over L2CAP.

3.2.2. On receiver side

Recover the data through ACI_L2CAP_COC_RX_DATA_EVENT event.

3.3. Example of Bluetooth^® LE connection, COC establishment and data exchange

Bluetooth® Low Energy and COC link establishment

L2CAP COC data exchange

3.4. Code example

A STM32WB COC code example has been shared on STM32-Hotspot GitHub
A STM32WBA COC code example is available in STM32CubeWBA package, see BLE_SerialCom application and the following wiki page BLE_SerialCom.