If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Jasonchenlijian/FastBle shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 3w ago
• 2 active contributors
• Apache-2.0 licensed
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 97% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Jasonchenlijian/FastBle repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Jasonchenlijian/FastBle.

What it runs against: a local clone of Jasonchenlijian/FastBle — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Jasonchenlijian/FastBle | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 51 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Jasonchenlijian/FastBle. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Jasonchenlijian/FastBle.git
#   cd FastBle
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Jasonchenlijian/FastBle and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Jasonchenlijian/FastBle(\\.git)?\\b" \\
  && ok "origin remote is Jasonchenlijian/FastBle" \\
  || miss "origin remote is not Jasonchenlijian/FastBle (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "FastBleLib/src/main/java/com/clj/fastble/BleManager.java" \\
  && ok "FastBleLib/src/main/java/com/clj/fastble/BleManager.java" \\
  || miss "missing critical file: FastBleLib/src/main/java/com/clj/fastble/BleManager.java"
test -f "FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java" \\
  && ok "FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java" \\
  || miss "missing critical file: FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java"
test -f "FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleConnector.java" \\
  && ok "FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleConnector.java" \\
  || miss "missing critical file: FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleConnector.java"
test -f "FastBleLib/src/main/java/com/clj/fastble/scan/BleScanner.java" \\
  && ok "FastBleLib/src/main/java/com/clj/fastble/scan/BleScanner.java" \\
  || miss "missing critical file: FastBleLib/src/main/java/com/clj/fastble/scan/BleScanner.java"
test -f "FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java" \\
  && ok "FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java" \\
  || miss "missing critical file: FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 51 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~21d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Jasonchenlijian/FastBle"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

FastBle is an Android Bluetooth Low Energy (BLE) development framework that abstracts Android's complex BluetoothGatt API into simple, chainable methods for scanning, connecting, reading, writing, and listening to notifications across multiple devices simultaneously. It handles low-level GATT callbacks, MTU negotiation, RSSI reading, and connection state management so developers can implement BLE functionality in 5–10 lines of code instead of 200+ lines of boilerplate. Single-module library structure: FastBleLib/src/main/java/com/clj/fastble/ contains the core, organized by responsibility — bluetooth/ (BleBluetooth.java, BleConnector.java for device logic), callback/ (11 callback interfaces for lifecycle events), scan/ (BleScanPresenter, BleScanner for discovery), data/ (model classes: BleDevice, BleMsg), exception/ (custom exceptions), and utils/ (HexUtil, BleLog, BleLruHashMap). The companion app/ demonstrates usage. No separate test directory visible.

Android developers building IoT/wearable companion apps, fitness trackers, health monitors, or any app requiring BLE communication with peripherals (e.g., smartwatches, heart-rate monitors, wireless headsets) who need to avoid writing custom BluetoothGattCallback handlers and state machines.

Actively maintained, production-ready framework. Latest version 2.5.0 targets Android 21–35 (API 5.0–15). Build is configured for Java 17 and modern Android Studio (Ladybug 2024.2+). No visible CI/CD pipeline or automated tests in the repo structure, but the project is stable with a working example app and distributed AAR artifacts. Suitable for production use if your team can handle BLE-specific edge cases independently.

Single maintainer (Jasonchenlijian) with no visible test suite or CI automation increases maintenance risk if the author becomes unavailable. The framework has zero external dependencies (good for stability, risky if Android BLE APIs break), and there is no changelog documenting breaking changes between versions. Android BLE stack itself is notoriously inconsistent across OEM implementations, so device-specific bugs may not be caught by this framework alone.

The repo shows a completed v2.5.0 release with prebuilt AAR and APK artifacts. No recent commit timestamps are visible in the provided data, so the active development status is unclear. The structure suggests the core feature set (scan, connect, read, write, notify, RSSI, MTU, multiconnect) is complete and stable, not under active feature development.

git clone https://github.com/Jasonchenlijian/FastBle.git
cd FastBle
# Open in Android Studio (Ladybug 2024.2+) or build via Gradle
./gradlew build
# Or import FastBleLib as a library module into your project

Add to your build.gradle: implementation 'com.github.Jasonchenlijian:FastBle:2.5.0' (requires JitPack in repositories).

Daily commands: Import FastBleLib as a module into your Android Studio project, or build the AAR: ./gradlew -p FastBleLib build. The example app (app/ directory) can be run via Android Studio's Run button or ./gradlew installDebug.

