wifi_connector_plus

Current stable release: 0.0.5

A comprehensive Flutter plugin to scan Wi-Fi QR codes, parse connection settings, and connect directly to Wi-Fi networks.

Features

• Built-in Scanner Widget: WifiQrScannerView handles camera permission requests, displays the camera view with an overlay, and parses Wi-Fi configurations automatically.
• Manual Connections: Establish connections manually using SSID, password, and security types (WPA, WEP, or Open/None).
• QR Code Parser: Standalone utility WifiQrParser to parse industry-standard Wi-Fi QR configurations (e.g., WIFI:S:MyNetwork;T:WPA;P:SecretPassword;;).
• Comprehensive Platform APIs: Uses modern native connection APIs (WifiNetworkSpecifier and WifiNetworkSuggestion on Android 10+, and NEHotspotConfigurationManager on iOS 11+).

Getting Started

1. Platform Setup & Permissions

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Camera permission for the QR Scanner -->
    <uses-permission android:name="android.permission.CAMERA" />
    
    <!-- Location and Wi-Fi state permissions for connecting to networks -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    
    <application ...>
        ...
    </application>
</manifest>

<key>NSCameraUsageDescription</key>
<string>This app needs camera access to scan QR codes for Wi-Fi connections.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access to detect nearby Wi-Fi networks.</string>

Usage

1. Connecting to Wi-Fi Manually

import 'package:wifi_connector_plus/wifi_connector_plus.dart';

final wifiConnector = WifiConnectorPlus();

// Connect manually to a WPA network
WifiConnectResult result = await wifiConnector.connect(
  ssid: 'MyHomeWiFi',
  password: 'myPassword123',
  securityType: WifiSecurityType.wpa, // WPA, WEP, or None
  isHidden: false,
);

if (result.isSuccess) {
  print('Connected successfully: ${result.message}');
} else {
  print('Connection failed: ${result.message} (Error: ${result.error})');
}

2. Parsing a raw Wi-Fi QR Code String

import 'package:wifi_connector_plus/wifi_connector_plus.dart';

final rawQrString = 'WIFI:S:OfficeWiFi;T:WPA;P:Secret123;;';
WifiCredentials? credentials = WifiQrParser.parse(rawQrString);

if (credentials != null) {
  print('SSID: ${credentials.ssid}');
  print('Password: ${credentials.password}');
  print('Security: ${credentials.securityType}');
}

3. Using the built-in Camera QR Scanner Widget

Push WifiQrScannerView to display a camera view that requests permissions and parses Wi-Fi configurations automatically.

import 'package:flutter/material.dart';
import 'package:wifi_connector_plus/wifi_connector_plus.dart';

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: WifiQrScannerView(
        onScanSuccess: (WifiCredentials credentials, String rawValue) async {
          // Triggered when a valid Wi-Fi QR code is scanned
          Navigator.pop(context);
          
          final connector = WifiConnectorPlus();
          final result = await connector.connect(
            ssid: credentials.ssid,
            password: credentials.password,
            securityType: credentials.securityType,
            isHidden: credentials.isHidden,
          );
          
          print('Connection Result: ${result.message}');
        },
        onError: (String error) {
          // Triggered if permissions are denied or scanning fails
          print('Scanner Error: $error');
        },
      ),
    );
  }
}

Scanner Customization Options

You can customize WifiQrScannerView with additional layout and camera option configuration:

WifiQrScannerView(
  // Configure whether to show or hide the camera controls overlay (torch and flip button)
  cameraOption: CameraOption.show, // Or CameraOption.hide
  
  // Instruction text shown overlaying the bottom portion of the camera feed
  instructionText: 'Align QR code within the frame to connect',
  
  onScanSuccess: (credentials, rawValue) { ... },
  onError: (error) { ... },
)

4. Checking and Requesting Location Permissions

On Android, location permissions are mandatory for Wi-Fi connection operations. You can utilize the built-in helper methods to check and request location permissions:

final wifiConnector = WifiConnectorPlus();

// Check if location permission is granted
bool isGranted = await wifiConnector.isLocationPermissionGranted();

if (!isGranted) {
  // Request location permission
  bool hasGranted = await wifiConnector.requestLocationPermission();
  if (hasGranted) {
    print("Location permission granted by user.");
  } else {
    print("Location permission denied by user.");
  }
}

Contributing

Contributions are welcome! If you find any bugs, have feature requests, or want to improve the codebase, feel free to open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-party package dependencies are subject to their respective licenses. See THIRD_PARTY_NOTICES.md for details.

Created and maintained by handelika.