• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (C) 2022 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// Proto Messages define the interface between Nearby nanoapp and its host.
18//
19// Host registers its interest in BLE event by configuring nanoapp with Filters.
20// The nanoapp keeps watching BLE events and notifies host once an event matches
21// a Filter.
22//
23// Each Filter is defined by its id (required) with optional fields of rssi,
24// uuid, MAC etc. The host should guarantee the uniqueness of ids. It is
25// convenient to assign id incrementally when adding a Filter such that its id
26// is the same as the index of the repeated field in Filters.
27//
28// The nanoapp compares each BLE event against the list of Filters, and notifies
29// host when the event matches a Filter. The Field's id will be sent back to
30// host in the FilterResult.
31//
32// It is possible for the nanoapp to return multiple ids when an event matches
33// multiple Filters.
34
35syntax = "proto2";
36
37package service.proto;
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  // Data Elements for extended properties.
94  repeated DataElement data_element = 9;
95}
96
97message BleFilters {
98  repeated BleFilter filter = 1;
99}
100
101// FilterResult is returned to host when a BLE event matches a Filter.
102message BleFilterResult {
103  enum ResultType {
104    RESULT_NONE = 0;
105    RESULT_PRESENCE = 1;
106    RESULT_FAST_PAIR = 2;
107  }
108
109  optional uint32 id = 1;  // id of the matched Filter.
110  optional int32 tx_power = 2;
111  optional int32 rssi = 3;
112  optional uint32 intent = 4;
113  optional bytes bluetooth_address = 5;
114  optional PublicCredential public_credential = 6;
115  repeated DataElement data_element = 7;
116  optional bytes ble_service_data = 8;
117  optional ResultType result_type = 9;
118  // Timestamp when the device is discovered, in nanoseconds,
119  // relative to Android SystemClock.elapsedRealtimeNanos().
120  optional uint64 timestamp_ns = 10;
121}
122
123message BleFilterResults {
124  repeated BleFilterResult result = 1;
125}
126
127message BleConfig {
128  // True to start BLE scan. Otherwise, stop BLE scan.
129  optional bool start_scan = 1;
130  // True when screen is turned on. Otherwise, set to false when screen is
131  // turned off.
132  optional bool screen_on = 2;
133  // Fast Pair cache expires after this time period.
134  optional uint64 fast_pair_cache_expire_time_sec = 3;
135}
136