This library allows for easy access to a Bluetooth LE device's AdRecord and RSSI value. It offers additional functionality for iBeacons.

Overview

Bluetooth LE Library for Android

This library allows for easy access to a Bluetooth LE device's Advertisement Records. It also offers:

  • A simple running average RSSI reading keeping.
  • For iBeacons: Manufacturer data record parser.
  • For iBeacons: Distance indicators (Near, Far, Immediate, Unknown).
  • For iBeacons: A decently inaccurate (due to real world issues) distance approximation.
  • All the new object types are Parcelable.

This will only work on devices with Android 4.3 (API Level 18) and above.

Get it on Google Play

Including the Library in Your Project

This project is available as an artifact for use with Gradle. To use that, add the following blocks to your build.gradle file:

	repositories {
		maven {
			url "https://dl.bintray.com/alt236/maven"
		}
	}

	dependencies {
		compile 'uk.co.alt236:bluetooth-le-library-android:1.0.0'
	}

If you really need a Jar file, fork the project and execute ./gradlew clean build generateRelease at the root of the project. This will create a zip file under <PROJECT_ROOT>/library/build/ the Jar can be found inside.

Using the Library

In the onLeScan() method of your BluetoothAdapter.LeScanCallback() create a new BluetoothLeDevice with the given information.

For example:

	private BluetoothAdapter.LeScanCallback mLeScanCallback = new BluetoothAdapter.LeScanCallback() {

		@Override
		public void onLeScan(final BluetoothDevice device, int rssi, byte[] scanRecord) {

			final BluetoothLeDevice deviceLe = new BluetoothLeDevice(device, rssi, scanRecord, System.currentTimeMillis());

			runOnUiThread(new Runnable() {
				@Override
				public void run() {
					mDeviceStore.addDevice(deviceLe);
					mLeDeviceListAdapter.replaceData(mDeviceStore.getDeviceList());
				}

			});
		}
	};

Device Properties

Once you have created a device, you can access the following methods:

  • getAddress() : Gets the MAC Address of the device
  • getAdRecordStore(): Gives access to a device's Ad Records
  • getDevice(): Gives access to the standard BluetoothDevice object
  • getFirstRssi(): Retrieves the RSSI value which was used when the object was created
  • getFirstTimestamp() Retrieves the timestamp (in millis) which was used when the object was created
  • getRssi() Gets the current RSSI measurement (see note below).
  • getScanRecord() Retrieves the RAW scan record array
  • getTimestamp() Gets the timestamp of the last RSSI measurement
  • getRunningAverageRssi() Retrieves the internally calculated running average RSSI value (see note below).

Note: The Running Average RSSI is not updated automatically (i.e. the library does not monitor on its own in the background). To add another measurement, you need to call updateRssiReading(long timestamp, int rssiReading).

Accessing the Advertisement (Ad) Records

Once you've created a BluetoothLe device, you can access the AdRecord store via the leDevice.getAdRecordStore(). Once you have the AdRecordStore you can use the following methods:

  • getRecord(int recordNo): Gets the AdRecord object corresponding to the recordNumber.
  • getRecordDataAsString(int recordNo) : Gets the AdRecord contents as a String (expect non printable characters in most cases).
  • isRecordPresent(int recordNo): Checks to see if a record exists.

Note: Record numbers are declared in the Bluetooth 4 spec which can be found here. They are also declared as constants in AdRecord.java.

Fun with iBeacons

You can check if a device is an iBeacon by using BeaconUtils.getBeaconType(BluetootLeDevice device). Once you have confirmed that it is, you can create a new IBeaconDevice via the IBeaconDevice constructor.

Example Flow:

	final BluetoothLeDevice device = ... // A generic BLE device

	if (BeaconUtils.getBeaconType(device) == BeaconType.IBEACON) {
		final IBeaconDevice iBeacon = new IBeaconDevice(device);
		// DO STUFF
	}