• FastBleLib/src/main/java/com/clj/fastble/BleManager.java — Primary entry point and facade for all BLE operations; all developers must understand the API surface and initialization pattern
• FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java — Core BLE connection abstraction wrapping Android's BluetoothGatt; essential for understanding device lifecycle and callback handling
• FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleConnector.java — Manages connection establishment and state transitions; critical for debugging connection issues and multi-device scenarios
• FastBleLib/src/main/java/com/clj/fastble/scan/BleScanner.java — Implements the scanning discovery mechanism with filter rules; entry point for understanding device discovery flow
• FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java — Central GATT callback handler for read/write/notify operations; must understand to troubleshoot data exchange failures
• FastBleLib/src/main/java/com/clj/fastble/data/BleDevice.java — Data model for discovered BLE devices; fundamental to understanding how device state is tracked throughout the framework
• FastBleLib/src/main/java/com/clj/fastble/bluetooth/MultipleBluetoothController.java — Manages concurrent multi-device connections; essential for understanding connection pooling and resource management

Add a New BLE Operation Type

1. Create a new callback interface extending BleBaseCallback in the callback package (FastBleLib/src/main/java/com/clj/fastble/callback/)
2. Implement operation logic in BleGattCallback or create a new handler method (FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java)
3. Add public method in BleManager to expose the operation with timeout handling (FastBleLib/src/main/java/com/clj/fastble/BleManager.java)
4. Update BleBluetooth to queue the operation if needed (FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java)

Add Device Scan Filtering Rules

1. Modify BleScanRuleConfig to add new filter parameters (FastBleLib/src/main/java/com/clj/fastble/scan/BleScanRuleConfig.java)
2. Update BleScanPresenterImp to apply the new filter logic in isMatch() (FastBleLib/src/main/java/com/clj/fastble/callback/BleScanPresenterImp.java)
3. Call BleManager.initScanRule() with configured BleScanRuleConfig before scanning (FastBleLib/src/main/java/com/clj/fastble/BleManager.java)

Implement Custom Connection Retry Logic

1. Extend BleConnector or override retry behavior in BleBluetooth (FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleConnector.java)
2. Modify connection timeout and retry counts via BleManager configuration methods (FastBleLib/src/main/java/com/clj/fastble/BleManager.java)
3. Hook into BleGattCallback.onConnectStateChange() to implement custom reconnection strategy (FastBleLib/src/main/java/com/clj/fastble/callback/BleGattCallback.java)

Add Support for Large Data Transfers

1. Review SplitWriter.write() for MTU-aware splitting behavior (FastBleLib/src/main/java/com/clj/fastble/bluetooth/SplitWriter.java)
2. Use BleManager.setMtu() before large writes to negotiate optimal MTU size (FastBleLib/src/main/java/com/clj/fastble/BleManager.java)
3. Implement chunking logic in application code using write callbacks to track progress (app/src/main/java/com/clj/blesample/operation/CharacteristicOperationFragment.java)

Runtime permissions required: Despite the README claiming 'no need to add permissions', you must request Bluetooth, BLE, location (for scan) at runtime on Android 6.0+ — the library only declares them in manifest. Device-specific quirks: Many Android OEM implementations have BLE stack bugs (e.g., Samsung, Huawei); this framework does not abstract them away — you may need device-specific workarounds. Callback threading: All callbacks execute on the Bluetooth handler thread, not the main thread — don't update UI directly or call BleManager methods inside callbacks without thread switching. MTU negotiation timing: MTU must be set after connection but some devices ignore the request silently; no fallback mechanism. No automatic descriptor writes: Enabling notifications requires writing a CCCD descriptor (0x2902) — the framework handles this, but if custom descriptors are needed, you must write them manually. Timeout behavior: Default timeout is configurable but hardcoded as global — no per-operation timeout override.

