{"id":18784468,"url":"https://github.com/pwittchen/reactivebeacons","last_synced_at":"2025-08-21T06:31:26.050Z","repository":{"id":57722219,"uuid":"43156715","full_name":"pwittchen/ReactiveBeacons","owner":"pwittchen","description":"Android library scanning BLE beacons nearby with RxJava","archived":false,"fork":false,"pushed_at":"2020-08-19T08:52:11.000Z","size":552,"stargazers_count":169,"open_issues_count":18,"forks_count":38,"subscribers_count":10,"default_branch":"RxJava2.x","last_synced_at":"2024-12-10T08:42:31.880Z","etag":null,"topics":["android","beacon","ble","bluetooth","bluetooth-low-energy","eddystone","estimote","ibeacon","indoor-positioning","kontaktio","rxandroid","rxandroid2","rxjava","rxjava2"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pwittchen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":["pwittchen"],"custom":["https://paypal.me/pwittchen"]}},"created_at":"2015-09-25T15:44:33.000Z","updated_at":"2024-11-07T13:52:23.000Z","dependencies_parsed_at":"2022-08-29T23:01:10.897Z","dependency_job_id":null,"html_url":"https://github.com/pwittchen/ReactiveBeacons","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwittchen%2FReactiveBeacons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwittchen%2FReactiveBeacons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwittchen%2FReactiveBeacons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pwittchen%2FReactiveBeacons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pwittchen","download_url":"https://codeload.github.com/pwittchen/ReactiveBeacons/tar.gz/refs/heads/RxJava2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230494921,"owners_count":18235046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","beacon","ble","bluetooth","bluetooth-low-energy","eddystone","estimote","ibeacon","indoor-positioning","kontaktio","rxandroid","rxandroid2","rxjava","rxjava2"],"created_at":"2024-11-07T20:43:07.302Z","updated_at":"2024-12-19T20:08:41.983Z","avatar_url":"https://github.com/pwittchen.png","language":"Java","readme":"# ReactiveBeacons\n\n[![Android Arsenal](https://img.shields.io/badge/Android%20Arsenal-ReactiveBeacons-brightgreen.svg?style=flat-square)](http://android-arsenal.com/details/1/2576)\n\n| Current Branch | Branch  | Artifact Id | Build Status  | Maven Central |\n|:--------------:|:-------:|:-----------:|:-------------:|:-------------:|\n| | [`RxJava1.x`](https://github.com/pwittchen/ReactiveBeacons/tree/RxJava1.x) | `reactivebeacons` | [![Build Status for RxJava1.x](https://img.shields.io/travis/pwittchen/ReactiveBeacons/RxJava1.x.svg?style=flat-square)](https://travis-ci.org/pwittchen/ReactiveBeacons) | ![Maven Central](https://img.shields.io/maven-central/v/com.github.pwittchen/reactivebeacons.svg?style=flat-square) |\n| :ballot_box_with_check: | [`RxJava2.x`](https://github.com/pwittchen/ReactiveBeacons/tree/RxJava2.x) | `reactivebeacons-rx2` | [![Build Status for RxJava2.x](https://img.shields.io/travis/pwittchen/ReactiveBeacons/RxJava2.x.svg?style=flat-square)](https://travis-ci.org/pwittchen/ReactiveBeacons) |![Maven Central](https://img.shields.io/maven-central/v/com.github.pwittchen/reactivebeacons-rx2.svg?style=flat-square) |\n\n\nThis is **RxJava2.x** branch. To see documentation for RxJava1.x, switch to [RxJava1.x](https://github.com/pwittchen/ReactiveBeacons/tree/RxJava1.x) branch.\n\nAndroid library scanning BLE (Bluetooth Low Energy) beacons nearby with RxJava\n\nLibrary was tested with Estimote and Kontakt beacons.\n\nThis library has limited functionality, but its API is simple:\n\n```java\nReactiveBeacons(context)\nboolean isBleSupported()\nboolean isBluetoothEnabled()\nboolean isLocationEnabled(context)\nboolean isAtLeastAndroidLollipop()\nvoid requestBluetoothAccess(activity)\nvoid requestLocationAccess(activity)\nObservable\u003cBeacon\u003e observe()\nObservable\u003cBeacon\u003e observe(ScanStrategy scanStrategy)\n```\n\nJavaDoc is available at: http://pwittchen.github.io/ReactiveBeacons/RxJava2.x\n\nmin SDK = 9, but if you are using API level lower than 18, don't forget to [check BLE support](#checking-ble-support) on the device.\n\nContents\n--------\n- [Usage](#usage)\n- [Good practices](#good-practices)\n  - [Updating Manifest](#updating-manifest)\n  - [Checking BLE support](#checking-ble-support)\n  - [Requesting Bluetooth access](#requesting-bluetooth-access)\n  - [Requesting Location access](#requesting-location-access)\n  - [Requesting Runtime Permissions](#requesting-runtime-permissions)\n  - [Exemplary code snippet](#exemplary-code-snippet)\n- [Examples](#examples)\n- [Compatibility with different Android versions](#compatibility-with-different-android-versions)\n- [Beacon class](#beacon-class)\n- [Filter class](#filter-class)\n- [Download](#download)\n- [Tests](#tests)\n- [Code style](#code-style)\n- [Static code analysis](#static-code-analysis)\n- [References](#references)\n- [License](#license)\n\nUsage\n-----\n\n### Step 1\n\nInitialize `ReactiveBeacons` object:\n\n```java\nprivate ReactiveBeacons reactiveBeacons;\n\n@Override protected void onCreate(Bundle savedInstanceState) {\n  reactiveBeacons = new ReactiveBeacons(this);\n}\n```\n\n### Step 2\n\nCreate subscribtion:\n\n```java\nprivate Disposable subscription;\n\n@Override protected void onResume() {\n  super.onResume();\n  \n  if (!reactiveBeacons.isBleSupported()) { // optional, but recommended step\n    // show message for the user that BLE is not supported on the device\n    return;\n  }\n  \n  // we should check Bluetooth and Location access here\n  // if they're disabled, we can request access\n  // if you want to know how to do it, check next sections \n  // of this documentation and sample app\n\n  subscription = reactiveBeacons.observe()\n    .subscribeOn(Schedulers.computation())\n    .observeOn(AndroidSchedulers.mainThread())\n    .subscribe(new Consumer\u003cBeacon\u003e() {\n      @Override public void call(Beacon beacon) {\n        // do something with beacon\n      }\n    });\n}    \n```\n\n### Step 3\n\nUnsubscribe subscription in `onPause()` method to stop BLE scan.\n\n```java\n@Override protected void onPause() {\n  super.onPause();\n  if (subscription != null \u0026\u0026 !subscription.isDisposed()) {\n    subscription.dispose()\n  }\n}\n```\n\n**Please note**: Library may emit information about the same beacon multiple times. New emission is created everytime when RSSI changes. We can distinguish several beacons by their MAC addresses with `beacon.device.getAddress()` method.\n\nGood practices\n--------------\n\n### Updating Manifest\n\nAdd `\u003cuses-feature .../\u003e` tag inside `\u003cmanifest ...\u003e` tag in `AndroidManifest.xml` file in your application if you support Android devices with API level 18 or higher. You can skip this, if you are supporting lower API levels.\n\n```xml\n\u003cuses-feature\n    android:name=\"android.hardware.bluetooth_le\"\n    android:required=\"true\" /\u003e\n```\n\n### Checking BLE support\n\nCheck BLE support if you are supporting devices with API level lower than 18.\n\n```java\nif (!reactiveBeacons.isBleSupported()) {\n  // show message for the user that BLE is not supported on the device\n}\n```\n\nIf BLE is not supported, Observable emitting Beacons will be always empty.\n\n### Requesting Bluetooth access\n\nUse `requestBluetoothAccess(activity)` method to ensure that Bluetooth is enabled.\nIf you are supporting devices with API level lower than 18, you don't have to request Bluetooth access every time.\n\n```java\nif (!reactiveBeacons.isBluetoothEnabled()) {\n  reactiveBeacons.requestBluetoothAccess(activity);\n}\n```\n\n### Requesting Location access\n\nSince API 23 (Android 6 - Marshmallow), Bluetooth Low Energy scan, requires `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` permissions.\nMoreover, we need to enable Location services in order to scan BLE beacons. You don't have to worry about that if your apps are targeted to lower APIs than 23.\nNevertheless, you have to be aware of that, if you want to detect beacons on the newest versions of Android. Read more at: https://code.google.com/p/android/issues/detail?id=190372. Use `requestLocationAccess(activity)` method to ensure that Location services are enabled. If you are supporting devices with API level lower than 18, you don't have to request Location access every time.\n\n```java\nif (!reactiveBeacons.isLocationEnabled(activity)) {\n  reactiveBeacons.requestLocationAccess(activity);\n}\n```\n\n### Requesting Runtime Permissions\n\nSince Android M (API 23), we need to request Runtime Permissions.\nIf we want to scan for BLE beacons, we need to request for `ACCESS_COARSE_LOCATION` or `ACCESS_FINE_LOCATION` permission.\nFor more details, check sample `app`.\n\n### Exemplary code snippet\n\nWith API methods, we can create the following code snippet:\n\n```java\nprivate boolean canObserveBeacons() {\n  if (!reactiveBeacons.isBleSupported()) {\n    Toast.makeText(this, \"BLE is not supported on this device\", Toast.LENGTH_SHORT).show();\n    return false;\n  }\n\n  if (!reactiveBeacons.isBluetoothEnabled()) {\n    reactiveBeacons.requestBluetoothAccess(this);\n    return false;\n  } else if (!reactiveBeacons.isLocationEnabled(this)) {\n    reactiveBeacons.requestLocationAccess(this);\n    return false;\n  } else if (!isFineOrCoarseLocationPermissionGranted()\n             \u0026\u0026 Build.VERSION.SDK_INT \u003e= Build.VERSION_CODES.M) {\n    requestCoarseLocationPermission();\n    return false;\n   }\n\n  return true;\n}\n```\n\nYou can adjust this snippet to your needs or handle this logic in your own way.\n\nAfter that, we can perform the following operation:\n\n```java\nif(canObserveBeacons()) {\n  // observe beacons here\n}\n```\n\nExamples\n--------\n\nExemplary application is located in `app` directory of this repository.\n\nIf you want to know, how to use this library with Kotlin, check `app-kotlin` sample.\n\nCompatibility with different Android versions\n---------------------------------------------\n\nBLE scanning is available from Android 4.3 `JELLY_BEAN_MR2` (API 18).\nYou can use this library on lower versions of Android, but you won't be able to scan BLE devices,\nyou should handle that situation in your app and notify user about that. See [Good practices](#good-practices) section.\nSince Android 5.0 `LOLLIPOP` (API 21), we have different API for BLE scanning.\nThat's why this library has two different BLE scanning strategies:\n- `PreLollipopScanStrategy` used for pre-Lollipop devices (from API 18 to 20)\n- `LollipopScanStrategy` used for Lollipop devices (API 21 or higher)\n\nLibrary automatically chooses proper strategy with `isAtLeastAndroidLollipop()` method,\nwhich checks version of the system installed on a device and uses selected strategy in `Observable\u003cBeacon\u003e observe()` method from the library.\nMoreover, you can force using one of the existing strategies or your own custom scanning strategy\nwith the following method available in the library:\n\n```java\nObservable\u003cBeacon\u003e observe(ScanStrategy scanStrategy)\n```\n\n`ScanStrategy` is an interface with the following method:\n\n```java\nObservable\u003cBeacon\u003e observe();\n```\n\nBeacon class\n------------\n\n`Beacon` class represents BLE beacon and has the following attributes:\n\n```java\nBluetoothDevice device;\nint rssi;\nbyte[] scanRecord;\nint txPower;\n```\n\nAll of the elements are assigned dynamically, but `txPower` has default value equal to `-59`.\nIt works quite fine for different types of beacons.\n\nBeacon class has also `getDistance()` method, which returns distance from mobile device to beacon in meters and `getProximity()` method, which returns `Proximity` value.\n\n`Proximity` can be as follows:\n- `IMMEDIATE` - from 0m to 1m\n- `NEAR` - from 1m to 3m\n- `FAR` - more than 3m\n\nBeacon class has also static `create(...)` method responsible for creating Beacon objects.\n\nFilter class\n------------\n\n`Filter` class provides static filtering methods, which can be used with RxJava `filter(...)` method inside specific subscription.\n\nCurrently the following filters are available:\n- `proximityIsEqualTo(Proximity)`\n- `proximityIsNotEqualTo(Proximity)`\n- `distanceIsEqualTo(double)`\n- `distanceIsGreaterThan(double)`\n- `distanceIsLowerThan(double)`\n- `hasName(String)`\n- `hasMacAddress(String)`\n\nOf course, we can create our own custom filters, which are not listed above if we need to.\n\n**Exemplary usage**\n\nIn the example below, we are filtering all Beacons with `Proximity` equal to `NEAR` value.\n\n```java\nreactiveBeacons.observe()\n    .filter(Filter.proximityIsEqualTo(Proximity.NEAR))\n    .subscribe(new Consumer\u003cBeacon\u003e() {\n      @Override public void call(Beacon beacon) {\n        beacons.put(beacon.device.getAddress(), beacon);\n        refreshBeaconList();\n      }\n    });\n```    \n\nDownload\n--------\n\nYou can depend on the library through Maven:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.github.pwittchen\u003c/groupId\u003e\n    \u003cartifactId\u003ereactivebeacons-rx2\u003c/artifactId\u003e\n    \u003cversion\u003e0.6.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nor through Gradle:\n\n```groovy\ndependencies {\n  compile 'com.github.pwittchen:reactivebeacons-rx2:0.6.0'\n}\n```\n\nTests\n-----\n\nTests are available in `library/src/test/java/` directory and can be executed without emulator or Android device from CLI with the following command:\n\n```\n./gradlew test\n```\n\nCode style\n----------\n\nCode style used in the project is called `SquareAndroid` from Java Code Styles repository by Square available at: https://github.com/square/java-code-styles. Currently, library doesn't have checkstyle verification attached. It can be done in the future.\n\nStatic code analysis\n--------------------\n\nStatic code analysis runs Checkstyle, FindBugs, PMD and Lint. It can be executed with command:\n\n ```\n ./gradlew check\n ```\n\nReports from analysis are generated in `library/build/reports/` directory.\n\nReferences\n----------\n\n### Useful resources\n\n- [Bluetooth Low Energy on Wikipedia](https://en.wikipedia.org/wiki/Bluetooth_low_energy)\n- [android-bluetooth-demo repository](https://github.com/Pixplicity/android-bluetooth-demo)\n- [Converting callbacks to RxJava Observables](https://getpocket.com/a/read/1052659262)\n- [Transmission power range and RSSI](https://support.kontakt.io/hc/en-gb/articles/201621521-Transmission-power-Range-and-RSSI)\n- [What are Broadcasting Power, RSSI and other characteristics of beacon's signal?](https://community.estimote.com/hc/en-us/articles/201636913-What-are-Broadcasting-Power-RSSI-and-other-characteristics-of-beacon-s-signal-)\n- [Estimating beacon proximity/distance based on RSSI - Bluetooth LE](http://stackoverflow.com/questions/22784516/estimating-beacon-proximity-distance-based-on-rssi-bluetooth-le)\n- [RSSI (Received Signal Strength Indication) on Wikipedia](https://en.wikipedia.org/wiki/Received_signal_strength_indication)\n- [Specification for Eddystone, an open beacon format from Google](https://github.com/google/eddystone)\n- [Bluetooth Low Energy on Android Developer Guide](http://developer.android.com/guide/topics/connectivity/bluetooth-le.html)\n\n### Producers of BLE beacons\n\n- [Estimote](http://estimote.com)\n- [Kontakt.io](http://kontakt.io)\n\n### Other APIs and libraries\n- Beacons/BLE\n  - [Android SDK by Estimote](https://github.com/Estimote/Android-SDK)\n  - [Android SDK by Kontakt.io](https://github.com/kontaktio/Android-SDK)\n  - [Android Beacon Library by AltBeacon](https://github.com/AltBeacon/android-beacon-library)\n  - [Bluetooth LE Library - Android](https://github.com/alt236/Bluetooth-LE-Library---Android)\n  - [EasyBle](https://github.com/Ficat/EasyBle)\n  - [RxAndroidBle](https://github.com/Polidea/RxAndroidBle)\n  - [RxCentralBle](https://github.com/uber/RxCentralBle)\n- Bluetooth\n  - [RxBluetooth](https://github.com/IvBaranov/RxBluetooth)\n  - [LMBluetoothSDK](https://github.com/whilu/LMBluetoothSdk)\n  - [Android-Bluetooth-Library](https://github.com/arissa34/Android-Bluetooth-Library)\n  - [AndroidSmoothBluetooth](https://github.com/palaima/AndroidSmoothBluetooth)\n  - [BlueDuff](https://github.com/Marchuck/BlueDuff)\n\nLicense\n-------\n\n    Copyright 2015 Piotr Wittchen\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n       http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n\n","funding_links":["https://github.com/sponsors/pwittchen","https://paypal.me/pwittchen"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwittchen%2Freactivebeacons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpwittchen%2Freactivebeacons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpwittchen%2Freactivebeacons/lists"}