Seeking Help on Game Controller Emulation Development

[typenoob]

I have implemented game controller emulation using BlueZ and now intend to achieve the same functionality via HCI sockets with Bumble. I originally thought there would be few differences between the two solutions, yet I have run into a tough issue that I cannot resolve.

I have attached two sets of btmon logs; the upper one is captured under BlueZ, and the lower one under Bumble. It is obvious that once Bumble receives the first data packet from the remote host, the remote device immediately initiates a disconnection. In contrast, stable connections can be established smoothly with BlueZ.

I noticed that BlueZ triggers Sniff mode entry and exit around the transmission and reception of the first data packet. Could this disconnection issue be related to Sniff mode behavior?

I sincerely hope experienced developers can offer guidance and solutions. Your help is highly appreciated.

[zxzxwu]

Analysis Report: Game Controller Emulation Disconnection Issue (Bumble Discussion #927)

This report analyzes the connection instability issue reported in Bumble Discussion #927, where an emulated game controller (targeting the Nintendo Switch) is immediately disconnected by the host after receiving the first data packet.

1. Log Comparison Analysis

Based on the btmon logs provided in the discussion, we compare the successful connection flow using BlueZ with the failed flow using Bumble.

Successful Connection Flow (BlueZ)

1. Connection & SDP: The connection is established, and SDP service discovery completes.
2. First Data: The emulated controller sends a HID Input Report:

   nxbt[387688]: < ACL Data TX: ... Channel: 67 len 50
       a1 30 a1 00...
   

3. Sniff Mode Transition (Critical): The host (Switch) immediately initiates and successfully transitions the connection into Sniff Mode (low-power mode):

   > HCI Event: Mode Change (0x14) plen 6
       Status: Success (0x00)
       Mode: Sniff (0x02)
       Interval: 15.000 msec (0x0018)
   

4. Host Request: While in Sniff Mode, the Switch sends a HID Output Report containing subcommand 0x02 (Request Device Info):

   > ACL Data RX: ... Channel: 65 len 50
       a2 01 02 00 00 00 00 00 00 00 00 02 00 00 00 00
   

5. Response & Exit Sniff: The controller replies to the subcommand and almost simultaneously requests to exit Sniff Mode back to Active Mode to transmit data:

   nxbt[387688]: < ACL Data TX: ... Channel: 67 len 50
       a1 21 ...
   < HCI Command: Exit Sniff Mode (0x02|0x0004) plen 2
   > HCI Event: Mode Change (0x14) plen 6
       Status: Success (0x00)
       Mode: Active (0x00)
   

   The connection remains stable after this.

Failed Connection Flow (Bumble)

1. Connection & L2CAP: The connection is established, and L2CAP channels are configured.
2. First Data: The controller sends the same HID Input Report:

   nxbt[386996]: < ACL Data TX: ... Channel: 81 len 54
       a1 30 ...
   

3. Missing Sniff Mode: Unlike BlueZ, there is no transition to Sniff Mode.
4. Host Request: The controller receives the HID Output Report from the Switch for subcommand 0x02:

   > ACL Data RX: ... Channel: 65 len 54
       a2 01 01 00 00 00 00 00 00 00 00 02 00 00 00 00
   

5. Immediate Disconnection: Just 65 milliseconds after sending the output report, the Switch immediately initiates a disconnection:

   > ACL Data RX: ... Channel: 65 len 12
       L2CAP: Disconnection Request (0x06) ident 8 len 4
       Destination CID: 65
       Source CID: 81
   

---

2. Root Cause Analysis

The Nintendo Switch has strict power management policies for its wireless controllers. It aggressively requires controllers to enter Sniff Mode shortly after connection to conserve battery.

• Why it works in BlueZ: During adapter initialization, the BlueZ daemon (bluetoothd) automatically configures the hardware controller's default link policy by sending the HCI_Write_Default_Link_Policy_Settings command with a value of 0x0005 (enabling Role Switch and Sniff Mode):

  < HCI Command: Write Default Link... (0x02|0x000f) plen 2
      Link policy: 0x0005
        Enable Role Switch
        Enable Sniff Mode
  

  When the Switch requests to enter Sniff Mode (via LMP layer negotiation), the controller hardware automatically accepts it because the host (BlueZ) has allowed it.

• Why it fails in Bumble: Bumble interacts directly with the HCI socket and does not automatically configure Link Policy settings by default. If the Bluetooth dongle's hardware default is to disable Sniff Mode, the controller will reject the Switch's request to enter Sniff Mode. Consequently, the Switch immediately disconnects the controller for failing to meet its protocol requirements.

---

3. Solution

To resolve this issue, the Bumble application must explicitly configure the adapter's default link policy to enable Sniff Mode during initialization.

Code Example

You can send the HCI_Write_Default_Link_Policy_Settings_Command using the Bumble API after the device is started:

from bumble.hci import HCI_Write_Default_Link_Policy_Settings_Command

async def initialize_device(device):
    # ... your existing device setup ...

    # Enable Role Switch (0x01) and Sniff Mode (0x04) -> 0x0005
    print("Configuring default link policy to enable Sniff Mode...")
    await device.send_command(
        HCI_Write_Default_Link_Policy_Settings_Command(
            default_link_policy_settings=0x0005
        )
    )
    
    # ... proceed with connection ...

Implementing this configuration allows the emulated controller to successfully negotiate Sniff Mode with the Nintendo Switch, resolving the premature disconnection.

[typenoob]

Cheers! Finally it successfully sends a button input.

So BlueZ just has a suitable default link policy that matches the Switch's behavior, right?

[typenoob]

I might have questions about reconnection issues tomorrow. Anyway, I’ve successfully established the first connection with unbonded devices now. Thank you so much.

[typenoob]

In BlueZ, I have following code to reconnect from a disconnected socket.

    def reconnect(self, reconnect_address) -> tuple:
        ctrl = socket.socket(
            family=socket.AF_BLUETOOTH,
            type=socket.SOCK_SEQPACKET,
            proto=socket.BTPROTO_L2CAP,
        )
        itr = socket.socket(
            family=socket.AF_BLUETOOTH,
            type=socket.SOCK_SEQPACKET,
            proto=socket.BTPROTO_L2CAP,
        )

        addresses = (
            reconnect_address
            if isinstance(reconnect_address, list)
            else [reconnect_address]
        )

        for address in addresses:
            try:
                ctrl.connect((address, 17))
                itr.connect((address, 19))
                return itr, ctrl
            except OSError:
                pass

        itr.close()
        ctrl.close()
        raise OSError(
            "Unable to reconnect to sockets at the given address(es)",
            reconnect_address,
        )

Is there any approach to do so in Bumble?

[zxzxwu]

In Bumble, reconnecting L2CAP channels is different from BlueZ (which uses system-level sockets). Bumble is an asynchronous framework that implements the Bluetooth stack entirely in user space.

To implement a similar reconnection logic in Bumble, you need to:

1. Establish a BR/EDR ACL connection first to get a Connection object.
2. Use that Connection object to asynchronously create the L2CAP channels (Control and Interrupt).

Here is an example of how you can implement the reconnection logic in Bumble, corresponding to your BlueZ code:

from bumble.device import Device
from bumble.core import PhysicalTransport
from bumble.l2cap import ClassicChannelSpec
from bumble.core import ProtocolError

async def reconnect(device: Device, reconnect_address: str) -> tuple:
    try:
        # 1. Establish BR/EDR ACL connection
        # This corresponds to the underlying HCI Connection Setup
        connection = await device.connect(
            reconnect_address, 
            transport=PhysicalTransport.BR_EDR
        )
        
        # 2. Create L2CAP channels (PSM 17: Control, PSM 19: Interrupt)
        # create_l2cap_channel will asynchronously wait for the channel to be established.
        # It raises ProtocolError if the connection fails.
        ctrl_channel = await connection.create_l2cap_channel(
            spec=ClassicChannelSpec(psm=17)
        )
        itr_channel = await connection.create_l2cap_channel(
            spec=ClassicChannelSpec(psm=19)
        )
        
        return itr_channel, ctrl_channel
        
    except (ProtocolError, Exception) as e:
        # Handle connection failure (e.g., timeout or protocol error)
        raise OSError(f"Unable to reconnect to sockets at the given address: {reconnect_address}") from e

Key Differences from BlueZ (Sockets):

1. Asynchronous Mechanism (async/await): Bumble's APIs are mostly asynchronous. Therefore, the reconnection function itself must be defined as async def, and you need to use await when calling connection methods.
2. Data Transmission (Reactive/Push Model):
   • Bumble's L2CAP channels do not use blocking recv() or send() methods.
   • Receiving Data: You need to set a sink property (callback function) on the channel. Bumble will automatically call it when new data arrives.

     def on_ctrl_data(pdu: bytes):
         # Process received Control channel data
         print(f"Received control PDU: {pdu.hex()}")
     
     ctrl_channel.sink = on_ctrl_data

   • Sending Data: Use the write() method of the channel object.

     ctrl_channel.write(data)

3. Disconnection:
   • Disconnect a specific channel: await ctrl_channel.disconnect()
   • Disconnect the entire ACL connection: await connection.disconnect()

You can refer to the built-in bumble/hid.py module in Bumble. The HID class therein demonstrates how to manage l2cap_ctrl_channel and l2cap_intr_channel creation, data transmission (on_ctrl_pdu / on_intr_pdu), and disconnection.

[typenoob]

Unfortunately, I encountered an error —— hci/CONNECTION_ALREADY_EXISTS_ERROR [0xB].
It's strange that peer disconnected the connection but connection is still exists in the device.

[zxzxwu]

@typenoob This error hci/CONNECTION_ALREADY_EXISTS_ERROR [0xB] (HCI Error Code 0x0B: Connection Already Exists) indicates that the Bluetooth controller (dongle/chip) believes that the connection to that peer address is still active, or there is a connection attempt currently in progress.

This is a common phenomenon in Bluetooth development, especially when a peer device disconnects abnormally (e.g., sudden power loss, going out of range, or software crash).

Why does this happen?

When a peer device disappears without sending a standard disconnection signal (LMP_detach), the local Bluetooth controller does not know immediately. The controller must wait for the Link Supervision Timeout (typically 5 to 20 seconds by default) to expire before it confirms that the link is lost. Once it expires, the controller sends an HCI_Disconnection_Complete_Event to the Host (Bumble) to release the resources.

Before the controller releases these resources, if you immediately try to call device.connect(), the controller will reject the command and return CONNECTION_ALREADY_EXISTS_ERROR.

---

Solution and Workarounds

In Bumble, you can handle and troubleshoot this issue using the following approaches:

1. Check and Force Clean Bumble's Internal Connection State

Sometimes the peer has disconnected physically, but Bumble's internal state is not yet cleaned up. Before reconnecting, you can check if a Connection object for that address still exists in Bumble, and explicitly call disconnect() to clean up the state on both the Host and Controller:

from bumble.hci import Address

# Check if a connection to this address already exists
# Note: Ensure the Address type matches your transport (e.g., PUBLIC_DEVICE_ADDRESS)
peer_addr = Address(reconnect_address)
existing_connection = device.find_connection_by_bd_addr(peer_addr)

if existing_connection:
    print("Found an existing connection object in Bumble, attempting to disconnect/clean up...")
    try:
        # Explicitly disconnect to clear the state (sends HCI Disconnect to the controller)
        await existing_connection.disconnect()
    except Exception as e:
        print(f"Force disconnect failed (likely the physical link is already gone): {e}")

2. Ensure Proper Listening to the disconnection Event

It is not recommended to trigger a reconnection immediately when a socket error is detected. The best practice is to listen to the disconnection event on the Connection object, and trigger the reconnection logic only after this event is fired (which guarantees that Bumble has finished cleaning up):

def on_disconnection(reason):
    print(f"Connection fully released, reason code: {reason}")
    # Safe to trigger reconnection logic here
    asyncio.create_task(reconnect(device, reconnect_address))

connection.on('disconnection', on_disconnection)

3. Implement a Backoff and Retry Mechanism

If the peer disconnected abnormally, the controller needs time (waiting for the Supervision Timeout) to realize it. If your reconnection logic encounters a 0x0B error, you should implement a backoff and retry mechanism:

import asyncio
from bumble.core import ConnectionError
from bumble.hci import HCI_CONNECTION_ALREADY_EXISTS_ERROR

async def reconnect_with_retry(device, address, max_retries=5, delay=2.0):
    for attempt in range(max_retries):
        try:
            return await reconnect(device, address)
        except ConnectionError as e:
            if e.error_code == HCI_CONNECTION_ALREADY_EXISTS_ERROR:
                print(f"Controller hasn't released the connection yet (0x0B), retrying in {delay}s... (Attempt {attempt + 1}/{max_retries})")
                await asyncio.sleep(delay)
                delay *= 1.5  # Exponential backoff
            else:
                raise e
    raise OSError("Reconnection failed: Controller timed out waiting for connection release")

4. Shorten the Link Supervision Timeout

If you have control over the connection parameters (typically when acting as Central/Master), you can set a shorter Link Supervision Timeout (e.g., 2-3 seconds) after the connection is established. This allows the controller to detect abnormal disconnections much faster, thereby reducing the waiting time before you can reconnect.

[typenoob]

Another question: what is the detail meaning of L2CAP ERROR——Connection refused – no resources available?
There's little information about that on Internet

[zxzxwu]

In the L2CAP protocol, Connection refused – no resources available (error code 0x0004) is a standard L2CAP connection response result.

According to the Bluetooth Core Specification, it indicates that the remote device (which received the connection request) rejected the L2CAP channel establishment because it ran out of resources.

In the context of L2CAP, "no resources available" typically refers to the following situations:

1. Service/PSM Limits (Most Common Reason)

Many Bluetooth services (identified by PSM) are designed to allow only a single active connection.

• For example, your game controller emulation uses HID services (PSM 17: Control, PSM 19: Interrupt). A HID device usually only allows one active connection to a HID Host (e.g., Nintendo Switch) at a time.
• If the remote host (Switch) believes that the previous connection is not fully released yet, when you try to establish new L2CAP channels, the Switch will reject them with "no resources available" because the unique HID service slot is still "occupied".

2. Max Channel Limits

The device has reached the maximum number of simultaneous L2CAP channels allowed by the stack. If old channels are not closed before opening new ones, the channel resources will be exhausted.

3. Memory/Buffer Exhaustion

The device does not have enough dynamic memory (RAM) or controller buffer space to allocate for the MTU (Maximum Transmission Unit) of the new channel.

---

Why does this happen in your scenario?

This error has a direct causal relationship with the CONNECTION_ALREADY_EXISTS_ERROR [0xB] error you encountered earlier:

1. Ghost Channels are Still Active: When the connection drops abnormally, if the Switch has not triggered the Link Supervision Timeout yet, in the Switch's stack, the old ACL connection and the old L2CAP channels (PSM 17/19) are still considered active.
2. New Requests are Rejected: If you try to establish new L2CAP channels immediately, the Switch detects that "there is already a HID controller connected" and determines there are no extra resources for a new one, thus returning Connection refused – no resources available.

Recommendation:

This further confirms that you should not reconnect immediately upon detecting socket exceptions. You must wait for both the local and remote devices to confirm that the old connection has been fully released (triggering the disconnection event), or implement a retry-with-delay mechanism in your reconnection logic to give the Switch enough time to timeout and release the old channel resources.

[zxzxwu]

I suggest you to get answers from some AI tools like Antigravity, Codex or Claude Code first. I used Antigravity CLI to answer all the questions here.

[typenoob]

Well, since AI tools cannot help me out, it even give me some confusing information, I'm here to seek here.

I'm not really understanding why NO_RESOURCES_AVAILABLE in Bumble when trying to reconnect the L2CAP channel. It works in BlueZ...

[zxzxwu]

It will be helpful to provide snoop or BUMBLE_LOGLEVEL=DEBUG logs to both us and agents. Installing tshark (wireshark cli) and add a skill to parse snoop or pacp logs will be helpful.

Error code NO_RESOURCES_AVAILABLE is just an indicator that remote device has no resource, but it doesn't define what is the resource missing. Since you cannot see the log on the remote side, the only thing you can do is probably to compare logs between BlueZ and Bumble and see what's the difference.

[typenoob]

The only noticeable difference would be

      L2CAP: Connection Response (0x03) ident 3 len 8
        Destination CID: 73
        Source CID: 64
        Result: Connection refused - no resources available (0x0004)
        Status: No further information available (0x0000)

      L2CAP: Connection Response (0x03) ident 8 len 8
        Destination CID: 81
        Source CID: 64
        Result: Connection successful (0x0000)
        Status: No further information available (0x0000)

[typenoob]

bluez.log
bumble.log
bumble.log
bluez.log

[zxzxwu]

Here is the analysis of the logs you provided (bluez.log and bumble.log).

Analysis Report: Bumble L2CAP Reconnection Failure Issue

1. Issue Overview

The reconnection attempt receives an L2CAP connection response error: Connection refused - no resources available (0x0004) when using Bumble, but succeeds smoothly when using BlueZ.

Comparing bluez.log and bumble.log reveals the root cause.

2. Log Comparison Analysis

Failed Reconnection Flow (Bumble)

1. Disconnection: The Host (Switch) initiates L2CAP disconnection, closing both the Interrupt channel (CID 65) and the Control channel (CID 64).
2. Reconnection Attempt: About 380ms later, the emulated controller (nxbt) initiates a new L2CAP connection request:

   L2CAP: Connection Request (0x02) ident 3 len 4
     PSM: 19 (0x0013)  <-- This is the Interrupt PSM
     Source CID: 64
   

   Note: Bumble only sends a connection request for PSM 19 (Interrupt Channel).
3. Host Rejection: The Host immediately rejects the connection:

   L2CAP: Connection Response (0x03) ident 3 len 8
     Result: Connection refused - no resources available (0x0004)
   

Successful Reconnection Flow (BlueZ)

1. Disconnection: Similarly, the Host closes the L2CAP channels.
2. Reconnection Attempt: About 358ms later, BlueZ initiates reconnection.
3. Control Channel First: BlueZ first sends a connection request for PSM 17 (Control Channel):

   L2CAP: Connection Request (0x02) ident 8 len 4
     PSM: 17 (0x0011)  <-- This is the Control PSM
   

   The Host responds with Connection successful and configuration completes.
4. Interrupt Channel Second: After the Control channel is established, BlueZ then sends a connection request for PSM 19 (Interrupt Channel):

   L2CAP: Connection Request (0x02) ident 10 len 4
     PSM: 19 (0x0013)
   

   The Host responds with Connection successful.

3. Root Cause Analysis

The root cause is that the order of L2CAP channel establishment violates the Bluetooth HID Specification.

According to the Bluetooth HID Profile Specification v1.1.1 (Section 5.2 Connection Establishment):

"A connection consists of two L2CAP channels: the Control channel and the Interrupt channel. The Control channel shall be established first. Once the Control channel is established, the Interrupt channel may be established."

• BlueZ Behavior: Compliant. It connects PSM 17 (Control) first, and then PSM 19 (Interrupt) after the control channel is ready.
• Bumble/Application Behavior: Non-compliant. It attempts to connect PSM 19 (Interrupt) directly without establishing PSM 17 (Control) first. The Switch rejects the Interrupt channel because there is no active Control channel associated with the device, returning no resources available.

Why does this happen in Bumble?

Bumble's bumble/hid.py Device class provides independent connect_control_channel() and connect_interrupt_channel() methods but does not provide a high-level connect() helper that automatically coordinates the two.

Consequently, the connection order is entirely up to the application using Bumble (e.g., the Bumble backend implementation in nxbt). If the application misses the Control channel connection step during reconnection, it leads to this failure.

4. Solutions

Solution A: Fix the Application Reconnection Logic

Ensure that the application using Bumble connects the channels in the correct order:

# 1. Connect Control Channel first
await hid_device.connect_control_channel()

# 2. Connect Interrupt Channel only after Control is connected
await hid_device.connect_interrupt_channel()

Solution B: Improve Bumble's HID implementation (Suggested)

To prevent other developers from running into this:

1. Add guard check in connect_interrupt_channel:
   Verify that the control channel is already established before attempting to connect the interrupt channel.

   async def connect_interrupt_channel(self) -> None:
       if not self.connection:
           raise InvalidStateError("Connection is not established!")
       if not self.l2cap_ctrl_channel:
           raise InvalidStateError("Control channel must be established before interrupt channel!")
       # ... proceed ...

2. Provide a unified connect() helper in the HID base class:

   async def connect(self) -> None:
       await self.connect_control_channel()
       await self.connect_interrupt_channel()

[zxzxwu]

BTW we may have an HID refactor in the future, but I am still cleaning some blockers.

[typenoob]

Oh, I missed that. I never thought HID has such restrict rule.

Sorry but I genuinely don't have a agent as clever as yours.

[typenoob]

Finally, it works. Though it currently only works in hci-socket:0 not in usb:0.

Thank you very very much !!!