1 /* 2 * Copyright (C) 2021 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.android.server.nearby.common.ble.decode; 18 19 import androidx.annotation.Nullable; 20 21 import com.android.server.nearby.common.ble.BleRecord; 22 23 /** 24 * This class encapsulates the logic specific to each manufacturer for parsing formats for beacons, 25 * and presents a common API to access important ADV/EIR packet fields such as: 26 * 27 * <ul> 28 * <li><b>UUID (universally unique identifier)</b>, a value uniquely identifying a group of one or 29 * more beacons as belonging to an organization or of a certain type, up to 128 bits. 30 * <li><b>Instance</b> a 32-bit unsigned integer that can be used to group related beacons that 31 * have the same UUID. 32 * <li>the mathematics of <b>TX signal strength</b>, used for proximity calculations. 33 * </ul> 34 * 35 * ...and others. 36 * 37 * @see <a href="http://go/ble-glossary">BLE Glossary</a> 38 * @see <a href="https://www.bluetooth.org/docman/handlers/downloaddoc.ashx?doc_id=245130">Bluetooth 39 * Data Types Specification</a> 40 */ 41 public abstract class BeaconDecoder { 42 /** 43 * Returns true if the bleRecord corresponds to a beacon format that contains sufficient 44 * information to construct a BeaconId and contains the Tx power. 45 */ supportsBeaconIdAndTxPower(@uppressWarnings"unused") BleRecord bleRecord)46 public boolean supportsBeaconIdAndTxPower(@SuppressWarnings("unused") BleRecord bleRecord) { 47 return true; 48 } 49 50 /** 51 * Returns true if this decoder supports returning TxPower via {@link 52 * #getCalibratedBeaconTxPower(BleRecord)}. 53 */ supportsTxPower()54 public boolean supportsTxPower() { 55 return true; 56 } 57 58 /** 59 * Reads the calibrated transmitted power at 1 meter of the beacon in dBm. This value is 60 * contained 61 * in the scan record, as set by the transmitting beacon. Suitable for use in computing path 62 * loss, 63 * distance, and related derived values. 64 * 65 * @param bleRecord the parsed payload contained in the beacon packet 66 * @return integer value of the calibrated Tx power in dBm or null if the bleRecord doesn't 67 * contain sufficient information to calculate the Tx power. 68 */ 69 @Nullable getCalibratedBeaconTxPower(BleRecord bleRecord)70 public abstract Integer getCalibratedBeaconTxPower(BleRecord bleRecord); 71 72 /** 73 * Extract telemetry information from the beacon. Byte 0 of the returned telemetry block should 74 * encode the telemetry format. 75 * 76 * @return telemetry block for this beacon, or null if no telemetry data is found in the scan 77 * record. 78 */ 79 @Nullable getTelemetry(@uppressWarnings"unused") BleRecord bleRecord)80 public byte[] getTelemetry(@SuppressWarnings("unused") BleRecord bleRecord) { 81 return null; 82 } 83 84 /** Returns the appropriate type for this scan record. */ getBeaconIdType()85 public abstract int getBeaconIdType(); 86 87 /** 88 * Returns an array of bytes which uniquely identify this beacon, for beacons from any of the 89 * supported beacon types. This unique identifier is the indexing key for various internal 90 * services. Returns null if the bleRecord doesn't contain sufficient information to construct 91 * the 92 * ID. 93 */ 94 @Nullable getBeaconIdBytes(BleRecord bleRecord)95 public abstract byte[] getBeaconIdBytes(BleRecord bleRecord); 96 97 /** 98 * Returns the URL of the beacon. Returns null if the bleRecord doesn't contain a URL or 99 * contains 100 * a malformed URL. 101 */ 102 @Nullable getUrl(BleRecord bleRecord)103 public String getUrl(BleRecord bleRecord) { 104 return null; 105 } 106 } 107