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 inline 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 inline 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 inline constexpr uint16_t kInquiryScanInterval = 0x01E0; // 300 ms
90 inline 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 inline constexpr pw::chrono::SystemClock::duration kLEGeneralDiscoveryScanMin =
95 std::chrono::milliseconds(10240);
96 inline constexpr pw::chrono::SystemClock::duration
97 kLEGeneralDiscoveryScanMinCoded = std::chrono::milliseconds(30720);
98 inline 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 inline 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 inline constexpr uint16_t kLEScanFastInterval = 0x0060; // 60 ms
117 inline constexpr uint16_t kLEScanFastIntervalCoded = 0x0120; // 180 ms
118 inline constexpr uint16_t kLEScanFastWindow = 0x0030; // 30 ms
119 inline constexpr uint16_t kLEScanFastWindowCoded = 0x90; // 90 ms
120
121 // For background scanning
122 inline constexpr uint16_t kLEScanSlowInterval1 = 0x0800; // 1.28 s
123 inline constexpr uint16_t kLEScanSlowInterval1Coded = 0x1800; // 3.84 s
124 inline constexpr uint16_t kLEScanSlowWindow1 = 0x0012; // 11.25 ms
125 inline constexpr uint16_t kLEScanSlowWindow1Coded = 0x0036; // 33.75 ms
126 inline constexpr uint16_t kLEScanSlowInterval2 = 0x1000; // 2.56 s
127 inline constexpr uint16_t kLEScanSlowInterval2Coded = 0x3000; // 7.68 s
128 inline constexpr uint16_t kLEScanSlowWindow2 = 0x0024; // 22.5 ms
129 inline constexpr uint16_t kLEScanSlowWindow2Coded = 0x006C; // 67.5 ms
130
131 // Advertising parameters
132 inline constexpr uint16_t kLEAdvertisingFastIntervalMin1 = 0x0030; // 30 ms
133 inline constexpr uint16_t kLEAdvertisingFastIntervalMax1 = 0x0060; // 60 ms
134 inline constexpr uint16_t kLEAdvertisingFastIntervalMin2 = 0x00A0; // 100 ms
135 inline constexpr uint16_t kLEAdvertisingFastIntervalMax2 = 0x00F0; // 150 ms
136 inline constexpr uint16_t kLEAdvertisingFastIntervalCodedMin1 =
137 0x0090; // 90 ms
138 inline constexpr uint16_t kLEAdvertisingFastIntervalCodedMax1 =
139 0x0120; // 180 ms
140 inline constexpr uint16_t kLEAdvertisingFastIntervalCodedMin2 =
141 0x01E0; // 300 ms
142 inline constexpr uint16_t kLEAdvertisingFastIntervalCodedMax2 =
143 0x02D0; // 450 ms
144
145 inline constexpr uint16_t kLEAdvertisingSlowIntervalMin = 0x0640; // 1 s
146 inline constexpr uint16_t kLEAdvertisingSlowIntervalMax = 0x0780; // 1.2 s
147 inline constexpr uint16_t kLEAdvertisingSlowIntervalCodedMin = 0x12C0; // 3 s
148 inline constexpr uint16_t kLEAdvertisingSlowIntervalCodedMax = 0x1680; // 3.6 s
149
150 // Timeout used for the LE Create Connection command.
151 inline constexpr pw::chrono::SystemClock::duration kLECreateConnectionTimeout =
152 std::chrono::seconds(20);
153 // Timeout used for the Br/Edr Create Connection command.
154 inline constexpr pw::chrono::SystemClock::duration
155 kBrEdrCreateConnectionTimeout = std::chrono::seconds(20);
156
157 // Timeout used for scanning during LE General CEP. Selected to be longer than
158 // the scan period.
159 inline constexpr pw::chrono::SystemClock::duration kLEGeneralCepScanTimeout =
160 std::chrono::seconds(20);
161
162 // Connection Interval Timing Parameters (see v5.0, Vol 3, Part C,
163 // Section 9.3.12 and Appendix A)
164 inline constexpr pw::chrono::SystemClock::duration
165 kLEConnectionParameterTimeout = std::chrono::seconds(30);
166 // Recommended minimum time upon connection establishment before the central
167 // starts a connection update procedure.
168 inline constexpr pw::chrono::SystemClock::duration kLEConnectionPauseCentral =
169 std::chrono::seconds(1);
170 // Recommended minimum time upon connection establishment before the peripheral
171 // starts a connection update procedure.
172 inline constexpr pw::chrono::SystemClock::duration
173 kLEConnectionPausePeripheral = std::chrono::seconds(5);
174
175 inline constexpr uint16_t kLEInitialConnIntervalMin = 0x0018; // 30 ms
176 inline constexpr uint16_t kLEInitialConnIntervalMax = 0x0028; // 50 ms
177 inline constexpr uint16_t kLEInitialConnIntervalCodedMin = 0x0048; // 90 ms
178 inline constexpr uint16_t kLEInitialConnIntervalCodedMax = 0x0078; // 150 ms
179
180 // Time interval that must expire before a temporary device is removed from the
181 // cache.
182 inline constexpr pw::chrono::SystemClock::duration kCacheTimeout =
183 std::chrono::seconds(60);
184
185 // Time interval between random address changes when privacy is enabled (see
186 // T_GAP(private_addr_int) in 5.0 Vol 3, Part C, Appendix A)
187 inline constexpr pw::chrono::SystemClock::duration kPrivateAddressTimeout =
188 std::chrono::minutes(15);
189
190 // Maximum duration for which a scannable advertisement will be stored and not
191 // reported to clients until a corresponding scan response is received.
192 //
193 // This number has been determined empirically but over a limited number of
194 // devices. According to Core Spec. v5.2 Vol 6, Part B, Section 4.4 and in
195 // practice, the typical gap between the two events from the same peer is
196 // <=10ms. However in practice it's possible to see gaps as high as 1.5 seconds
197 // or more.
198 inline constexpr pw::chrono::SystemClock::duration kLEScanResponseTimeout =
199 std::chrono::seconds(2);
200
201 // GATT types used in the GAP service.
202 inline constexpr UUID kGenericAccessService(uint16_t{0x1800});
203 inline constexpr UUID kDeviceNameCharacteristic(uint16_t{0x2A00});
204 inline constexpr UUID kAppearanceCharacteristic(uint16_t{0x2A01});
205 constexpr UUID kPeripheralPreferredConnectionParametersCharacteristic(uint16_t{
206 0x2A04});
207
208 // The Peripheral Preferred Connection Parameters Characteristic is optionally
209 // included in the GAP service of a peripheral (Core Spec v5.2, Vol 3, Part C,
210 // Sec 9.12.3). See hci_spec::LEConnectionParameters for a description of these
211 // fields.
212 struct PeripheralPreferredConnectionParametersCharacteristicValue {
213 uint16_t min_interval;
214 uint16_t max_interval;
215 uint16_t max_latency;
216 uint16_t supervision_timeout;
217 } __attribute__((packed));
218
219 } // namespace bt::gap
220