Flutter BLE: Building a Bluetooth IoT Controller App from Scratch

Flutter BLE: Building a Bluetooth IoT Controller App from Scratch

Bluetooth Low Energy is the right choice for short-range IoT devices — wearables, industrial sensors, home automation, and medical devices all use BLE because it consumes milliwatts instead of watts. Flutter's BLE ecosystem has matured significantly, and flutter_blue_plus is now the production-standard library.

This guide takes you from zero to a working Flutter BLE IoT controller that scans, connects, reads sensor data in real time, and writes commands to your embedded device.

Understanding BLE for IoT Engineers

Before touching Flutter code, you need to understand BLE's data model:

Device (Peripheral)
  └── Service (UUID: 180F = Battery, or custom UUID)
        ├── Characteristic (UUID: read/write/notify)
        │     └── Value (bytes)
        └── Characteristic (UUID: write-only)
              └── Value (bytes: your command)

Your ESP32/STM32 firmware exposes Services (logical groups) containing Characteristics (individual data points). A temperature sensor might expose:

Setup: flutter_blue_plus

# pubspec.yaml
dependencies:
  flutter_blue_plus: ^1.31.0
  permission_handler: ^11.0.0

iOS permissions (Info.plist)

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Required to connect to IoT sensors</string>
<key>NSBluetoothPeripheralUsageDescription</key>
<string>Required to connect to IoT sensors</string>

Android permissions (AndroidManifest.xml)

<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
                 android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Step 1: Scanning for BLE Devices

import 'package:flutter_blue_plus/flutter_blue_plus.dart';
class BLEScanService {
  StreamSubscription<List<ScanResult>>? _scanSub;
  Stream<List<ScanResult>> get scanResults => FlutterBluePlus.scanResults;
  Future<void> startScan({Duration timeout = const Duration(seconds: 10)}) async {
    // Request permissions first
    await Permission.bluetoothScan.request();
    await Permission.bluetoothConnect.request();
    await FlutterBluePlus.startScan(
      withServices: [Guid('12345678-1234-1234-1234-1234567890AB')], // Filter by your service UUID
      timeout: timeout,
      androidUsesFineLocation: false,
    );
  }
  Future<void> stopScan() async {
    await FlutterBluePlus.stopScan();
  }
}

Filtering by service UUID is critical in production — it prevents your app from showing every BLE device nearby and only surfaces your IoT hardware.

Step 2: Connecting and Discovering Services

class BLEDeviceService {
  BluetoothDevice? _device;
  BluetoothCharacteristic? _tempCharacteristic;
  BluetoothCharacteristic? _ctrlCharacteristic;
  static const String SERVICE_UUID = '12345678-1234-1234-1234-1234567890AB';
  static const String TEMP_UUID    = '12345678-1234-1234-1234-1234567890AC';
  static const String CTRL_UUID    = '12345678-1234-1234-1234-1234567890AD';
  Future<void> connect(BluetoothDevice device) async {
    _device = device;
    await device.connect(
      timeout: const Duration(seconds: 15),
      autoConnect: false,  // true causes connection delays on Android
    );
    // Monitor connection state
    device.connectionState.listen((state) {
      if (state == BluetoothConnectionState.disconnected) {
        _scheduleReconnect(device);
      }
    });
    await _discoverServices(device);
  }
  Future<void> _discoverServices(BluetoothDevice device) async {
    final services = await device.discoverServices();
    for (final service in services) {
      if (service.uuid == Guid(SERVICE_UUID)) {
        for (final char in service.characteristics) {
          if (char.uuid == Guid(TEMP_UUID)) _tempCharacteristic = char;
          if (char.uuid == Guid(CTRL_UUID)) _ctrlCharacteristic = char;
        }
      }
    }
  }
  // Reconnect with exponential backoff
  int _reconnectAttempts = 0;
  Future<void> _scheduleReconnect(BluetoothDevice device) async {
    final delay = Duration(seconds: [2, 5, 10, 30][_reconnectAttempts.clamp(0, 3)]);
    await Future.delayed(delay);
    _reconnectAttempts++;
    try {
      await connect(device);
      _reconnectAttempts = 0;
    } catch (_) {
      _scheduleReconnect(device);
    }
  }
}

Step 3: Real-Time Sensor Data via Notify

BLE notify is the equivalent of WebSocket for Bluetooth — the device pushes data to your app without polling:

Stream<double> streamTemperature() async* {
  if (_tempCharacteristic == null) throw StateError('Not connected');
  // Enable notifications on the characteristic
  await _tempCharacteristic!.setNotifyValue(true);
  await for (final value in _tempCharacteristic!.onValueReceived) {
    // Parse 4-byte IEEE 754 float (little-endian, as set in ESP32 firmware)
    final byteData = ByteData.sublistView(Uint8List.fromList(value));
    yield byteData.getFloat32(0, Endian.little);
  }
}

On the ESP32 side, your firmware notifies every 500ms:

// ESP32 firmware (simplified)
float temperature = readTemperatureSensor();
uint8_t buf[4];
memcpy(buf, &temperature, 4);
pTempCharacteristic->setValue(buf, 4);
pTempCharacteristic->notify();

Step 4: State Management with Riverpod

// providers.dart
final bleServiceProvider = Provider((ref) => BLEDeviceService());
final temperatureProvider = StreamProvider.autoDispose<double>((ref) {
  final service = ref.watch(bleServiceProvider);
  return service.streamTemperature();
});
// In your widget
class TemperatureWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final temp = ref.watch(temperatureProvider);
    return temp.when(
      data: (value) => Text(
        '${value.toStringAsFixed(1)}°C',
        style: const TextStyle(fontSize: 48, color: Colors.white),
      ),
      loading: () => const CircularProgressIndicator(),
      error: (e, _) => Text('Disconnected', style: TextStyle(color: Colors.red)),
    );
  }
}

Step 5: Writing Commands to the Device

enum DeviceCommand { on, off, reset }
Future<void> sendCommand(DeviceCommand cmd) async {
  if (_ctrlCharacteristic == null) throw StateError('Not connected');
  final byte = switch (cmd) {
    DeviceCommand.on    => [0x01],
    DeviceCommand.off   => [0x00],
    DeviceCommand.reset => [0xFF],
  };
  await _ctrlCharacteristic!.write(byte, withoutResponse: false);
  // withoutResponse: false = BLE Write With Response (guaranteed delivery)
  // withoutResponse: true  = BLE Write Without Response (faster, no ACK)
}

Background BLE

On iOS, background BLE requires the bluetooth-central background mode and a CoreBluetooth state restoration identifier. On Android, use a Foreground Service:

// Start foreground service to keep BLE alive in background (Android)
await FlutterBluePlus.setLogLevel(LogLevel.none);
// Add to AndroidManifest.xml:
// <service android:name=".BluetoothService" android:foregroundServiceType="connectedDevice" />

Production Checklist

Building BLE-connected IoT apps is our bread and butter at Code Caracal. [Contact us](/contact) if you need a production BLE IoT controller built.