Beacon Manager

Note: To display only the features present on a particular device, select one or more filters from the SmartDocs bar below.

Language Note: Input fields accept ENGLISH ONLY.

EMDK For Android - 8.0

Overview

Beacon Manager (BeaconMgr) controls the signal emitted by the secondary Bluetooth Low Energy (BLE) radio of supported devices (see below) when powered off. To configure the primary BLE radio, please see the Android BLE APIs and Bluetooth LE classes.

The BLE beacon emitted from a device can be detected by an app running on another device and used for a variety of purposes. Beacon Manager facilitates administrative control over beacon contents and settings such as emission power and interval, which can help balance battery consumption with detectable range.

One solution that leverages BLE beaconing is Zebra Device Tracker, which can help locate misplaced devices by honing in on their BLE beacons. See Zebra Device Tracker for more information and a list of supported devices.

Supported Devices

Main Functionality

  • Turn On/Off Beaconing...
    • From secondary BLE radio when device is powered off
    • If device was in "Airplane mode" before being powered off
    • After battery is reinserterd in powered-off device
  • Set the beacon transmission power level
  • Set the transmission interval
  • Set beacon parameters for:
    • Beacon type
    • AltBeacon UUID
    • AltBeacon ID1, ID2
    • Custom beacon data
    • Manufacturer Byte value
    • Reference Received Signal Strength Indicator (RSSI) value

Note: In this document, the terms emission and transmission are used interchangeably.

Battery-based BLE Behavior

The secondary BLE radio of some devices is located in the battery. Such devices are subject to the following behaviors:

  • Beacon Manager configuration settings are stored in the device and its BLE-equipped battery, if present.
  • Settings stored in the device are replicated in the battery only when the device is powered on.
  • When BLE beaconing is enabled and the device is powered off, the battery emits a beacon using the preconfigured values as long as the battery remains in the device.
  • If beaconing is enabled and the battery is removed from a device, beaconing stops.
  • When a BLE-configured and enabled battery is placed in a device, beaconing resumes within about 30 seconds according to the following:
    • If the battery is reinserted into the device on which it was configured or that contains no Beacon Manager configuration values, the battery's last-saved values are used.
    • If the battery is placed in a powered-off device other than the one in which it was configured, the battery behaves according to its last preconfigured values until the device is powered on, at which time the battery receives and applies the BLE settings stored on the device.
  • A beaconing-enabled battery removed from a device consumes a small amount of power to periodically detect whether it has been inserted into a device and should resume beaconing.
  • If beaconing is disabled on a BLE-equipped battery, it draws no power when removed from the device.

Beaconing On/Off

Controls whether a beacon is transmitted by a device when the device is powered OFF. Off by default.

Parm Name: Beaconing

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change to device settings; any previously selected setting is retained.

MX: 10.2+

Android API: 29+

1 Turn ON Enables beacon transmission when device is powered off.

MX: 10.2+

Android API: 29+

2 Turn OFF Disables beacon transmission when device is powered off (default).

MX: 10.2+

Android API: 29+

Beaconing on Reinsertion On/Off

Controls whether beaconing by a BLE-enabled battery resumes when the battery is reinserted into any supported, powered-off device. On by default.

Parm Name: Beaconing

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change to device settings; any previously selected setting is retained.

MX: 10.5+

Android API: 26+

1 Turn ON Allows beaconing to resume when a battery is reinserted into a powered-off device (default).

MX: 10.5+

Android API: 26+

2 Turn OFF Prevents beaconing from resuming when the battery is reinserted into a powered-off device.

MX: 10.5+

Android API: 26+

Beaconing in Airplane Mode On/Off

Controls whether a beacon is transmitted by a device when powered OFF while in Airplane Mode. Disabled by default. Airplane Mode can be administered on the device using Settings Manager.

IMPORTANT:

When a device is placed in Airplane Mode, all device radios are switched off, including the device's beacon emitter. If a device is powered off while in Airplane Mode, the setting contained in the Beaconing in Airplane Mode parameter comes into play.

Device behavior for this mode is as follows:

  • If "Turn On" is selected, a beacon is emitted if the device is turned off while in Airplane Mode until the device battery runs out or the device is powered on again. This setting allows BLE radio transmissions from a powered-off device, which could be undesired in some situations.

  • If "Turn Off" is selected, no beacon is emitted when the device is turned off while in Airplane Mode.
    In this scenario, the beacon would be unavailable to help locate a powered-off device.

