nearby_connections

Description:

nearby connections

nearby_connections #
An ANDROID flutter plugin for the Nearby Connections API
Currently supports Bytes and Files.
Transfer Data between multiple connected devices using fully offline peer to peer networking



Table of Content #

Setup
Work Flow

Advertise For connections
Discover Advertisers
Request Connection
Accept Connection


Sending Data

Sending Bytes Payload
Sending Files



Setup #
Note regarding Location(GPS) #
While using this,
Location/GPS service must be turned on or devices may disconnect
more often, some devices may disconnect immediately.
Set Permissions #
Add these to your project's android/src/main/AndroidManifest.xml
<!-- Required for Nearby Connections -->
<uses-permission android:maxSdkVersion="31" android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:maxSdkVersion="31" android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:maxSdkVersion="30" android:name="android.permission.BLUETOOTH" />
<uses-permission android:maxSdkVersion="30" android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:maxSdkVersion="28" android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:minSdkVersion="29" android:maxSdkVersion="31" android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:minSdkVersion="31" android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:minSdkVersion="31" android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:minSdkVersion="31" android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:minSdkVersion="32" android:name="android.permission.NEARBY_WIFI_DEVICES" />
<!-- Optional: only required for FILE payloads -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
copied to clipboard

Note: Android 12+ has introduced some new bluetooth permissions - BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT, BLUETOOTH_SCAN, which need to be handled as well. You may also need to set compileSdkVersion 32 in your build.gradle file.

Request Permissions #
Since ACCESS_FINE_LOCATION, BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT, BLUETOOTH_SCAN and READ_EXTERNAL_STORAGE are considered to be dangerous system permissions, in addition to adding them to your manifest, you must request these permissions at runtime.

You can use:

permission_handler package to handle all these permissions
location package to request enabling location.
device_info_plus to check Android verison.


// location permission
await Permission.location.isGranted // Check Permission
await Permission.location.request() // Ask

// Check Location Status
await Permission.location.serviceStatus.isEnabled;

// location enable dialog
await Location.instance.requestService()

// external storage permission
await Permission.storage.isGranted // Check Permission
await Permission.storage.request() // Ask

// Bluetooth permissions
bool granted = !(await Future.wait([ // Check Permissions
Permission.bluetooth.isGranted,
Permission.bluetoothAdvertise.isGranted,
Permission.bluetoothConnect.isGranted,
Permission.bluetoothScan.isGranted,
])).any((element) => false);
[ // Ask Permissions
Permission.bluetooth,
Permission.bluetoothAdvertise,
Permission.bluetoothConnect,
Permission.bluetoothScan
].request();

// Check Bluetooth Status
await Permission.bluetooth.serviceStatus.isEnabled;


// Android 12+
await Permission.nearbyWifiDevices.request()
copied to clipboard
Checkout the Example in Repository for more details.
NOTE #
Location/GPS service must be turned on or devices may disconnect
more often, some devices may disconnect immediately.
Work Flow #
The work flow is similar to the Android Nearby Connections library
Advertise for connection #
try {
bool a = await Nearby().startAdvertising(
userName,
strategy, // https://developers.google.com/nearby/connections/strategies
onConnectionInitiated: (String id,ConnectionInfo info) {
// Called whenever a discoverer requests connection
},
onConnectionResult: (String id,Status status) {
// Called when connection is accepted/rejected
},
onDisconnected: (String id) {
// Callled whenever a discoverer disconnects from advertiser
},
serviceId: "com.yourdomain.appname", // uniquely identifies your app
);
} catch (exception) {
// platform exceptions like unable to start bluetooth or insufficient permissions
}
copied to clipboard
Discover Advertisers #
try {
bool a = await Nearby().startDiscovery(
userName,
strategy, // https://developers.google.com/nearby/connections/strategies
onEndpointFound: (String id,String userName, String serviceId) {
// called when an advertiser is found
},
onEndpointLost: (String id) {
//called when an advertiser is lost (only if we weren't connected to it )
},
serviceId: "com.yourdomain.appname", // uniquely identifies your app
);
} catch (e) {
// platform exceptions like unable to start bluetooth or insufficient permissions
}
copied to clipboard
Stopping Advertising and Discovery #
Nearby().stopAdvertising();
Nearby().stopDiscovery();
// endpoints already discovered will still be available to connect
// even after stopping discovery
// You should stop discovery once you have found the intended advertiser
// this will reduce chances for disconnection
copied to clipboard
Request Connection #
// to be called by discover whenever an endpoint is found
// callbacks are similar to those in startAdvertising method
try{
Nearby().requestConnection(
userName,
id,
onConnectionInitiated: (id, info) {
},
onConnectionResult: (id, status) {
},
onDisconnected: (id) {
},
);
}catch(exception){
// called if request was invalid
}
copied to clipboard
Accept Connection #
Nearby().acceptConnection(
id,
onPayLoadRecieved: (endpointId, payload) {
// called whenever a payload is recieved.
},
onPayloadTransferUpdate: (endpointId, payloadTransferUpdate) {
// gives status of a payload
// e.g success/failure/in_progress
// bytes transferred and total bytes etc
}
);
copied to clipboard
Sending Data #
Sending Bytes Payload #
Nearby().sendBytesPayload(endpointId, bytes_array);

// payloads are recieved by callback given to acceptConnection method.
copied to clipboard
Sending File Payload #
You need to send the File Payload and File Name seperately.
File is stored in DOWNLOAD_DIRECTORY/.nearby/ and given a generic name.
You need to copy the file to another directory of your choice.
//creates file with generic name (without extension) in Downloads Directory
//its your responsibility to rename the file properly
Nearby().sendFilePayload(endpointId, filePath);

//Send filename as well so that receiver can move and rename the file
Nearby().sendBytesPayload(endpointId,fileNameEncodedWithPayloadId);
//e.g send a string like "payloadId:FileExtensionOrFullName" as bytes

//payloads are recieved by callback given to acceptConnection method.
copied to clipboard
Every payload has an ID which is same for sender and receiver.
You can get the uri of the file from Payload in onPayloadReceived function.
We have a convenience method to copy the file to a location you want-
// Convenience method to copy file using it's `uri`.
final newPath = '${await getExternalStorageDirectory}/$fileName';
await Nearby().copyFileAndDeleteOriginal(uri, newPath);
copied to clipboard
Checkout the Example in Repository for more details.