An IBeaconDevice extends BluetoothLeDevice, so you still have access to the same methods as before. In addition you can do the following:

  • getAccuracy(): Gets the estimated Accuracy of the reading in meters based on a simple running average calculation
  • getCalibratedTxPower(): Gets the calibrated TX power of the iBeacon device as reported
  • getCompanyIdentifier(): Gets the iBeacon company identifier (this should always be 0x004C for Apple)
  • getDistanceDescriptor(): Gets the estimated Distance descriptor (an enum)
  • getIBeaconData(): Gets the raw IBeaconManufacturerData object.
  • getUUID(): Gets the device's UUID
  • getMajor(): Gets the device's Major value
  • getMinor(): Gets the device's Minor value

Lookup Functions

You can also lookup values and convert them to human friendly strings:

  • BluetoothClassResolver.resolveDeviceClass(int btClass): Will try to resolve a Blueotooth Device class
  • CompanyIdentifierResolver.getCompanyName(int companyId, String fallback): Will try to resolve a Company identifier to the company name
  • GattAttributeResolver.getAttributeName(String uuid, String fallback): Will try to convert a UUID to its name.

Note: The data can be found as ODS (Open Office Spreadsheets) in the documents folder.

Library Changelog

  • v0.0.1
    • First public release
  • v0.0.2:
    • Attempting to create an iBeaconDevice from a device which is not an iBeacon will now throw an IllegalArgumentException exception.
    • Fixed a ConcurrentModificationException on getRunningAverageRssi()
    • Added some Estimote UUIDs
  • v1.0.0:
    • Migrated project to Android Studio/ gradle
    • Note that the API has slightly changed in this version.
    • We now use the more generic BeaconUtils.getBeaconType() method instead of IBeaconUtils.isThisAnIBeacon()
    • Fix for issue 5
    • Fix for issue 9

Sample Application Changelog

  • v0.0.1
    • First public release
  • v0.0.2:
    • Can now export scanned devices as a CSV file.
  • v0.0.3:
    • UI Refresh.
  • v1.0.0:
    • Migrated project to Android Studio/ gradle
    • Using version v1.0.0 of the library project
  • v1.1.0:
    • App refactor and materialisation.
    • Added runtime permissions.
  • v1.1.1:

Permission Explanation

You will need the following permissions to access the Bluetooth Hardware

  • android.permission.BLUETOOTH
  • android.permission.BLUETOOTH_ADMIN

In addition one of the following is needed from API 23 and above to scan for BT LE devices:

  • android.permission.ACCESS_COARSE_LOCATION
  • android.permission.ACCESS_FINE_LOCATION

TODO

  • Tidy up Javadoc. There is quite a lot of it that is template
  • Add parsers for common Ad Records.

Links

Credits

Author: Alexandros Schillings.

All logos are the property of their respective owners.

The code in this project is licensed under the Apache Software License 2.0.

Copyright (c) 2014-2017 Alexandros Schillings.