Parm Name: BeaconingInAirplaneMode

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change to device settings; any previously selected setting is retained.

MX: 10.2+

Android API: 29+

1 Turn ON Enables beacon transmission if device is powered off while in Airplane Mode. See Warning, above.

MX: 10.2+

Android API: 29+

2 Turn OFF Disables beacon transmission if device is powered off while in Airplane Mode. See Warning, above.

MX: 10.2+

Android API: 29+

Beacon Type

Controls the type of beacon transmitted for locating a lost device when it's powered off. AltBeacon, an open specification for determiniing device proximity, is enabled by default. If "Custom" is selected (option 3), specify custom proximity protocols using the CustomBeaconData parameter.

Parm Name: BeaconType

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no change device settings; any previously selected setting is retained.

MX: 10.2+

Android API: 29+

2 AltBeacon Enables the AltBeacon open device beacon specication (default).

MX: 10.2+

Android API: 29+

3 Custom Enables the custom custom beacon specification as entered in the CustomBeaconData parameter.

MX: 10.2+

Android API: 29+

Transmit Power Level

Used to enter the power level (in decibels per milliwatt, or dBm) for beacon transmission. Select a value that balances power consumption and transmission power to optimize device detection range. Option 1 (1 dBm) is selected by default.

Parm Name: TxPowerLevel

Option Name Description Note Requires
1 High (1 dBm) Sets the highest beacon transmission power level for maximum detection range. Uses the most device power (default).

MX: 10.2+

Android API: 29+

2 Medium (-7 dBm) Sets a moderate beacon transmission power level, conserving power and reducing detection range slightly.

MX: 10.2+

Android API: 29+

3 Low Power (-15 dBm) Sets a low beacon transmission power level, conserving power and reducing detection range.

MX: 10.2+

Android API: 29+

4 Ultra Low Power (-21 dBm) Sets a very low beacon transmission power level, conserving power while reducing detection range to a minimum.

MX: 10.2+

Android API: 29+

5 Custom (-127 dBm to 1 dBm) Allows a custom value to be entered using the CustomTxPowerLevel parameter.

MX: 10.2+

Android API: 29+

Custom Transmit Power Level

Used to enter a power level (in decibels per milliwatt, or dBm) for beacon transmission.

Input value rules:

  • An integer from -127–1

Shown if: Transmit Power Level is "Custom"

Parm Name: CustomTxPowerLevel

Requires:

  • MX: 10.2+
  • Android API: 29+

Transmit Interval

Used to enter the amount of time (in milliseconds) between each beacon transmission. Select a value that balances power consumption and transmission frequency to optimize device location. Option 1 (100 ms) is selected by default.

Parm Name: TxInterval

Option Name Description Note Requires
0 Do not change This value (or the absence of this parm from the XML) causes no changes device settings; any previously selected setting is retained.

MX: 10.2+

Android API: 29+

1 Low Latency (100 ms) Causes a beacon to be transmitted approx. 10 times per second. This option uses the most device power.

MX: 10.2+

Android API: 29+

2 Balanced (250 ms) Causes a beacon to be transmitted approx. four times per second.

MX: 10.2+

Android API: 29+

3 Low Power (1000 ms) Causes a beacon to be transmitted once per second.

MX: 10.2+

Android API: 29+

4 Custom (100 ms to 10240 ms) Allows a custom value to be entered using the CustomTxInterval parameter.

MX: 10.2+

Android API: 29+

Custom Transmit Interval

Used to enter the amount of time (in milliseconds) between each beacon transmission. Allowable range is 100 ms (10 transmissions per second) and 10240 (one transmission every 10 seconds).

Input value rules:

  • An integer from 100–10240

Shown if: Transmit Interval is "Custom"

Parm Name: CustomTxInterval

Requires:

  • MX: 10.2+
  • Android API: 29+

Explicit Beacon UUID (checkbox)

Controls whether an explicit beacon UUID will be entered. If unchecked, a self-generated, device-specific UUID is used (default).

Parm Name: ExplicitBeaconUUID

Option Name Description Note Requires
0 (unchecked) Disables entry of an explicit beacon UUID.

MX: 10.2+

Android API: 29+

1 (checked) Enables entry of an explicit beacon UUID.

MX: 10.2+

Android API: 29+

AltBeacon UUID

Used to enter a 32-character AltBeacon UUID in hexadecimal format.

The 20-byte AltBeacon data format contains 40 hexadecimal characters of information divided into the UUID (32 hexadecimal characters) plus ID1 (4 hexadecimal characters) and ID2 (4 hexadecimal characters).

