Create smart_wifi_connect Flutter Package and Ensemble Wi-Fi Connect Module

[sharjeelyunus]

Overview

Create a lightweight Flutter plugin named smart_wifi_connect that allows apps to connect to a known Wi-Fi network using SSID and password.

The package should expose a minimal cross-platform API and be integrated into Ensemble as a native module/action so Ensemble apps can reconnect users to a newly updated home Wi-Fi network after SSID/password changes.

Problem

When a user updates their home Wi-Fi SSID or password from the app, the router applies the new Wi-Fi settings and the phone disconnects from the old network. Since the device is no longer connected to the home network, the app becomes unusable and the user cannot continue setup or verify the changes.

We need a guided way for the app to reconnect the device to the newly configured Wi-Fi network.

Goals

Create a public Flutter package:

smart_wifi_connect

Add Ensemble module/action support using this package.

Support only one core API for now:

SmartWifiConnect.connect(
  ssid: "...",
  password: "...",
  joinOnce: false,
  rememberNetwork: true,
);

Non-Goals

Do not support Wi-Fi scanning in this version.

Do not support reading current SSID in this version.

Do not support listing saved networks.

Do not support background Wi-Fi monitoring.

Do not request background location.

Do not build full Wi-Fi management features.

Do not guarantee silent reconnection, since Android and iOS control final connection behavior.

Package API

Dart API

class SmartWifiConnect {
  static Future<SmartWifiConnectResult> connect({
    required String ssid,
    required String password,
    bool joinOnce = false,
    bool rememberNetwork = true,
  });
}

Result model

class SmartWifiConnectResult {
  final bool success;
  final SmartWifiConnectStatus status;
  final String? message;
  final String? platformCode;

  const SmartWifiConnectResult({
    required this.success,
    required this.status,
    this.message,
    this.platformCode,
  });
}

Status enum

enum SmartWifiConnectStatus {
  connected,
  permissionDenied,
  userCancelled,
  unsupported,
  invalidArguments,
  failed,
}

Expected Behavior

iOS

Use NEHotspotConfigurationManager.

If joinOnce is true, configure the network as temporary/session-based.

If rememberNetwork is true, allow the device to remember the configured network.

iOS may show a native confirmation prompt. The package should handle this gracefully and return a structured result.

Android

Use modern Android Wi-Fi connection APIs.

Preferred behavior:

For Android 10+:

Use WifiNetworkSuggestion or WifiNetworkSpecifier depending on what works best for connection behavior.

For Android 13+:

Use NEARBY_WIFI_DEVICES.

For Android 12 and below:

Use location-compatible Wi-Fi permission only where required.

The package should not scan networks.

The package should not infer user location.

Minimum Permissions

Android

Add to the consuming app’s AndroidManifest.xml:

<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />

<uses-permission
    android:name="android.permission.NEARBY_WIFI_DEVICES"
    android:usesPermissionFlags="neverForLocation" />

<uses-permission
    android:name="android.permission.ACCESS_FINE_LOCATION"
    android:maxSdkVersion="32" />

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

The package documentation must clearly explain why each permission is needed.

iOS

Add the following capability:

Hotspot Configuration

This adds the entitlement:

<key>com.apple.developer.networking.hotspotconfiguration</key>
<true/>

No Wi-Fi scanning or current SSID reading should be added in v1.

Ensemble Module

Create an Ensemble module/action using the package.

Proposed module name

ensemble_wifi

Proposed action

connectToWifi:
  ssid: ${newSSID}
  password: ${newPassword}
  joinOnce: false
  rememberNetwork: true
  onSuccess:
    executeCode:
        body: |
           console.log('Connected to Wi-Fi');
  onError:
    executeCode:
         body: |
            console.log('Failed to connect to Wi-Fi');

UX Recommendation

The action should be used from a guided reconnect screen, not silently in the background.

Suggested flow:

1. User updates SSID/password.
2. App sends changes to router.
3. Router applies new Wi-Fi settings.
4. App shows reconnect screen.
5. User taps “Reconnect automatically”.
6. App calls SmartWifiConnect.connect().
7. If success, continue setup.
8. If failed, show manual Wi-Fi settings fallback.

Acceptance Criteria

Package

• smart_wifi_connect package is created.
• Package exposes only SmartWifiConnect.connect().
• Supports ssid, password, joinOnce, and rememberNetwork.
• Android implementation uses platform-appropriate Wi-Fi connection APIs.
• iOS implementation uses NEHotspotConfigurationManager.
• Package returns structured success/error result.
• Package does not include Wi-Fi scanning.
• Package does not include current SSID reading.
• Package does not request background location.
• README documents required Android permissions.
• README documents required iOS Hotspot Configuration capability.
• Example Flutter app is included.
• Tested on at least one Android 13+ device and one iOS device.

Ensemble Module

• Ensemble module is created using smart_wifi_connect.
• connectToWifi action is added.
• onSuccess and onError handlers are supported.
• Sensitive fields such as password are not logged.
• Module works in a real reconnect flow after Wi-Fi credentials are changed.

Security & Privacy Requirements

• Never log Wi-Fi password.
• Do not persist Wi-Fi password unless strictly required by platform API.
• Do not scan nearby Wi-Fi networks.
• Do not collect location data.
• Use neverForLocation on Android 13+.
• Request permissions only when the user initiates the reconnect action.
• Clearly explain to the user why Wi-Fi permission is needed.

Suggested Repo Structure

smart_wifi_connect/
├── android/
├── ios/
├── lib/
│   ├── smart_wifi_connect.dart
│   ├── smart_wifi_connect_result.dart
│   └── smart_wifi_connect_status.dart
├── example/
├── test/
├── pubspec.yaml
└── README.md

Implementation Notes

Use a platform-channel based Flutter plugin.

Dart API should stay small and stable.

Platform-specific behavior should be normalized into SmartWifiConnectResult.