Type-Safe Platform Channels with Pigeon

What is Pigeon and Why Use It?

Adding Pigeon to Your Project

# pubspec.yaml (relevant excerpt)
# dev_dependencies:
#   pigeon: ^22.0.0

// Run generation (in terminal, not Dart code):
// dart run pigeon --input pigeons/messages.dart

Defining a Pigeon API File

// pigeons/messages.dart
import 'package:pigeon/pigeon.dart';

@ConfigurePigeon(PigeonOptions(
  dartOut: 'lib/src/messages.g.dart',
  dartOptions: DartOptions(),
  kotlinOut:
    'android/app/src/main/kotlin/com/example/app/Messages.g.kt',
  kotlinOptions: KotlinOptions(),
  swiftOut: 'ios/Runner/Messages.g.swift',
  swiftOptions: SwiftOptions(),
))

// Data class shared between Flutter and native
class BatteryInfo {
  BatteryInfo({required this.level, required this.isCharging});
  final int level;
  final bool isCharging;
}

// Flutter calls native to read battery
@HostApi()
abstract class BatteryHostApi {
  BatteryInfo getBatteryInfo();
  @async
  BatteryInfo getBatteryInfoAsync();
}

// Native calls Flutter to report a low-battery event
@FlutterApi()
abstract class BatteryFlutterApi {
  void onLowBattery(BatteryInfo info);
}

Running the Generator

dart run pigeon --input pigeons/messages.dart

Implementing the Host API on Android (Kotlin)

// android/app/src/main/kotlin/com/example/app/MainActivity.kt
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine

class MainActivity : FlutterActivity() {

  override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
    super.configureFlutterEngine(flutterEngine)

    BatteryHostApi.setUp(
      flutterEngine.dartExecutor.binaryMessenger,
      BatteryHostApiImpl()
    )
  }
}

class BatteryHostApiImpl : BatteryHostApi {
  override fun getBatteryInfo(): BatteryInfo {
    // Real impl would query BatteryManager
    return BatteryInfo(level = 87L, isCharging = true)
  }

  override fun getBatteryInfoAsync(result: Result<BatteryInfo>) {
    // Offload to coroutine in production
    result.success(BatteryInfo(level = 87L, isCharging = true))
  }
}

Implementing the Host API on iOS (Swift)

// ios/Runner/AppDelegate.swift
import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate {

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let controller = window?.rootViewController as! FlutterViewController
    let messenger = controller.binaryMessenger

    BatteryHostApiSetup.setUp(
      binaryMessenger: messenger,
      api: BatteryHostApiImpl()
    )

    return super.application(application,
      didFinishLaunchingWithOptions: options)
  }
}

class BatteryHostApiImpl: BatteryHostApi {
  func getBatteryInfo() throws -> BatteryInfo {
    // UIDevice.current.batteryLevel in production
    return BatteryInfo(level: 87, isCharging: true)
  }

  func getBatteryInfoAsync(
    completion: @escaping (Result<BatteryInfo, Error>) -> Void
  ) {
    completion(.success(BatteryInfo(level: 87, isCharging: true)))
  }
}

Calling the Host API from Dart

// lib/battery_page.dart
import 'package:flutter/material.dart';
import 'src/messages.g.dart'; // generated

class BatteryPage extends StatefulWidget {
  const BatteryPage({super.key});
  @override
  State<BatteryPage> createState() => _BatteryPageState();
}

class _BatteryPageState extends State<BatteryPage> {
  final _api = BatteryHostApi(); // generated class
  BatteryInfo? _info;

  Future<void> _fetch() async {
    try {
      // Typed return — no casts needed
      final info = await _api.getBatteryInfoAsync();
      setState(() => _info = info);
    } on PlatformException catch (e) {
      debugPrint('Native error: ${e.message}');
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Battery')),
      body: Column(
        children: [
          Text('Level: ${_info?.level ?? '--'}%'),
          Text('Charging: ${_info?.isCharging ?? '--'}'),
          ElevatedButton(
            onPressed: _fetch,
            child: const Text('Refresh'),
          ),
        ],
      ),
    );
  }
}

Implementing FlutterApi — Native Calls Flutter

// lib/src/battery_flutter_api_impl.dart
import 'messages.g.dart';

class BatteryFlutterApiImpl extends BatteryFlutterApi {
  // Called by native when battery drops below threshold
  @override
  void onLowBattery(BatteryInfo info) {
    debugPrint(
      'LOW BATTERY: ${info.level}% '
      '(charging: ${info.isCharging})',
    );
    // Update state, show snackbar, etc.
  }
}

// Register once — e.g. in main() or an initState
void registerFlutterApis() {
  BatteryFlutterApi.setUp(BatteryFlutterApiImpl());
}

Nullable Fields and Enum Support

// pigeons/messages.dart  (additions)

enum ChargingStatus { unknown, charging, discharging, full }

class DetailedBatteryInfo {
  DetailedBatteryInfo({
    required this.level,
    required this.status,
    this.temperature,  // nullable — not available on all devices
    this.voltages,
  });

  final int level;
  final ChargingStatus status;
  final double? temperature;
  final List<double>? voltages;
}

@HostApi()
abstract class DetailedBatteryHostApi {
  @async
  DetailedBatteryInfo getDetailedInfo();
}

Error Handling with PigeonError

// pigeons/messages.dart
class BatteryError {
  BatteryError({required this.code, this.details});
  final String code;   // e.g. 'PERMISSION_DENIED'
  final String? details;
}

// Dart call-site
Future<void> safeFetch() async {
  try {
    final info = await BatteryHostApi().getBatteryInfoAsync();
    print('Level: ${info.level}');
  } on PlatformException catch (e) {
    // e.code  = native error code string
    // e.message = human-readable message
    // e.details = arbitrary details object
    if (e.code == 'PERMISSION_DENIED') {
      print('Need battery permission');
    } else {
      rethrow;
    }
  }
}

Streaming with EventChannelApi

// pigeons/messages.dart
@EventChannelApi()
abstract class BatteryEventApi {
  // The return type defines what flows down the stream
  BatteryInfo onBatteryChanged();
}

// lib/battery_stream_page.dart
import 'src/messages.g.dart';

class BatteryStreamPage extends StatelessWidget {
  const BatteryStreamPage({super.key});

  @override
  Widget build(BuildContext context) {
    // BatteryEventApi().onBatteryChangedStream() returns Stream<BatteryInfo>
    return StreamBuilder<BatteryInfo>(
      stream: BatteryEventApi().onBatteryChangedStream(),
      builder: (context, snapshot) {
        if (!snapshot.hasData) return const CircularProgressIndicator();
        final info = snapshot.data!;
        return Text('${info.level}% – charging: ${info.isCharging}');
      },
    );
  }
}

Knowledge Check: Pigeon API Direction

Recap: Type-Safe Platform Channels with Pigeon