Input value rules:

  • String of exactly 32 hexadecimal characters

Shown if: Beacon Type is "AltBeacon" and Explicit Beacon UUID is "checked"

Parm Name: AltBeaconUUID

Requires:

  • MX: 10.2+
  • Android API: 29+

AltBeacon ID1

Used to enter the ID1 portion of the AltBeacon UUID. Default value of EBEB is used if this parameter is missing or left blank.

The 20-byte AltBeacon data format contains 40 hexadecimal characters of information divided into the UUID (32 hexadecimal characters) plus ID1 (4 hexadecimal characters) and ID2 (4 hexadecimal characters).

Input value rules:

  • String of exactly four (4) hexadecimal characters

Shown if: Beacon Type is "AltBeacon"

Parm Name: ID1

Requires:

  • MX: 10.2+
  • Android API: 29+

AltBeacon ID2

Used to enter the ID2 portion of the AltBeacon UUID. Default value of ECDD is used if this parameter is missing or left blank.

The 20-byte AltBeacon data format contains 40 hexadecimal characters of information divided into the UUID (32 hexadecimal characters) plus ID1 (4 hexadecimal characters) and ID2 (4 hexadecimal characters).

Input value rules:

  • String of exactly four (4) hexadecimal characters

Shown if: Beacon Type is "AltBeacon"

Parm Name: ID2

Requires:

  • MX: 10.2+
  • Android API: 29+

Custom Beacon Data

Used to enter custom or proprietary UUID, URL and other data for beacon transmission. Accepts as many as 56 hexadecimal characters; must follow Bluetooth SIG Advertising format.

More Information:

Input value rules:

  • String from 1–56 numerals in Bluetooth SIG Advertising format

Parm Name: CustomBeaconData

Requires:

  • MX: 10.2+
  • Android API: 29+

Manufacturer Byte

Used to enter the Manufacturer Byte or a custom value in the AltBeacon advertising packet. Default value of 00 is used if this parameter is missing or left blank.

Input value rules:

  • String of exactly two (2) hexadecimal characters

Shown if: Beacon Type is "AltBeacon"

Parm Name: MfgByte

Requires:

  • MX: 10.5+
  • Android API: 29+

Reference RSSI

Used to enter the Reference Received Signal Strength Indicator (RSSI) value, which can be helpful for extrapolating the relative distance to a device beacon based on its signal strength. If this parameter is missing or left blank, a calculated value is inserted that is the RSSI value received at one (1) meter distance from device emitting the beacon at its selected TX Power Level. NOTE: Calculated value varies by device.

Input value rules:

  • String of exactly two (2) hexadecimal characters

Shown if: Beacon Type is "AltBeacon"

Parm Name: RefRSSI

Requires:

  • MX: 10.5+
  • Android API: 29+

Examples

Configure beaconing

Turn beaconing on:


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <parm name="Beaconing" value="1"/>
    </characteristic>
</wap-provisioningdoc>


Turn beaconing on in Airplane Mode:


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <parm name=" BeaconingInAirplaneMode " value="1"/>
    </characteristic>
</wap-provisioningdoc>


Configure default AltBeacon data:


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="BeaconType" value="2"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure explicit beacon data using AltBeacon:


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="BeaconType" value="2"/>
            <parm name="ExplicitBeaconUUID" value="1"/>
            <parm name="AltBeaconUUID" value="123456789abcdef123456789abcdef12"/>
            <parm name="ID1" value="AAAA"/>
            <parm name="ID2" value="BBBB"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure explicit beacon data using custom beacon:


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="BeaconType" value="3"/>
            <parm name="CustomBeaconData" value="1affF101beacd69cad1c04fca07052bcc0896b0f7764aaaabbbbc5"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure transmit (tx) interval (low latency):


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="TxInterval" value="1"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure transmit (tx) interval (custom value of 2000 ms):


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="TxInterval" value="4"/>
            <parm name="CustomTxInterval" value="2000"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure transmit (tx) power level (high):


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="TxPowerLevel" value="1"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>


Configure transmit (tx) power level (custom):


<wap-provisioningdoc>
    <characteristic type="BeaconMgr" version="10.2" >
        <characteristic type="BeaconParameters">
            <parm name="TxPowerLevel" value="5"/>
            <parm name="CustomTxPowerLevel" value="-24"/>
        </characteristic>
    </characteristic>
</wap-provisioningdoc>