flutter_blue_ultra_accessory_setup 0.0.4

Use it to discover and configure Bluetooth or Wi-Fi accessories with images and names provided by the app. Works on iOS 18 and above, and uses AccessorySetupKit through FFI.

Flutter Accessory Kit

At this stage the library supports:

• ✅ BLE
• ✅ WiFi
• ✅ Migration

‼️ iOS only. This library wraps Apple's AccessorySetupKit, which is an iOS-exclusive framework with no Android equivalent. It requires iOS 18 or above. ‼️

🚇 How to use

Install the library using the command line:

flutter pub add flutter_blue_ultra_accessory_setup

There is a standalone app in example that keeps AccessorySetupKit isolated from the regular flutter_blue_ultra scanner example. Use that app when testing the iOS picker flow.

⚙️ Setup

• For the full details refer apple docs

• You should add the keys to the Info.plist of the iOS app to make it work. ⚠️ If you miss the required key the app will crash when you show the picker. ⚠️

  • ALWAYS: (Bluetooth or WiFi, or both)

  <key>NSAccessorySetupSupports</key>
  <array>
    <string>Bluetooth</string>
    <string>WiFi</string>
  </array>
  

  • When you use the ASDiscoveryDescriptor with bluetoothServiceUUID
    ⚠️ The UUID string must be upper-cased here. ⚠️

  <key>NSAccessorySetupBluetoothServices</key>
  <array>
    <string>149E9E42-33AD-41AD-8665-70D153533EC1</string>
  </array>
  

  For testing, replace the UUID above with the BLE service UUID advertised by your accessory. The same UUID must also be passed to showPickerForDevice as the serviceID. Info.plist is read from the installed iOS app, so rebuild and reinstall the app after changing this value.

  When checking with nRF Connect, inspect the advertising data. Seeing the service in the post-connection GATT service list does not necessarily mean the service UUID is advertised, and the AccessorySetupKit picker can only match the identifiers in the discovery descriptor and app allowlist.

  • There is an option with manufacturer ID that is not covered here.

• Use the FlutterAccessorySetup class. The snippet below shows the minimum setup flow inside a StatefulWidget.

class _MyScreenState extends State<MyScreen> {
  final _accessorySetup = FlutterAccessorySetup();
  StreamSubscription<ASAccessoryEvent>? _eventSubscription;

  @override
  void initState() {
    super.initState();
    _eventSubscription = _accessorySetup.eventStream.listen((event) {
      debugPrint('Got event: ${event.eventType}');
      // handle session events here
    });
    _accessorySetup.activate();
    _showPicker();
  }

  Future<void> _showPicker() async {
    try {
      await _accessorySetup.showPickerForDevice(
        'My BLE',
        Assets.images.ble.path,
        '149E9E42-33AD-41AD-8665-70D153533EC1',
      );
    } on PlatformException {
      debugPrint('Failed to show the picker');
    }
  }

  @override
  void dispose() {
    _eventSubscription?.cancel();
    _accessorySetup.dispose();
    super.dispose();
  }
}

---

ℹ️ What we know

• You app does not need Bluetooth permissions when you use the picker to work with bluetooth devices.

• It is very easy for user to select the device from a picker.

• ⚠️ If you want to have multiple devices of the same type displayed in the picker, each device should advertise a unique name. The picker will show only one device per unique name. If your device exposes 0x1800 service, the device name in that service should be unique too⚠️

• When the user closes the Picker by tapping the cross button, the showPicker closure emits an error (ASErrorDomain, code 700). Be prepared.

• ⚠️ When the person picks a BLE accessory, the picker sends an event of type ASAccessoryEventType.accessoryChanged. The picker is supposed to sends an event of type ASAccessoryEventType.accessoryAdded, but I can't reproduce it at all.⚠️

• If the device has been connected previously, it will be in the session.accessories array right after the session is activated.
  ⚠️ This device will not be discoverable by the Setup Picker until the user disconnects it from the settings. ⚠️

• If the device has been connected by another app already, the picker will show the device as it was decorated by another app -> meaning the image and name will be from that app, not that you provide. To change the decoration the user should add the device to your app.

• When the user selects the device using the picker:

  • The device will be displayed in the Accessories of the mobile App settings at Settings/Apps/YourApp.
  • The device will be displayed in the My Devices section at Settings/Bluetooth.
  • The device's info screen will display the image and name you provided to the ASPickerDisplayItem during the discovery process (the same that the user saw in the picker).

• When the user deletes the app, the device will be disconnected automatically. It won't be displayed in the My Devices section of the Settings/Bluetooth screen anymore.

⚠️ The AccessorySetup does not work on the Simulator. ⚠️

---

📗 References

• https://developer.apple.com/documentation/accessorysetupkit/discovering-and-configuring-accessories
• https://developer.apple.com/documentation/accessorysetupkit/authorizing-a-bluetooth-accessory-to-share-a-dice-roll