Comments
  • Android 6.0 not in LeScanCallback

    Android 6.0 not in LeScanCallback

    In Android 6.0 appear information log below: D/BluetoothAdapter: startLeScan(): null And the program not in LeScanCallback (onLeScan), what's wrong with it ? thanks~

    opened by WeberHsu 7
  • Some issue in GattAttributeResolver

    Some issue in GattAttributeResolver

    The service or characteristic id may have some error, for example: public static final String LINK_LOSS = "00001804-0000-1000-8000-00805f9b34fb"; it should be 1803 for LINK_LOSS

    opened by greatwh 2
  • what kind of beacon format (ibeacon)

    what kind of beacon format (ibeacon)

    hi all, in my beacon device , can't assert as BeaconType.IBEACON. how to revise it ?

    02,0x1 04,no connected 1A,data len FF,Manufacture uuid ,major and minor id . 590002150112233445566778899AABBCCDDEEFF001020304

    beacon raw data: 0x0201041AFF590002150112233445566778899AABBCCDDEEFF001020304C3

    android ,6.0 android studio 3.01

    opened by amigomcu 1
  • Meaning of these values in the accurancy calculation

    Meaning of these values in the accurancy calculation

    ...in this method:

    protected static double calculateAccuracy(int txPower, double rssi) {
      if (rssi == 0) {
        return -1.0; // if we cannot determine accuracy, return -1.
      }
    
      double ratio = rssi*1.0/txPower;
      if (ratio < 1.0) {
        return Math.pow(ratio,10);
      }
      else {
        double accuracy =  (0.89976)*Math.pow(ratio,7.7095) + 0.111;    //these
        return accuracy;
      }
    }   
    
    thanks
    
    
    opened by redirect11 1
  • Question about sample app: `cannot resolve objectcursor`

    Question about sample app: `cannot resolve objectcursor`

    Everything is resolving properly except for objectcursor. I went through code, searched on GitHub and googled. But I couldn't find a reference anywhere. What do I do? How do I resolve this properly? screen shot 2014-09-12 at 11 49 16 am

    opened by dhilipsiva 1
  • Fixed typographical error, changed advertisment to advertisement in README.

    Fixed typographical error, changed advertisment to advertisement in README.

    @alt236, I've corrected a typographical error in the documentation of the Bluetooth-LE-Library---Android project. You should be able to merge this pull request automatically. However, if this was intentional or if you enjoy living in linguistic squalor, please let me know and create an issue on my home repository.

    opened by orthographic-pedant 0
  • Small change to properly format the UUID

    Small change to properly format the UUID

    The current implementation removes any leading zeros from a byte thus the bytes "AB 01 02" will be converted to the string "AB12".

    opened by ncichris 0
  • Raw AD record display missing some bytes?

    Raw AD record display missing some bytes?

    This shows #9 Name having 26 characters when shown "As String", which is correct. But the display "As Array" only shows the last 24 characters. SmartSelect_20200421-173709_Bluetooth LE Scanner

    opened by LenShustek 1
  • Advertisement record lengths are incorrectly handled

    Advertisement record lengths are incorrectly handled

    Since in Java all primitive types are signed, we could receive a negative advertisement length. In that case, the library doesn't consider this case and it must be converted to unsigned int.

    opened by XabierGoros 0
  • Unable to include Library to my project

    Unable to include Library to my project

    I am new to this android development. I am making an app to detect the BLE attributes of my Eddystone beacon. screen shot 2018-04-04 at 4 34 42 pm

    It is showing an error in onLeScan method. I would really appreciate if someone can help.

    Thanks

    opened by SupreetKaurP 0
  • scanning the ble of ibeacon, Glide+okhttp3 load image very slow from server.

    scanning the ble of ibeacon, Glide+okhttp3 load image very slow from server.

    When the application starts, I first open the intentservice to download the audio, then opened the service to scan the Bluetooth equipment ibeacon. At this point, I found the picture from the server to download very slowly, in the local load is not affected.

    I think the child thread may be blocked, how to solve it.

    android os: huawei 6.0 and xiaomi 5.0

    opened by Owen-Hw 0
Releases(app_v1.1.1)
Owner
Alexandros Schillings
Alexandros Schillings
Android Bluetooth Helper Library, Bluetooth Device Finder

Bluetooth Helper Allows you to access the Bluetooth of your mobile device, manage turn-on - turn off, and discover bluetooth devices around you. Getti

Tolga Bolatcan 44 Jul 15, 2022
[UNMAINTAINED][Android] Bluetooth Serial Port Profile which comfortable to developer application to communication with microcontroller via bluetooth

⚠ WARNING: This project is no longer being maintained Android-BluetoothSPPLibrary Bluetooth Serial Port Profile which comfortable to developer applica

Akexorcist 1.7k Dec 31, 2022
Smooth communication via bluetooth with other android devices or microcontrollers such as Arduino.

Android Smooth Bluetooth Smooth communication via bluetooth with other android devices or microcontrollers such as Arduino. Getting Started Add Gradle

Mantas Palaima 191 Nov 28, 2022
An Android Library for handling Bluetooth Low Energy on Android Easy