• BluetoothGattCallback state machine — FastBle's core — understanding how BleConnector wraps Android's async GATT callbacks into connection state transitions is essential to extending the library or debugging connection hangs
• Generic Attribute Profile (GATT) — services, characteristics, descriptors — FastBle abstracts GATT discovery and I/O; knowing the hierarchy (service UUID → characteristic UUID → descriptor) is needed to configure filters and read/write the correct attributes
• Client Characteristic Configuration Descriptor (CCCD) 0x2902 — Enabling notifications requires writing the CCCD; FastBle handles this internally in BleBluetooth.java, but understanding it helps debug notification failures
• MTU (Maximum Transmission Unit) negotiation — BLE MTU defaults to 23 bytes for data; FastBle provides setMTU() but negotiation timing is device-specific and can silently fail — this is a hidden complexity in multi-device scenarios
• LRU (Least Recently Used) cache for connection pooling — MultipleBluetoothController uses BleLruHashMap to manage multiple simultaneous device connections; understanding eviction policy is critical for high-device-count scenarios
• Android runtime permissions for location and Bluetooth — BLE scanning on Android 6.0+ requires location permission at runtime, even though the device only needs Bluetooth capability — a hidden requirement not obvious from the API alone
• OEM-specific BLE stack bugs and workarounds — Android BLE behavior varies widely across manufacturers; FastBle does not abstract these — device-specific timeouts, reconnection delays, and GATT errors require empirical testing on target hardware

• noble/noble — Cross-platform BLE library for Node.js; comparable abstraction layer over system BLE APIs but for desktop/server instead of Android
• polidea/RxAndroidBle — Reactive (RxJava2/3) BLE wrapper for Android; same problem domain but uses modern reactive patterns instead of callbacks
• android/connectivity-samples — Google's official Android Bluetooth LE samples repo; low-level reference implementations that FastBle abstracts away
• AltBeacon/android-beacon-library — Android BLE library focused on beacon scanning/ranging; overlaps with FastBle's scan features but specialized for iBeacon/Eddystone discovery
• Jasonchenlijian/EasyBluetooth — Earlier project by the same author for classic Bluetooth (BR/EDR); shows evolution from classic to BLE abstraction

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for BleManager and BleBluetooth core classes

The repo lacks unit tests for critical BLE operations. BleManager.java and BleBluetooth.java handle connection lifecycle, scan filtering, and device state management - core functionality that should have test coverage. This improves code reliability and prevents regressions in future releases.

• [ ] Create FastBleLib/src/test/java/com/clj/fastble/BleManagerTest.java with tests for init(), scan(), connect(), disconnect() methods
• [ ] Create FastBleLib/src/test/java/com/clj/fastble/bluetooth/BleBluetoothTest.java testing connection state transitions and callback handling
• [ ] Create FastBleLib/src/test/java/com/clj/fastble/scan/BleScanRuleConfigTest.java for scan filter validation logic
• [ ] Add Mockito/JUnit4 test dependencies to FastBleLib/build.gradle
• [ ] Ensure tests cover edge cases like null callbacks, rapid connect/disconnect, and timeout scenarios

Implement GitHub Actions CI/CD workflow for automated testing and AAR artifact publishing

The repo has a manual makeAAR task and no CI pipeline. Automating builds, tests, and releases (on version tags) would improve code quality, reduce manual errors, and make the library more trustworthy for contributors. This directly supports the existing build.gradle configuration.

• [ ] Create .github/workflows/build-and-test.yml that runs ./gradlew build and test on every push to main
• [ ] Add artifact upload step in workflow to publish FastBLE-*.aar to GitHub Releases on version tag pushes
• [ ] Configure workflow to validate ProGuard rules and check for minification issues in release builds
• [ ] Add status badge to README.md linking to workflow results
• [ ] Test workflow locally using act before merging

Add comprehensive exception handling documentation and add missing BleException subclasses for timeout/state scenarios

The exception module (FastBleLib/src/main/java/com/clj/fastble/exception/) has TimeoutException and ConnectException, but missing exceptions for common BLE failures (e.g., characteristic not found, service unavailable, MTU negotiation failure). Adding these with clear documentation helps developers handle errors gracefully.

• [ ] Create FastBleLib/src/main/java/com/clj/fastble/exception/CharacteristicNotFoundException.java and ServiceNotFoundException.java
• [ ] Create FastBleLib/src/main/java/com/clj/fastble/exception/MtuException.java for MTU negotiation failures
• [ ] Update all callback classes (BleReadCallback.java, BleWriteCallback.java, etc.) to throw/document specific exception types
• [ ] Create docs/EXCEPTION_HANDLING.md documenting all exception types, their causes, and recovery strategies
• [ ] Update sample app (app/src/main/java/com/clj/blesample/MainActivity.java) to demonstrate proper exception handling for each callback type

