Merge branch 'feat/ble-adapter-option' into 'master'

provision: Add --ble_adapter CLI option for selecting HCI adapter

See merge request app-frameworks/esp-rainmaker-cli!98

Author: shahpiyushv

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All major changes to ESP RainMaker CLI will be documented in this file.
 
+## [Unreleased]
+### Added
+- `--ble_adapter` option for the `provision` command to select the HCI adapter used for BLE transport (default: `hci0`). Useful with `vhci_bridge` for emulated devices, e.g. `--ble_adapter hci1`. Linux/BlueZ only.
+
 ## [1.14.1] - 05-Jun-2026
 ### Bugfixes
 - Security 2 fixes across provisioning and local control:

docs/commands/provisioning.md

@@ -28,6 +28,7 @@ esp-rainmaker-cli provision [--pop <pop>] [options]
 - `--transport <mode>`: Communication method (softap, ble, console, on-network)
 - `--sec_ver <version>`: Security scheme (0, 1, or 2)
 - `--qrcode <json>`: QR code payload as JSON string (extracts transport, device_name, and pop)
+- `--ble_adapter <name>`: HCI adapter to use for BLE transport (default: `hci0`). Useful with `vhci_bridge` for emulated devices, e.g. `--ble_adapter hci1`. Linux/BlueZ only; ignored on macOS/Windows.
 
 ### Transport Modes
 
@@ -193,6 +194,15 @@ esp-rainmaker-cli provision --pop abcd1234 \
   --passphrase "MyWiFiPassword"
 ```
 
+### BLE Provisioning with a Specific HCI Adapter
+```bash
+# Target a non-default adapter (e.g. hci1 from vhci_bridge for emulated devices)
+esp-rainmaker-cli provision --pop abcd1234 \
+  --transport ble \
+  --device_name PROV_d76c30 \
+  --ble_adapter hci1
+```
+
 ### SoftAP Provisioning with Security 2
 ```bash
 # Use advanced security with username/password

rainmaker/rainmaker.py

@@ -564,6 +564,12 @@ def main():
                                   help='Metadata as JSON string to attach during node mapping\n'
                                        '(e.g., \'{"serial_no": "abc123", "region": "us"}\')')
 
+    provision_parser.add_argument('--ble_adapter',
+                                  type=str,
+                                  default='hci0',
+                                  help='HCI adapter to use for BLE transport (default: hci0).\n'
+                                       'Useful with vhci_bridge for emulated devices, e.g. --ble_adapter hci1')
+
     add_profile_argument(provision_parser)
     provision_parser.set_defaults(func=provision)
 

rmaker_cmd/provision.py

@@ -244,7 +244,8 @@ def provision(vars=None):
                 no_wifi=no_wifi,
                 disable_chal_resp=disable_chal_resp,
                 tags=mapping_tags,
-                metadata=mapping_metadata
+                metadata=mapping_metadata,
+                ble_adapter=vars.get('ble_adapter', 'hci0')
             )
         except RuntimeError as claim_err:
             # Handle claim requirement error specifically

rmaker_tools/common/transport/ble_cli.py

@@ -58,7 +58,7 @@ async def connect(self, devname, iface, chrc_names, fallback_srv_uuid):
 
         print('Discovering...')
         try:
-            discovery = await bleak.BleakScanner.discover(return_adv=True)
+            discovery = await bleak.BleakScanner.discover(return_adv=True, adapter=iface)
             devices = list(discovery.values())
         except bleak.exc.BleakDBusError as e:
             if str(e) == '[org.bluez.Error.NotReady] Resource Not Ready':
@@ -92,7 +92,7 @@ async def connect(self, devname, iface, chrc_names, fallback_srv_uuid):
                 if select != 0:
                     break
 
-                discovery = await bleak.BleakScanner.discover(return_adv=True)
+                discovery = await bleak.BleakScanner.discover(return_adv=True, adapter=iface)
                 devices = list(discovery.values())
 
             self.devname = devices[select - 1][0].name
@@ -115,7 +115,7 @@ async def connect(self, devname, iface, chrc_names, fallback_srv_uuid):
             self.srv_uuid_adv = uuids[0]
 
         print('Connecting...')
-        self.device = bleak.BleakClient(found_device[0].address)
+        self.device = bleak.BleakClient(found_device[0].address, adapter=iface)
         await self.device.connect()
         # must be paired on Windows to access characteristics;
         # cannot be paired on Mac

rmaker_tools/common/transport/transport_ble.py

@@ -5,9 +5,11 @@
 from . import ble_cli
 from .transport import Transport
 
+DEFAULT_BLE_ADAPTER = 'hci0'
+
 
 class Transport_BLE(Transport):
