1// Copyright (C) 2023 The Android Open Source Project 2// Licensed under the Apache License, Version 2.0 (the "License"); 3// you may not use this file except in compliance with the License. 4// You may obtain a copy of the License at 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 8// Unless required by applicable law or agreed to in writing, software 9// distributed under the License is distributed on an "AS IS" BASIS, 10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11// See the License for the specific language governing permissions and 12// limitations under the License. 13// 14// Proto Messages define the interface between Nearby nanoapp and its host. 15// 16// Host registers its interest in BLE event by configuring nanoapp with Filters. 17// The nanoapp keeps watching BLE events and notifies host once an event matches 18// a Filter. 19// 20// Each Filter is defined by its id (required) with optional fields of rssi, 21// uuid, MAC etc. The host should guarantee the uniqueness of ids. It is 22// convenient to assign id incrementally when adding a Filter such that its id 23// is the same as the index of the repeated field in Filters. 24// 25// The nanoapp compares each BLE event against the list of Filters, and notifies 26// host when the event matches a Filter. The Field's id will be sent back to 27// host in the FilterResult. 28// 29// It is possible for the nanoapp to return multiple ids when an event matches 30// multiple Filters. 31 32syntax = "proto2"; 33 34package nearby; 35 36option java_package = "com.google.location.lbs.contexthub"; 37option java_outer_classname = "NearbyNano"; 38 39// Certificate to verify BLE events from trusted devices. 40// When receiving an advertisement from a remote device, it will 41// be decrypted by authenticity_key and SHA hashed. The device 42// is verified as trusted if the hash result is equal to 43// metadata_encryption_key_tag. 44// See details in go/ns-certificates. 45message PublicateCertificate { 46 optional bytes authenticity_key = 1; 47 optional bytes metadata_encryption_key_tag = 2; 48} 49 50// Public credential returned in BleFilterResult. 51message PublicCredential { 52 optional bytes secret_id = 1; 53 optional bytes authenticity_key = 2; 54 optional bytes public_key = 3; 55 optional bytes encrypted_metadata = 4; 56 optional bytes encrypted_metadata_tag = 5; 57} 58 59message DataElement { 60 enum ElementType { 61 DE_NONE = 0; 62 DE_FAST_PAIR_ACCOUNT_KEY = 9; 63 DE_CONNECTION_STATUS = 10; 64 DE_BATTERY_STATUS = 11; 65 // Reserves 128 Test DEs. 66 DE_TEST_BEGIN = 2147483520; // INT_MAX - 127 67 DE_TEST_END = 2147483647; // INT_MAX 68 } 69 70 optional int32 key = 1; 71 optional bytes value = 2; 72 optional uint32 value_length = 3; 73} 74 75// A single filter used to filter BLE events. 76message BleFilter { 77 optional uint32 id = 1; // Required, unique id of this filter. 78 // Maximum delay to notify the client after an event occurs. 79 optional uint32 latency_ms = 2; 80 optional uint32 uuid = 3; 81 // MAC address of the advertising device. 82 optional bytes mac_address = 4; 83 optional bytes mac_mask = 5; 84 // Represents an action that scanners should take when they receive this 85 // packet. See go/nearby-presence-spec for details. 86 optional uint32 intent = 6; 87 // Notify the client if the advertising device is within the distance. 88 // For moving object, the distance is averaged over data sampled within 89 // the period of latency defined above. 90 optional float distance_m = 7; 91 // Used to verify the list of trusted devices. 92 repeated PublicateCertificate certificate = 8; 93 repeated DataElement data_element = 9; 94} 95 96message BleFilters { 97 repeated BleFilter filter = 1; 98} 99 100// FilterResult is returned to host when a BLE event matches a Filter. 101message BleFilterResult { 102 enum ResultType { 103 RESULT_NONE = 0; 104 RESULT_PRESENCE = 1; 105 RESULT_FAST_PAIR = 2; 106 } 107 108 optional uint32 id = 1; // id of the matched Filter. 109 optional int32 tx_power = 2; 110 optional int32 rssi = 3; 111 optional uint32 intent = 4; 112 optional bytes bluetooth_address = 5; 113 optional PublicCredential public_credential = 6; 114 repeated DataElement data_element = 7; 115 optional bytes ble_service_data = 8; 116 optional ResultType result_type = 9; 117 // Timestamp the advertisement was received, in nanoseconds, relative to 118 // Android SystemClock.elapsedRealtimeNanos(). 119 optional uint64 timestamp_ns = 10; 120} 121 122message BleFilterResults { 123 repeated BleFilterResult result = 1; 124} 125 126message BleConfig { 127 // True to start BLE scan. Otherwise, stop BLE scan. 128 optional bool start_scan = 1; 129 // True when screen is turned on. Otherwise, set to false when screen is 130 // turned off. 131 optional bool screen_on = 2; 132 // Fast Pair cache expires after this time period. 133 optional uint64 fast_pair_cache_expire_time_sec = 3; 134} 135