1 // Copyright 2023 The Pigweed Authors
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not
4 // use this file except in compliance with the License. You may obtain a copy of
5 // the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
12 // License for the specific language governing permissions and limitations under
13 // the License.
14
15 #pragma once
16 #include <pw_bluetooth/hci_events.emb.h>
17 #include <pw_chrono/system_clock.h>
18
19 #include <cstdint>
20
21 #include "pw_bluetooth_sapphire/internal/host/common/identifier.h"
22 #include "pw_bluetooth_sapphire/internal/host/common/uuid.h"
23
24 // This file contains constants and numbers that are part of the Generic Access
25 // Profile specification.
26
27 namespace bt::gap {
28
29 // Bluetooth technologies that a device can support.
30 enum class TechnologyType {
31 kLowEnergy,
32 kClassic,
33 kDualMode,
34 };
35 const char* TechnologyTypeToString(TechnologyType type);
36
37 enum class Mode {
38 // Use the legacy HCI command set.
39 kLegacy,
40
41 // Use the extended HCI command set introduced in version 5.0
42 kExtended,
43 };
44
45 // Enum for the supported values of the BR/EDR Security Mode as defined in
46 // Core Spec v5.4, Vol 3, Part C, 4.2.2.
47 enum class BrEdrSecurityMode {
48 // Mode 4 entails possibly encrypted, possibly authenticated communication.
49 Mode4,
50 // Secure Connections Only mode enforces that all encrypted transmissions use
51 // 128-bit,
52 // SC-generated and authenticated encryption keys.
53 SecureConnectionsOnly,
54 };
55 const char* BrEdrSecurityModeToString(BrEdrSecurityMode mode);
56
57 // Enum for the supported values of the LE Security Mode as defined in spec v5.2
58 // Vol 3 Part C 10.2.
59 enum class LESecurityMode {
60 // Mode 1 entails possibly encrypted, possibly authenticated communication.
61 Mode1,
62 // Secure Connections Only mode enforces that all encrypted transmissions use
63 // 128-bit,
64 // SC-generated and authenticated encryption keys.
65 SecureConnectionsOnly,
66 };
67 const char* LeSecurityModeToString(LESecurityMode mode);
68
69 const char* EncryptionStatusToString(
70 pw::bluetooth::emboss::EncryptionStatus status);
71
72 enum class PairingStateType : uint8_t {
73 kSecureSimplePairing,
74 kLegacyPairing,
75 kUnknown,
76 };
77 const char* PairingStateTypeToString(PairingStateType type);
78
79 // Placeholder assigned as the local name when gap::Adapter is initialized.
80 constexpr char kDefaultLocalName[] = "fuchsia";
81
82 // Constants used in BR/EDR Inquiry (Core Spec v5.0, Vol 2, Part C, Appendix A)
83 // Default cycles value for length of Inquiry. See T_gap(100).
84 // This is in 1.28s time slice units, and is 10.24 seconds.
85 constexpr uint8_t kInquiryLengthDefault = 0x08;
86
87 // The inquiry scan interval and window used by our stack. The unit for these
88 // values is controller timeslices (N) where Time in ms = N * 0.625ms
89 constexpr uint16_t kInquiryScanInterval = 0x01E0; // 300 ms
90 constexpr uint16_t kInquiryScanWindow = 0x0012; // 11.25 ms
91
92 // Constants used in Low Energy (see Core Spec v5.0, Vol 3, Part C, Appendix A).
93
94 constexpr pw::chrono::SystemClock::duration kLEGeneralDiscoveryScanMin =
95 std::chrono::milliseconds(10240);
96 constexpr pw::chrono::SystemClock::duration kLEGeneralDiscoveryScanMinCoded =
97 std::chrono::milliseconds(30720);
98 constexpr pw::chrono::SystemClock::duration kLEScanFastPeriod =
99 std::chrono::milliseconds(30720);
100
101 // The HCI spec defines the time conversion as follows: Time = N * 0.625 ms,
102 // where N is the value of the constant.
103 constexpr float kHciScanIntervalToMs = 0.625f;
HciScanIntervalToMs(uint16_t i)104 constexpr float HciScanIntervalToMs(uint16_t i) {
105 return static_cast<float>(i) * kHciScanIntervalToMs;
106 }
HciScanWindowToMs(uint16_t w)107 constexpr float HciScanWindowToMs(uint16_t w) { return HciScanIntervalToMs(w); }
108
109 // Recommended scan and advertising parameters that can be passed directly to
110 // the HCI commands. A constant that contans the word "Coded" is recommended
111 // when using the LE Coded PHY. Otherwise the constant is recommended when using
112 // the LE 1M PHY. See Core Spec v5.2, Vol. 3, Part C, Table A for ranges and
113 // descriptions.
114
115 // For user-initiated scanning
116 constexpr uint16_t kLEScanFastInterval = 0x0060; // 60 ms
117 constexpr uint16_t kLEScanFastIntervalCoded = 0x0120; // 180 ms
118 constexpr uint16_t kLEScanFastWindow = 0x0030; // 30 ms
119 constexpr uint16_t kLEScanFastWindowCoded = 0x90; // 90 ms
120
121 // For background scanning
122 constexpr uint16_t kLEScanSlowInterval1 = 0x0800; // 1.28 s
123 constexpr uint16_t kLEScanSlowInterval1Coded = 0x1800; // 3.84 s
124 constexpr uint16_t kLEScanSlowWindow1 = 0x0012; // 11.25 ms
125 constexpr uint16_t kLEScanSlowWindow1Coded = 0x0036; // 33.75 ms
126 constexpr uint16_t kLEScanSlowInterval2 = 0x1000; // 2.56 s
127 constexpr uint16_t kLEScanSlowInterval2Coded = 0x3000; // 7.68 s
128 constexpr uint16_t kLEScanSlowWindow2 = 0x0024; // 22.5 ms
129 constexpr uint16_t kLEScanSlowWindow2Coded = 0x006C; // 67.5 ms
130
131 // Advertising parameters
132 constexpr uint16_t kLEAdvertisingFastIntervalMin1 = 0x0030; // 30 ms
133 constexpr uint16_t kLEAdvertisingFastIntervalMax1 = 0x0060; // 60 ms
134 constexpr uint16_t kLEAdvertisingFastIntervalMin2 = 0x00A0; // 100 ms
135 constexpr uint16_t kLEAdvertisingFastIntervalMax2 = 0x00F0; // 150 ms
136 constexpr uint16_t kLEAdvertisingFastIntervalCodedMin1 = 0x0090; // 90 ms
137 constexpr uint16_t kLEAdvertisingFastIntervalCodedMax1 = 0x0120; // 180 ms
138 constexpr uint16_t kLEAdvertisingFastIntervalCodedMin2 = 0x01E0; // 300 ms
139 constexpr uint16_t kLEAdvertisingFastIntervalCodedMax2 = 0x02D0; // 450 ms
140
141 constexpr uint16_t kLEAdvertisingSlowIntervalMin = 0x0640; // 1 s
142 constexpr uint16_t kLEAdvertisingSlowIntervalMax = 0x0780; // 1.2 s
143 constexpr uint16_t kLEAdvertisingSlowIntervalCodedMin = 0x12C0; // 3 s
144 constexpr uint16_t kLEAdvertisingSlowIntervalCodedMax = 0x1680; // 3.6 s
145
146 // Timeout used for the LE Create Connection command.
147 constexpr pw::chrono::SystemClock::duration kLECreateConnectionTimeout =
148 std::chrono::seconds(20);
149 // Timeout used for the Br/Edr Create Connection command.
150 constexpr pw::chrono::SystemClock::duration kBrEdrCreateConnectionTimeout =
151 std::chrono::seconds(20);
152
153 // Timeout used for scanning during LE General CEP. Selected to be longer than
154 // the scan period.
155 constexpr pw::chrono::SystemClock::duration kLEGeneralCepScanTimeout =
156 std::chrono::seconds(20);
157
158 // Connection Interval Timing Parameters (see v5.0, Vol 3, Part C,
159 // Section 9.3.12 and Appendix A)
160 constexpr pw::chrono::SystemClock::duration kLEConnectionParameterTimeout =
161 std::chrono::seconds(30);
162 // Recommended minimum time upon connection establishment before the central
163 // starts a connection update procedure.
164 constexpr pw::chrono::SystemClock::duration kLEConnectionPauseCentral =
165 std::chrono::seconds(1);
166 // Recommended minimum time upon connection establishment before the peripheral
167 // starts a connection update procedure.
168 constexpr pw::chrono::SystemClock::duration kLEConnectionPausePeripheral =
169 std::chrono::seconds(5);
170
171 constexpr uint16_t kLEInitialConnIntervalMin = 0x0018; // 30 ms
172 constexpr uint16_t kLEInitialConnIntervalMax = 0x0028; // 50 ms
173 constexpr uint16_t kLEInitialConnIntervalCodedMin = 0x0048; // 90 ms
174 constexpr uint16_t kLEInitialConnIntervalCodedMax = 0x0078; // 150 ms
175
176 // Time interval that must expire before a temporary device is removed from the
177 // cache.
178 constexpr pw::chrono::SystemClock::duration kCacheTimeout =
179 std::chrono::seconds(60);
180
181 // Time interval between random address changes when privacy is enabled (see
182 // T_GAP(private_addr_int) in 5.0 Vol 3, Part C, Appendix A)
183 constexpr pw::chrono::SystemClock::duration kPrivateAddressTimeout =
184 std::chrono::minutes(15);
185
186 // Maximum duration for which a scannable advertisement will be stored and not
187 // reported to clients until a corresponding scan response is received.
188 //
189 // This number has been determined empirically but over a limited number of
190 // devices. According to Core Spec. v5.2 Vol 6, Part B, Section 4.4 and in
191 // practice, the typical gap between the two events from the same peer is
192 // <=10ms. However in practice it's possible to see gaps as high as 1.5 seconds
193 // or more.
194 constexpr pw::chrono::SystemClock::duration kLEScanResponseTimeout =
195 std::chrono::seconds(2);
196
197 // GATT types used in the GAP service.
198 constexpr UUID kGenericAccessService(uint16_t{0x1800});
199 constexpr UUID kDeviceNameCharacteristic(uint16_t{0x2A00});
200 constexpr UUID kAppearanceCharacteristic(uint16_t{0x2A01});
201 constexpr UUID kPeripheralPreferredConnectionParametersCharacteristic(uint16_t{
202 0x2A04});
203
204 // The Peripheral Preferred Connection Parameters Characteristic is optionally
205 // included in the GAP service of a peripheral (Core Spec v5.2, Vol 3, Part C,
206 // Sec 9.12.3). See hci_spec::LEConnectionParameters for a description of these
207 // fields.
208 struct PeripheralPreferredConnectionParametersCharacteristicValue {
209 uint16_t min_interval;
210 uint16_t max_interval;
211 uint16_t max_latency;
212 uint16_t supervision_timeout;
213 } __attribute__((packed));
214
215 } // namespace bt::gap
216