• Add unit tests for BleDevice model and state transitions: No test directory exists. Start by writing JUnit tests for FastBleLib/src/main/java/com/clj/fastble/data/BleDevice.java to verify connection state transitions (IDLE → CONNECTING → CONNECTED → DISCONNECTED) and RSSI updates.
• Document callback threading model in javadoc comments: The 11 callback interfaces in FastBleLib/src/main/java/com/clj/fastble/callback/ lack thread-safety warnings. Add clear @ThreadSafe or @NotThreadSafe annotations and examples showing how to marshal calls back to the main thread in BleBaseCallback.java and each subclass.
• Add example for scanning with UUID filter and multi-device write: The demo app likely covers basic cases. Add a complete example in app/src showing how to filter scan results by service UUID (using BleScanRuleConfig), connect to multiple devices simultaneously via MultipleBluetoothController, and write data to the same characteristic on all devices in parallel with timeout handling.

• High · Minification Disabled in Release Build — FastBleLib/build.gradle - buildTypes.release.minifyEnabled. The build.gradle file has minifyEnabled set to false in the release build configuration. This means the compiled APK/AAR will not be obfuscated, making the code easily decompilable and allowing attackers to reverse-engineer the implementation, understand the logic flow, and identify potential security weaknesses. Fix: Set minifyEnabled to true and ensure proper ProGuard/R8 configuration rules are in place. Review and update proguard-rules.pro to keep necessary classes/methods while obfuscating sensitive logic.
• High · Bluetooth Permissions Not Explicitly Validated at Runtime — FastBleLib/src/main/java/com/clj/fastble/ (entire BLE module). BLE operations require BLUETOOTH, BLUETOOTH_ADMIN, and on Android 6.0+ require location permissions (ACCESS_FINE_LOCATION). The file structure shows BLE implementation but no visible permission validation patterns. If permissions are not checked at runtime before BLE operations, the app may crash or fail unexpectedly on Android 6.0+. Fix: Implement runtime permission checks using Android's checkSelfPermission() or AndroidX's ActivityCompat before initiating BLE scan and connection operations. Validate permissions explicitly for BLUETOOTH, BLUETOOTH_ADMIN, and location permissions on Android 6.0+.
• Medium · No Visible Input Validation in Callback Handlers — FastBleLib/src/main/java/com/clj/fastble/callback/. Multiple callback classes (BleGattCallback, BleReadCallback, BleWriteCallback, etc.) handle data from Bluetooth devices. Without visible input validation, the app may be vulnerable to malformed data attacks from rogue BLE devices that could cause crashes, buffer overflows, or unexpected behavior. Fix: Implement strict input validation in all callback handlers. Validate data length, format, and range before processing. Use try-catch blocks to handle unexpected data gracefully. Add bounds checking for byte arrays and data parsing operations.
• Medium · Potential Man-in-the-Middle Vulnerability in BLE Communication — FastBleLib/src/main/java/com/clj/fastble/bluetooth/BleBluetooth.java, BleConnector.java. BLE communication over the air can be vulnerable to interception and modification attacks. The codebase does not show evidence of encryption or authentication mechanisms for data transmitted over BLE, beyond what the BLE protocol itself provides. Fix: Implement application-level encryption for sensitive data using industry-standard encryption (AES-256). Consider implementing certificate pinning or device authentication. Use BLE's built-in security features (pairing, bonding) and enforce encryption at the GATT level.
• Medium · Hardcoded Logging May Expose Sensitive Information — FastBleLib/src/main/java/com/clj/fastble/utils/BleLog.java. The presence of BleLog.java suggests extensive logging throughout the BLE operations. Debug logs may contain sensitive information such as device addresses, UUIDs, or data payloads. In production builds, these logs could be accessed by other apps on the device. Fix: Ensure logging is disabled or controlled in production builds. Use conditional logging based on BuildConfig.DEBUG flag. Implement log filtering to prevent sensitive data (addresses, UUIDs, raw data) from being logged in production.
• Medium · No Evidence of Secure Key/Credential Storage — FastBleLib/src/main/java/com/clj/fastble/ (general). If the BLE framework is used to handle sensitive data or authentication tokens, there is no visible implementation of Android's KeyStore or encrypted SharedPreferences for secure credential storage. Fix: If sensitive data needs to be stored, use Android's KeyStore for cryptographic key storage or use EncryptedSharedPreferences from AndroidX security library. Never store credentials or sensitive tokens in plain SharedPreferences.
• Low · Missing INTERNET Permission Declaration — app/src/main/AndroidManifest.xml. While BLE is primarily local, if the sample app (app/) uses network functionality, the AndroidManifest.xml should explicitly declare required permissions. Overly permissive permissions can increase attack surface. Fix: Declare only the permissions actually needed

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.