BLE UART Write Fails with "Unknown system firmware error: 261" on ESP32-S3

[bobricius]

CircuitPython version and board name

Board: espressif_esp32s3_devkitc_1_n8r8
Frequency: 240000000
(sysname='ESP32S3', nodename='ESP32S3', release='10.0.3', version='10.0.3 on 2025-10-17', machine='ESP32-S3-DevKitC-1-N8R8 with ESP32S3')

Code/REPL

"""
Minimal test case to reproduce BLE UART write error 261 on ESP32-S3
This script attempts to connect to a BLE UART device and write data.
"""

import time
from adafruit_ble import BLERadio
from adafruit_ble.advertising.standard import ProvideServicesAdvertisement
from adafruit_ble.services.nordic import UARTService

# Configuration
TARGET_MAC = "EA:85:F9:AB:62:24"  # Replace with your device MAC
BLE_PIN = "680044"  # Replace if different

print("=" * 60)
print("BLE UART Write Error Reproducer")
print("=" * 60)
print(f"Target MAC: {TARGET_MAC}")
print(f"BLE PIN: {BLE_PIN}")
print()

# Initialize BLE
ble = BLERadio()
#print(f"Local BLE Address: {ble.address_bytes.hex(':').upper()}")
print()

connection = None
uart_service = None

try:
    # Scan for BLE devices
    print("Scanning for BLE devices with UART service (15s)...")
    
    for advertisement in ble.start_scan(ProvideServicesAdvertisement, timeout=15):
        addr = ":".join([f"{b:02X}" for b in advertisement.address.address_bytes])
        
        if UARTService in advertisement.services:
            print(f"Found UART device: {advertisement.complete_name or 'Unknown'} ({addr})")
            
            # Connect to target or first UART device found
            if addr.upper() == TARGET_MAC.upper() or TARGET_MAC == "AA:BB:CC:DD:EE:FF":
                print(f"Connecting to: {addr}")
                connection = ble.connect(advertisement)
                print("✓ Connected!")
                break
    
    ble.stop_scan()
    
    if not connection:
        print("ERROR: No UART device found")
        print("Please update TARGET_MAC with your device address")
        exit(1)
    
    # Get UART service
    print("\nGetting UART service...")
    uart_service = connection[UARTService]
    print("✓ UART service obtained")
    
    # Print basic service info
    print(f"\nUART Service: {uart_service}")
    print(f"Service type: {type(uart_service)}")
    
    # Attempt to write data - THIS SHOULD FAIL WITH ERROR 261
    print("\nAttempting to write 2 bytes to UART...")
    test_data = bytes([0x16, 0x07])  # CMD_DEVICE_QUERY + version
    print(f"Data to write: {test_data.hex(' ').upper()}")
    
    uart_service.write(test_data)  # <-- ERROR OCCURS HERE
    
    # If we reach here, write succeeded
    print("✓ Write succeeded (unexpected!)")
    
except Exception as e:
    print(f"\n{'='*60}")
    print(f"ERROR CAUGHT:")
    print(f"{'='*60}")
    print(f"Exception Type: {type(e).__name__}")
    print(f"Exception Message: {e}")
    print()

Behavior

============================================================
BLE UART Write Error Reproducer

Target MAC: EA:85:F9:AB:62:24
BLE PIN: 680044

Scanning for BLE devices with UART service (15s)...
Found UART device: Unknown (EA:85:F9:AB:62:24)
Connecting to: EA:85:F9:AB:62:24
✓ Connected!

Getting UART service...
✓ UART service obtained

UART Service: <UARTService object at 0x3c1ba8e0>
Service type: <class 'UARTService'>

Attempting to write 2 bytes to UART...
Data to write: 16 07

============================================================
ERROR CAUGHT:

Exception Type: BluetoothError
Exception Message: Unknown system firmware error: 261

Description

Hi, experimenting with BLE

When attempting to write data to a BLE UART service on ESP32-S3 using CircuitPython, the write operation consistently fails with error code 261

What does error code 261 mean in the ESP32 BLE stack?
Is there a known issue with BLE UART writes on ESP32-S3?
Are there any required permissions or characteristics properties that might be missing?

Thanks

Additional information

No response