-    def __init__(self, service_uuid, nu_lookup):
+    def __init__(self, service_uuid, nu_lookup, ble_adapter=DEFAULT_BLE_ADAPTER):
         # Store original endpoint IDs (e.g., 'ff54', 'ff55') for fallback calculation
         self.endpoint_ids = nu_lookup.copy()
         self.service_uuid = service_uuid
@@ -23,13 +25,15 @@ def __init__(self, service_uuid, nu_lookup):
             # Result: '0000ff54-0000-1000-8000-00805f9b34fb'
             self.fallback_lookup[name] = service_uuid[:4] + endpoint_id + service_uuid[8:]
 
+        self.ble_adapter = ble_adapter
+
         # Get BLE client module
         self.cli = ble_cli.get_client()
 
     async def connect(self, devname):
         # Use client to connect to BLE device and bind to service
         # Pass endpoint names (not UUIDs) for auto-discovery via user descriptors
-        if not await self.cli.connect(devname=devname, iface='hci0',
+        if not await self.cli.connect(devname=devname, iface=self.ble_adapter,
                                       chrc_names=self.endpoint_ids.keys(),
                                       fallback_srv_uuid=self.service_uuid):
             raise RuntimeError('Failed to initialize transport')

rmaker_tools/rmaker_local_ctrl/esp_prov.py

@@ -48,7 +48,7 @@ def get_security(secver, sec_patch_ver, username, password, pop='', verbose=Fals
     return None
 
 
-async def get_transport(sel_transport, service_name):
+async def get_transport(sel_transport, service_name, ble_adapter=transport.DEFAULT_BLE_ADAPTER):
     try:
         tp = None
         if (sel_transport in ['softap', 'httpd']):
@@ -65,7 +65,7 @@ async def get_transport(sel_transport, service_name):
             # will fallback to using the provided UUIDs instead
             nu_lookup = {'prov-session': 'ff51', 'prov-config': 'ff52', 'proto-ver': 'ff53'}
             tp = transport.Transport_BLE(service_uuid='021a9004-0382-4aea-bff4-6b3f1c5adfb4',
-                                         nu_lookup=nu_lookup)
+                                         nu_lookup=nu_lookup, ble_adapter=ble_adapter)
             await tp.connect(devname=service_name)
         elif (sel_transport == 'console'):
             tp = transport.Transport_Console()

rmaker_tools/rmaker_prov/esp_rainmaker_prov.py

@@ -164,7 +164,7 @@ def get_wifi_creds_from_scanlist(transport_mode, obj_transport,
 def provision_device(transport_mode, pop, userid, secretkey,
                      ssid=None, passphrase=None, security_version=None,
                      sec2_username='', sec2_password='', device_name=None, session=None, no_retry=False, no_wifi=False, disable_chal_resp=False,
-                     tags=None, metadata=None):
+                     tags=None, metadata=None, ble_adapter=esp_prov.transport.DEFAULT_BLE_ADAPTER):
     """
     Wi-Fi Provision a device
 
@@ -235,7 +235,7 @@ def provision_device(transport_mode, pop, userid, secretkey,
     else:
         service_name = None  # Use default for SoftAP (192.168.4.1:80)
 
-    obj_transport = esp_prov.get_transport(transport_mode, service_name)
+    obj_transport = esp_prov.get_transport(transport_mode, service_name, ble_adapter)
     if obj_transport is None:
         print("Establishing connection to node - Failed")
         return None

rmaker_tools/rmaker_prov/prov/prov_util.py

@@ -88,11 +88,12 @@ def get_sec_patch_ver(tp, verbose=False):
     except Exception:
         return 0
 
-def get_transport(sel_transport, service_name):
+def get_transport(sel_transport, service_name, ble_adapter=transport.DEFAULT_BLE_ADAPTER):
     """
     Get object of class `Transport` based on input parameters
     `sel_transport` - Transport Mode (softap/ble)
     `service_name` - Service Name to connect to
+    `ble_adapter` - HCI adapter name for BLE transport
     """
     try:
         tp = None
@@ -115,9 +116,10 @@ def get_transport(sel_transport, service_name):
             import inspect
             import asyncio
             sig = inspect.signature(transport.Transport_BLE.__init__)
-            if len(sig.parameters) == 3:  # self, service_uuid, nu_lookup
+            if len(sig.parameters) == 4:  # self, service_uuid, nu_lookup, ble_adapter
                 ble_transport = transport.Transport_BLE(service_uuid='0000ffff-0000-1000-8000-00805f9b34fb',
-                                                        nu_lookup=nu_lookup)
+                                                        nu_lookup=nu_lookup,
+                                                        ble_adapter=ble_adapter)
 
                 # Create sync wrapper for async transport
                 class SyncBLETransport: