# FastBle: an Android BLE wrapper for scan, connect and notify

> FastBle is a Java library that wraps Android's Bluetooth Low Energy APIs behind a single BleManager. It suits Android 5.0 to 15 projects that want filtered scanning, multi-connection and simple read/write callbacks without writing GATT plumbing themselves.

**Jasonchenlijian/FastBle** — Android Bluetooth Low Energy (BLE) Fast Development Framework. It uses simple ways to filter, scan, connect, read ,write, notify, readRssi, setMTU, and multiConnection.

- Repository: https://github.com/Jasonchenlijian/FastBle
- Stars: 5,505 · Forks: 1,243
- Language: Java
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/jasonchenlijian-fastble

## What problem FastBle removes from an Android BLE project

Android's Bluetooth Low Energy stack is callback-heavy. A scan needs a ScanCallback, a connection needs a BluetoothGattCallback, and every read, write and notification arrives as another callback on a GATT object you have to keep alive yourself. FastBle puts all of that behind BleManager, a singleton the README initializes with BleManager.getInstance().init(getApplication()). The framework is aimed at Android app developers who already know what a service UUID and a characteristic are, and who would rather configure a scan rule than write a BluetoothLeScanner loop. The README lists the supported range as Android 5.0 through 15, API 21 through 35, which is broad enough to cover most phones still in use. It is a Java library with no Kotlin-specific API surface described, so Java Android projects are the natural audience. The project is Apache-2.0 licensed and the last push to the default branch was on 2026-04-17, so the repository is not archived and has seen changes this year, though the most recent release listed is 2.4.0 from 2021-09-13 while the README badge and dependency line both say 2.5.0.

## How BleManager, scan rules and callbacks fit together

The architecture is a singleton facade over Android's own BLE classes. The README states that FastBle uses BluetoothLeScanner and ScanCallback internally, so it is a wrapper rather than a replacement stack. You build a BleScanRuleConfig with a builder, passing service UUIDs, device names, a MAC address, an autoConnect flag and a scan timeout, then hand it to initScanRule. Scanning starts with scan() and reports through BleScanCallback, which has three methods: onScanStarted, onScanning for each device found, and onScanFinished with the full result list. Connection is separate. You can pass a BleDevice, a MAC address string, or call scanAndConnect to scan and connect to the first match. Each path takes a BleGattCallback with onStartConnect, onConnectFail, onConnectSuccess and onDisConnected, and onDisConnected tells you whether the disconnect was active, meaning you initiated it. Characteristics are addressed by service UUID plus characteristic UUID. notify, indicate, write and read each take their own callback type, so the data flow is: configure rule, scan, receive BleDevice, connect, then operate on characteristics and receive byte arrays back. FastBle also declares its required permissions in its own manifest, which the README says means you do not add them again in yours.

## Installing FastBle from JitPack and running a first scan

FastBle is distributed through JitPack, not Maven Central. Step one is adding the JitPack repository to your root build.gradle or settings.gradle, exactly as the README shows. Step two is the dependency line. The README gives the version as 2.5.0 even though the release list stops at 2.4.0, so confirm which artifact resolves before you pin it.

```gradle
allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

dependencies {
    implementation 'com.github.Jasonchenlijian:FastBle:2.5.0'
}
```

Runtime permissions are still your job. The README's checkPermissions example collects BLUETOOTH_SCAN and BLUETOOTH_CONNECT on Android 12 and above, plus ACCESS_FINE_LOCATION on all versions, then requests whatever was denied. On Android 6.0 through 11 the README notes GPS must be enabled for scanning; on Android 12 and later that requirement is gone. Once permissions are granted, initialize the manager and configure logging and timeouts. The README's init block sets a reconnect count of 1 with a 5000 ms interval, a split write size of 20 bytes, a 10000 ms connect timeout and a 5000 ms operation timeout.

```java
BleManager.getInstance().init(getApplication());
BleManager.getInstance()
        .enableLog(true)
        .setReConnectCount(1, 5000)
        .setSplitWriteNum(20)
        .setConnectOverTime(10000)
        .setOperateTimeout(5000);
```

A first real scan is a rule plus a callback. The builder takes service UUIDs, device names, a MAC, an autoConnect flag and a scan timeout; the scan call reports devices as they arrive and again as a list when the timeout expires. Expect onScanStarted to fire first, onScanning repeatedly, and onScanFinished once.

```java
BleScanRuleConfig scanRuleConfig = new BleScanRuleConfig.Builder()
        .setServiceUuids(serviceUuids)
        .setDeviceName(true, names)
        .setDeviceMac(mac)
        .setAutoConnect(isAutoConnect)
        .setScanTimeOut(10000)
        .build();
BleManager.getInstance().initScanRule(scanRuleConfig);

BleManager.getInstance().scan(new BleScanCallback() {
    @Override
    public void onScanStarted(boolean success) { }

    @Override
    public void onScanning(BleDevice bleDevice) { }

    @Override
    public void onScanFinished(List<BleDevice> scanResultList) { }
});
```

## Where FastBle stops helping: permissions, payload size and platform gaps

