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 // Placeholder assigned as the local name when gap::Adapter is initialized.
73 constexpr char kDefaultLocalName[] = "fuchsia";
74
75 // Constants used in BR/EDR Inquiry (Core Spec v5.0, Vol 2, Part C, Appendix A)
76 // Default cycles value for length of Inquiry. See T_gap(100).
77 // This is in 1.28s time slice units, and is 10.24 seconds.
78 constexpr uint8_t kInquiryLengthDefault = 0x08;
79
80 // The inquiry scan interval and window used by our stack. The unit for these
81 // values is controller timeslices (N) where Time in ms = N * 0.625ms
82 constexpr uint16_t kInquiryScanInterval = 0x01E0; // 300 ms
83 constexpr uint16_t kInquiryScanWindow = 0x0012; // 11.25 ms
84
85 // Constants used in Low Energy (see Core Spec v5.0, Vol 3, Part C, Appendix A).
86
87 constexpr pw::chrono::SystemClock::duration kLEGeneralDiscoveryScanMin =
88 std::chrono::milliseconds(10240);
89 constexpr pw::chrono::SystemClock::duration kLEGeneralDiscoveryScanMinCoded =
90 std::chrono::milliseconds(30720);
91 constexpr pw::chrono::SystemClock::duration kLEScanFastPeriod =
92 std::chrono::milliseconds(30720);
93
94 // The HCI spec defines the time conversion as follows: Time = N * 0.625 ms,
95 // where N is the value of the constant.
96 constexpr float kHciScanIntervalToMs = 0.625f;
HciScanIntervalToMs(uint16_t i)97 constexpr float HciScanIntervalToMs(uint16_t i) {
98 return static_cast<float>(i) * kHciScanIntervalToMs;
99 }
HciScanWindowToMs(uint16_t w)100 constexpr float HciScanWindowToMs(uint16_t w) { return HciScanIntervalToMs(w); }
101
102 // Recommended scan and advertising parameters that can be passed directly to
103 // the HCI commands. A constant that contans the word "Coded" is recommended
104 // when using the LE Coded PHY. Otherwise the constant is recommended when using
105 // the LE 1M PHY. See Core Spec v5.2, Vol. 3, Part C, Table A for ranges and
106 // descriptions.
107
108 // For user-initiated scanning
109 constexpr uint16_t kLEScanFastInterval = 0x0060; // 60 ms
110 constexpr uint16_t kLEScanFastIntervalCoded = 0x0120; // 180 ms
111 constexpr uint16_t kLEScanFastWindow = 0x0030; // 30 ms
112 constexpr uint16_t kLEScanFastWindowCoded = 0x90; // 90 ms
113
114 // For background scanning
115 constexpr uint16_t kLEScanSlowInterval1 = 0x0800; // 1.28 s
116 constexpr uint16_t kLEScanSlowInterval1Coded = 0x1800; // 3.84 s
117 constexpr uint16_t kLEScanSlowWindow1 = 0x0012; // 11.25 ms
118 constexpr uint16_t kLEScanSlowWindow1Coded = 0x0036; // 33.75 ms
119 constexpr uint16_t kLEScanSlowInterval2 = 0x1000; // 2.56 s
120 constexpr uint16_t kLEScanSlowInterval2Coded = 0x3000; // 7.68 s
121 constexpr uint16_t kLEScanSlowWindow2 = 0x0024; // 22.5 ms
122 constexpr uint16_t kLEScanSlowWindow2Coded = 0x006C; // 67.5 ms
123
124 // Advertising parameters
125 constexpr uint16_t kLEAdvertisingFastIntervalMin1 = 0x0030; // 30 ms
126 constexpr uint16_t kLEAdvertisingFastIntervalMax1 = 0x0060; // 60 ms
127 constexpr uint16_t kLEAdvertisingFastIntervalMin2 = 0x00A0; // 100 ms
128 constexpr uint16_t kLEAdvertisingFastIntervalMax2 = 0x00F0; // 150 ms
129 constexpr uint16_t kLEAdvertisingFastIntervalCodedMin1 = 0x0090; // 90 ms
130 constexpr uint16_t kLEAdvertisingFastIntervalCodedMax1 = 0x0120; // 180 ms
131 constexpr uint16_t kLEAdvertisingFastIntervalCodedMin2 = 0x01E0; // 300 ms
132 constexpr uint16_t kLEAdvertisingFastIntervalCodedMax2 = 0x02D0; // 450 ms
133
134 constexpr uint16_t kLEAdvertisingSlowIntervalMin = 0x0640; // 1 s
135 constexpr uint16_t kLEAdvertisingSlowIntervalMax = 0x0780; // 1.2 s
136 constexpr uint16_t kLEAdvertisingSlowIntervalCodedMin = 0x12C0; // 3 s
137 constexpr uint16_t kLEAdvertisingSlowIntervalCodedMax = 0x1680; // 3.6 s
138
139 // Timeout used for the LE Create Connection command.
140 constexpr pw::chrono::SystemClock::duration kLECreateConnectionTimeout =
141 std::chrono::seconds(20);
142 // Timeout used for the Br/Edr Create Connection command.
143 constexpr pw::chrono::SystemClock::duration kBrEdrCreateConnectionTimeout =
144 std::chrono::seconds(20);
145
146 // Timeout used for scanning during LE General CEP. Selected to be longer than
147 // the scan period.
148 constexpr pw::chrono::SystemClock::duration kLEGeneralCepScanTimeout =
149 std::chrono::seconds(20);
150
151 // Connection Interval Timing Parameters (see v5.0, Vol 3, Part C,
152 // Section 9.3.12 and Appendix A)
153 constexpr pw::chrono::SystemClock::duration kLEConnectionParameterTimeout =
154 std::chrono::seconds(30);
155 // Recommended minimum time upon connection establishment before the central
156 // starts a connection update procedure.
157 constexpr pw::chrono::SystemClock::duration kLEConnectionPauseCentral =
158 std::chrono::seconds(1);
159 // Recommended minimum time upon connection establishment before the peripheral
160 // starts a connection update procedure.
161 constexpr pw::chrono::SystemClock::duration kLEConnectionPausePeripheral =
162 std::chrono::seconds(5);
163
164 constexpr uint16_t kLEInitialConnIntervalMin = 0x0018; // 30 ms
165 constexpr uint16_t kLEInitialConnIntervalMax = 0x0028; // 50 ms
166 constexpr uint16_t kLEInitialConnIntervalCodedMin = 0x0048; // 90 ms
167 constexpr uint16_t kLEInitialConnIntervalCodedMax = 0x0078; // 150 ms
168
169 // Time interval that must expire before a temporary device is removed from the
170 // cache.
171 constexpr pw::chrono::SystemClock::duration kCacheTimeout =
172 std::chrono::seconds(60);
173
174 // Time interval between random address changes when privacy is enabled (see
175 // T_GAP(private_addr_int) in 5.0 Vol 3, Part C, Appendix A)
176 constexpr pw::chrono::SystemClock::duration kPrivateAddressTimeout =
177 std::chrono::minutes(15);
178
179 // Maximum duration for which a scannable advertisement will be stored and not
180 // reported to clients until a corresponding scan response is received.
181 //
182 // This number has been determined empirically but over a limited number of
183 // devices. According to Core Spec. v5.2 Vol 6, Part B, Section 4.4 and in
184 // practice, the typical gap between the two events from the same peer is
185 // <=10ms. However in practice it's possible to see gaps as high as 1.5 seconds
186 // or more.
187 constexpr pw::chrono::SystemClock::duration kLEScanResponseTimeout =
188 std::chrono::seconds(2);
189
190 // GATT types used in the GAP service.
191 constexpr UUID kGenericAccessService(uint16_t{0x1800});
192 constexpr UUID kDeviceNameCharacteristic(uint16_t{0x2A00});
193 constexpr UUID kAppearanceCharacteristic(uint16_t{0x2A01});
194 constexpr UUID kPeripheralPreferredConnectionParametersCharacteristic(uint16_t{
195 0x2A04});
196
197 // The Peripheral Preferred Connection Parameters Characteristic is optionally
198 // included in the GAP service of a peripheral (Core Spec v5.2, Vol 3, Part C,
199 // Sec 9.12.3). See hci_spec::LEConnectionParameters for a description of these
200 // fields.
201 struct PeripheralPreferredConnectionParametersCharacteristicValue {
202 uint16_t min_interval;
203 uint16_t max_interval;
204 uint16_t max_latency;
205 uint16_t supervision_timeout;
206 } __attribute__((packed));
207
208 } // namespace bt::gap
209