Overview

What is libbeacon?

libbeacon is an Android Beacon Library for detecting an expected fleet of Bluetooth Low Energy beacons.

In a basic usage, it can be under control of an active Activity for a live session, with results displayed on the screen.

In a more advanced usage, which is what the library is designed for, it allows an application to detect Bluetooth beacons in the neighborhood and take actions accordingly. As the work is done in a service, the user isn't involved for anything.

Through listeners, you implement your actions for some events, such as:

  • Entering/exiting an area globally covered by a set of cooperative beacons (called a Region in the iBeacon world or a Namespace in the Eddystone world).
  • The discover and the lost of a beacon, with the option of slow pace reminder in between.
  • Each and every frames sent by the beacons.
  • Changes in the collection of known devices in an area.

Use cases

Asset/Tool tracking IT hardware tracking Medical device tracking

Locate your high value equipments, and know if they are available in storage areas or currently used on some site. It will also help to plan the maintenance operations more efficiently. When parts can be provided by many contractors on a site, detecting exchanges, losses or thefts is easier.

Routing

Follow the route of a tracker, check the conformity with an expected routing plan. Detect in which nodes the tracker suffers delays.

Inventory

Knowing how much time an equipment stays unused in the storage areas and the usage rates helps to optimize the annual investments and, if applicable, the allocation between multiple areas.

What does it support?

Standard protocols

The frame processing supports these de facto industrial standards:

  • iBeacon (from Apple)
  • Eddystone (from Google)

Specific protocols

Other frame formats and/or data specific to manufacturers can be supported through the addition of plugins. For example, it's usual for manufacturers to provide an indicator for the battery level, but sometimes in a non standard way.

The library is provided with a basic set of plugins for the tags of these manufacturers:

  • ELA Innovation (France)
  • Invirtus (France)
  • Accent Systems (Spain)
  • Teltonika Telematics (Lithuania)
  • Minew Technologies Co. (China)
  • KKM Company Limited (China)
  • Meeblue / Ankhmaway (China)
  • Moko (China)

The integration of more plugins can be considered, on request.

Read more...

Android versions

The library fully supports the requirements related to running a foreground service, introduced in Android 14 (API 34).

The minimal SDK version is 24.

How does it look like?

libbeacon is packaged as an aar file and needs an API Key (free for evaluation).

Integration Guidelines

Step 1: Get the library file

Go to the Download section and choose preferably the latest .aar file.

Place the file under the libs/ directory of the application of your project.

Step 2: Get an API Key

Go to the License section and request a Key.

Copy-paste this Key in your AndroidManifest.xml file as the YOUR_API_KEY below:

<manifest ... >
  <application ... >
    <activity ... > </activity>
    <meta-data android:name="fr.maxcom.libbeacon.apiKey" android:value="YOUR_API_KEY" />
  </application>
</manifest>

Step 3: Set the possible necessary permissions and features

Note: Required for its internal implementation, the library already declares these permissions in its AndroidManifest.xml, so they will be merged in the final app packaging:

"android.permission.BLUETOOTH_CONNECT"
"android.permission.BLUETOOTH_SCAN"
"android.permission.FOREGROUND_SERVICE"
"android.permission.FOREGROUND_SERVICE_LOCATION"

♦ If you want your application to run on older devices, lower or equal to Android 11 (R - API level 30) some legacy permissions are needed.

Set these permissions in the AndroidManifest.xml file:

<manifest ... >
  <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions -->
  <!-- "Request legacy Bluetooth permissions on older devices." -->
  <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
  <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
</manifest>

♦ On Android 11 or lower, ACCESS_FINE_LOCATION is necessary for a Bluetooth scan. On Android 12 or higher, the option of an assertion about "never derives physical location" can not be used because it is too much restrictive as it filters Eddystone and iBeacon payloads.

♦ On Android 12 (API level 31) or higher, if you need access to FINE location, you must request both ACCESS_FINE_LOCATION and ACCESS_COARSE_LOCATION.

Set these permissions in the AndroidManifest.xml file:

<manifest ... >
  <!-- https://developer.android.com/develop/connectivity/bluetooth/bt-permissions -->
  <!-- "Needed only if your app uses Bluetooth scan results to derive physical location." -->
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <!-- https://developer.android.com/develop/sensors-and-location/location/permissions#approximate-request -->
  <!-- "On Android 12 (API level 31) or higher, users can request that your app retrieve only approximate ..." -->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

♦ Optionally you may declare a required feature, intended to the Play Store filtering:

<manifest ... >
  <uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />
</manifest>

Step 4: Allow the use of the library

Before any call to the library can be made, the application code must make an initial call to Licensing.allow(Context). Typically this takes place in the onCreate() method of the activity declared as the application entry point:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    Licensing.allow(applicationContext)
    //...
}

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    Licensing.allow(getApplicationContext());
    //...
}