The library deliberately does not manage permissions for you. Its own manifest declares what it needs, but the README is explicit that you must request runtime permissions before scanning, and the sample code is a manual check-and-request routine. If you forget ACCESS_FINE_LOCATION on Android 11 or below, or leave GPS off on Android 6.0 through 11, scanning fails in ways that look like a hardware problem. The second boundary is payload size. The README's tip says data longer than 20 bytes is automatically split into packets, and the init example sets setSplitWriteNum(20). That default is conservative and matches the classic BLE attribute limit, but it means large characteristic writes become many sequential operations, each with its own callback and each subject to the operation timeout. If your peripheral expects a negotiated MTU before you write, the splitting behavior interacts with whatever MTU you request. Third, the release history is uneven: 2.3.0 and 2.3.2 in 2018, 2.4.0 in 2021, and a README that advertises 2.5.0. Anyone pinning a version should check which artifacts actually exist rather than trusting the badge. Finally, this is an Android-only library. The README names no iOS, desktop or embedded target, and no emulator workflow, so testing means real hardware.

## FastBle against RxAndroidBle: callbacks versus reactive streams

RxAndroidBle is the comparison that appears alongside FastBle in search results, and the two take opposite approaches to the same Android APIs. FastBle exposes imperative methods on a singleton: you call scan, connect, notify, read or write and pass a callback object whose methods fire on completion. State lives inside BleManager and the BleDevice objects it hands back. RxAndroidBle models the same operations as RxJava observables, so scanning is a stream you subscribe to and can compose with operators like flatMap, retry and timeout. The practical difference shows up in composition. If your app already uses RxJava and you want to merge a connection stream with a data stream, the reactive model fits without adapters. If your app is plain Java with no reactive dependency, FastBle's callback style avoids pulling RxJava in at all. Neither is strictly better; the choice is really about which concurrency model your codebase already speaks. FastBle's multi-connection support is described as simultaneous connections to several devices through the same manager, which is the feature to compare when your use case involves more than one peripheral at once.

## Maintenance, licensing and what an upgrade costs

FastBle is Apache-2.0, which permits commercial and closed-source use and requires you to keep the license and notice files; this is a description of the license text, not legal advice, so read the LICENSE file in the repository for the terms that bind you. The repository is not archived and the last push was on 2026-04-17, so there is recent activity on the default branch. That said, the release cadence is thin: the listed releases are 2.4.0 from 2021-09-13, 2.3.2 from 2018-05-22 and 2.3.0 from 2018-04-30, while the README badge and Gradle snippet both reference 2.5.0. That gap between the README and the release list is the main upgrade risk. Pin an exact version, verify the artifact resolves from JitPack, and read the changelog section of the README before moving. Because FastBle wraps platform classes rather than shipping its own Bluetooth stack, upgrades to Android itself are the bigger cost: the README's permission guidance already splits behavior at Android 12, and that split is the kind of thing that changes again with a new API level. Budget for retesting scan and connect on each Android version you support, not just on each FastBle version.

## Conclusion

Adopt FastBle if you are building an Android app on API 21 or above and want scanning, connection, notify and read/write behind one BleManager instance rather than raw BluetoothGatt callbacks. Skip it if you need Kotlin coroutines or Flow as the primary API, or if you cannot test on real hardware, because the README documents no emulator path. Before committing, verify three things on your own devices: that your runtime permission flow covers BLUETOOTH_SCAN, BLUETOOTH_CONNECT and ACCESS_FINE_LOCATION, that your longest characteristic payload survives the default 20-byte split, and that the 2.5.0 artifact resolves from JitPack in your build.

## FAQ

### Does FastBle require me to add Bluetooth permissions to my own AndroidManifest.xml?

No. The README states that FastBle declares all required permissions in its own manifest and that you do not need to add them again. You do still have to request the runtime permissions before scanning.

### How does FastBle handle writes longer than 20 bytes?

The README says data longer than 20 bytes is automatically split into packets, and the init example sets the split size with setSplitWriteNum(20). Each packet is written sequentially and reports through the write callback.

### Can FastBle connect to more than one BLE device at the same time?

Yes. Multi-device simultaneous connections are listed among the features, and connections are opened through the same BleManager singleton using either a BleDevice, a MAC address, or scanAndConnect.

### Which Android versions does FastBle support?

The README gives the range as Android 5.0 through 15, API 21 through 35, and the requirements table lists API 21 as the minimum SDK. The build requirements also name Java 17 and Android Studio Ladybug or later.

### Where do I get the FastBle dependency from?

The README's getting started section adds the JitPack repository and then the dependency com.github.Jasonchenlijian:FastBle:2.5.0. Note that the release list only goes up to 2.4.0, so check which version resolves.

## Sources

- [Issues](https://github.com/Jasonchenlijian/FastBle/issues)
- [Jasonchenlijian/FastBle on GitHub](https://github.com/Jasonchenlijian/FastBle)
- [License: Apache-2.0](https://github.com/Jasonchenlijian/FastBle/blob/master/LICENSE)
- [README](https://github.com/Jasonchenlijian/FastBle/blob/master/README.md)
- [Releases](https://github.com/Jasonchenlijian/FastBle/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jasonchenlijian-fastble