An Android Library for handling Bluetooth Low Energy on Android Easy

Leandro SQ 42 Jan 3, 2023
A Bluetooth kotlin multiplatform "Cross-Platform" library for iOS and Android

Blue-Falcon A Bluetooth "Cross Platform" Kotlin Multiplatform library for iOS, Android, MacOS, Raspberry Pi and Javascript. Bluetooth in general has t

Andrew Reed 220 Dec 28, 2022
A reactive, interface-driven central role Bluetooth LE library for Android

RxCentralBle RxCentralBle provides a simple reactive paradigm for connecting to and communicating with Bluetooth LE peripherals from the central role.

Uber Open Source 198 Nov 29, 2022
An Android library that solves a lot of Android's Bluetooth Low Energy problems

A library that makes working with Bluetooth LE on Android a pleasure. Seriously.

Nordic Semiconductor 1.4k Jan 7, 2023
BLESSED Coroutines, a Bluetooth Low Energy (BLE) library for Android using Kotlin Coroutines

BLESSED for Android with Coroutines - BLE made easy BLESSED is a very compact Bluetooth Low Energy (BLE) library for Android 8 and higher, that makes

Martijn van Welie 82 Jan 1, 2023
A non-trivial Bluetooth LE app using Kable and app architecture best practices

kable_mvvm_demo The intention of this project is to demonstrate a non-trivial Bluetooth LE app using Kable and app architecture best practices. ⚠️ The

Chris Laplante 14 Aug 18, 2022
BluePass extracts two factor authentication codes (2FA) from SMS and sends them to a paired device via Bluetooth RFCOMM.

BluePass extracts two factor authentication codes (2FA) from SMS and sends them to a paired device via Bluetooth RFCOMM.

Manuel Huber 15 Dec 4, 2022
Open-source weight and body metrics tracker, with support for Bluetooth scales

Open-source weight and body metrics tracker, with support for Bluetooth scales

OliE 1.3k Jan 4, 2023
Kotlin Asynchronous Bluetooth Low-Energy

Kable Kotlin Asynchronous Bluetooth Low Energy provides a simple Coroutines-powered API for interacting with Bluetooth Low Energy devices. Usage is de

JUUL Labs 493 Dec 25, 2022
Simple bluetooth flutter project

bluetooth_simple Simple bluetooth implementation. Getting Started This project is a starting point for a Flutter application. A few resources to get y

Aleksey Vasiliev 0 Nov 25, 2021
The purpose is to share the Internet capability of one device to the entire Bluetooth LAN.

bluenet The purpose is to share the Internet capability of one device to the entire Bluetooth LAN. To make a prototype of a soft bus, or actually, I w

yunlong.wen 1 Jun 28, 2022
User-friendly Lightweight TPM Remote Attestation over Bluetooth

Ultrablue Ultrablue (User-friendly Lightweight TPM Remote Attestation over Bluetooth) is a solution to allow individual users to perform boot state at

ANSSI 32 Jan 2, 2023
RxBle: Use Android Bluetooth API in Rx way

RxBle: Use Android Bluetooth API in Rx way A lightweight encapsulation of Android Bluetooth API. Use Android Bluetooth API in Rx way. Support multiple

null 3 Dec 2, 2022
Allows Android apps to interact with BLE beacons

Android Beacon Library An Android library providing APIs to interact with beacons. Please visit the project website for how to use this library. IMPOR

AltBeacon 2.7k Dec 28, 2022
A simple, lightweight library intended to take away some of the cruft and tediousness of using the Android BLE.

Blueteeth What Is Blueteeth? Blueteeth is a simple, lightweight library intended to take away some of the cruft and tediousness of using the Android B

Robot Pajamas 103 Nov 26, 2022
🍔 Meals is a small demo app based on modern Android technologies and MVVM architecture

Meals ?? Meals is a small demo app based on modern Android technologies and MVVM architecture. built-in Kotlin, Coroutine, Flow, Retrofit, and Jetpack

Amr Jyniat 4 Nov 6, 2022