1 /*
2 * Copyright (c) 2018 Texas Instruments, Incorporated
3 * Copyright (c) 2023 Nordic Semiconductor ASA
4 *
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8 /**
9 * @file
10 * @brief IEEE 802.11 protocol and general Wi-Fi definitions.
11 */
12
13 /**
14 * @defgroup wifi_mgmt Wi-Fi Management
15 * @brief Wi-Fi Management API.
16 * @ingroup networking
17 * @{
18 */
19
20 #ifndef ZEPHYR_INCLUDE_NET_WIFI_H_
21 #define ZEPHYR_INCLUDE_NET_WIFI_H_
22
23 #include <zephyr/sys/util.h> /* for ARRAY_SIZE */
24
25 #define WIFI_COUNTRY_CODE_LEN 2
26
27 #define WIFI_LISTEN_INTERVAL_MIN 0
28 #define WIFI_LISTEN_INTERVAL_MAX 65535
29
30 #ifdef __cplusplus
31 extern "C" {
32 #endif
33
34 /** IEEE 802.11 security types. */
35 enum wifi_security_type {
36 /** No security. */
37 WIFI_SECURITY_TYPE_NONE = 0,
38 /** WPA2-PSK security. */
39 WIFI_SECURITY_TYPE_PSK,
40 /** WPA2-PSK-SHA256 security. */
41 WIFI_SECURITY_TYPE_PSK_SHA256,
42 /** WPA3-SAE security. */
43 WIFI_SECURITY_TYPE_SAE,
44 /** GB 15629.11-2003 WAPI security. */
45 WIFI_SECURITY_TYPE_WAPI,
46 /** EAP security - Enterprise. */
47 WIFI_SECURITY_TYPE_EAP,
48 /** WEP security. */
49 WIFI_SECURITY_TYPE_WEP,
50 /** WPA-PSK security. */
51 WIFI_SECURITY_TYPE_WPA_PSK,
52
53 __WIFI_SECURITY_TYPE_AFTER_LAST,
54 WIFI_SECURITY_TYPE_MAX = __WIFI_SECURITY_TYPE_AFTER_LAST - 1,
55 WIFI_SECURITY_TYPE_UNKNOWN
56 };
57
58 /** Helper function to get user-friendly security type name. */
59 const char *wifi_security_txt(enum wifi_security_type security);
60
61 /** IEEE 802.11w - Management frame protection. */
62 enum wifi_mfp_options {
63 /** MFP disabled. */
64 WIFI_MFP_DISABLE = 0,
65 /** MFP optional. */
66 WIFI_MFP_OPTIONAL,
67 /** MFP required. */
68 WIFI_MFP_REQUIRED,
69
70 __WIFI_MFP_AFTER_LAST,
71 WIFI_MFP_MAX = __WIFI_MFP_AFTER_LAST - 1,
72 WIFI_MFP_UNKNOWN
73 };
74
75 /** Helper function to get user-friendly MFP name.*/
76 const char *wifi_mfp_txt(enum wifi_mfp_options mfp);
77
78 /**
79 * @brief IEEE 802.11 operational frequency bands (not exhaustive).
80 */
81 enum wifi_frequency_bands {
82 /** 2.4 GHz band. */
83 WIFI_FREQ_BAND_2_4_GHZ = 0,
84 /** 5 GHz band. */
85 WIFI_FREQ_BAND_5_GHZ,
86 /** 6 GHz band (Wi-Fi 6E, also extends to 7GHz). */
87 WIFI_FREQ_BAND_6_GHZ,
88
89 /** Number of frequency bands available. */
90 __WIFI_FREQ_BAND_AFTER_LAST,
91 /** Highest frequency band available. */
92 WIFI_FREQ_BAND_MAX = __WIFI_FREQ_BAND_AFTER_LAST - 1,
93 /** Invalid frequency band */
94 WIFI_FREQ_BAND_UNKNOWN
95 };
96
97 /** Helper function to get user-friendly frequency band name. */
98 const char *wifi_band_txt(enum wifi_frequency_bands band);
99
100 #define WIFI_SSID_MAX_LEN 32
101 #define WIFI_PSK_MIN_LEN 8
102 #define WIFI_PSK_MAX_LEN 64
103 #define WIFI_SAE_PSWD_MAX_LEN 128
104 #define WIFI_MAC_ADDR_LEN 6
105
106 #define WIFI_CHANNEL_MIN 1
107 #define WIFI_CHANNEL_MAX 233
108 #define WIFI_CHANNEL_ANY 255
109
110 /** Wi-Fi interface states.
111 *
112 * Based on https://w1.fi/wpa_supplicant/devel/defs_8h.html#a4aeb27c1e4abd046df3064ea9756f0bc
113 */
114 enum wifi_iface_state {
115 /** Interface is disconnected. */
116 WIFI_STATE_DISCONNECTED = 0,
117 /** Interface is disabled (administratively). */
118 WIFI_STATE_INTERFACE_DISABLED,
119 /** No enabled networks in the configuration. */
120 WIFI_STATE_INACTIVE,
121 /** Interface is scanning for networks. */
122 WIFI_STATE_SCANNING,
123 /** Authentication with a network is in progress. */
124 WIFI_STATE_AUTHENTICATING,
125 /** Association with a network is in progress. */
126 WIFI_STATE_ASSOCIATING,
127 /** Association with a network completed. */
128 WIFI_STATE_ASSOCIATED,
129 /** 4-way handshake with a network is in progress. */
130 WIFI_STATE_4WAY_HANDSHAKE,
131 /** Group Key exchange with a network is in progress. */
132 WIFI_STATE_GROUP_HANDSHAKE,
133 /** All authentication completed, ready to pass data. */
134 WIFI_STATE_COMPLETED,
135
136 __WIFI_STATE_AFTER_LAST,
137 WIFI_STATE_MAX = __WIFI_STATE_AFTER_LAST - 1,
138 WIFI_STATE_UNKNOWN
139 };
140
141 /** Helper function to get user-friendly interface state name. */
142 const char *wifi_state_txt(enum wifi_iface_state state);
143
144 /** Wi-Fi interface modes.
145 *
146 * Based on https://w1.fi/wpa_supplicant/devel/defs_8h.html#a4aeb27c1e4abd046df3064ea9756f0bc
147 */
148 enum wifi_iface_mode {
149 /** Infrastructure station mode. */
150 WIFI_MODE_INFRA = 0,
151 /** IBSS (ad-hoc) station mode. */
152 WIFI_MODE_IBSS = 1,
153 /** AP mode. */
154 WIFI_MODE_AP = 2,
155 /** P2P group owner mode. */
156 WIFI_MODE_P2P_GO = 3,
157 /** P2P group formation mode. */
158 WIFI_MODE_P2P_GROUP_FORMATION = 4,
159 /** 802.11s Mesh mode. */
160 WIFI_MODE_MESH = 5,
161
162 __WIFI_MODE_AFTER_LAST,
163 WIFI_MODE_MAX = __WIFI_MODE_AFTER_LAST - 1,
164 WIFI_MODE_UNKNOWN
165 };
166
167 /** Helper function to get user-friendly interface mode name. */
168 const char *wifi_mode_txt(enum wifi_iface_mode mode);
169
170 /** Wi-Fi link operating modes
171 *
172 * As per https://en.wikipedia.org/wiki/Wi-Fi#Versions_and_generations.
173 */
174 enum wifi_link_mode {
175 /** 802.11 (legacy). */
176 WIFI_0 = 0,
177 /** 802.11b. */
178 WIFI_1,
179 /** 802.11a. */
180 WIFI_2,
181 /** 802.11g. */
182 WIFI_3,
183 /** 802.11n. */
184 WIFI_4,
185 /** 802.11ac. */
186 WIFI_5,
187 /** 802.11ax. */
188 WIFI_6,
189 /** 802.11ax 6GHz. */
190 WIFI_6E,
191 /** 802.11be. */
192 WIFI_7,
193
194 __WIFI_LINK_MODE_AFTER_LAST,
195 WIFI_LINK_MODE_MAX = __WIFI_LINK_MODE_AFTER_LAST - 1,
196 WIFI_LINK_MODE_UNKNOWN
197 };
198
199 /** Helper function to get user-friendly link mode name. */
200 const char *wifi_link_mode_txt(enum wifi_link_mode link_mode);
201
202 /** Wi-Fi scanning types. */
203 enum wifi_scan_type {
204 /** Active scanning (default). */
205 WIFI_SCAN_TYPE_ACTIVE = 0,
206 /** Passive scanning. */
207 WIFI_SCAN_TYPE_PASSIVE,
208 };
209
210 /** Wi-Fi power save states. */
211 enum wifi_ps {
212 /** Power save disabled. */
213 WIFI_PS_DISABLED = 0,
214 /** Power save enabled. */
215 WIFI_PS_ENABLED,
216 };
217
218 /** Helper function to get user-friendly ps name. */
219 const char *wifi_ps_txt(enum wifi_ps ps_name);
220
221 /** Wi-Fi power save modes. */
222 enum wifi_ps_mode {
223 /** Legacy power save mode. */
224 WIFI_PS_MODE_LEGACY = 0,
225 /* This has to be configured before connecting to the AP,
226 * as support for ADDTS action frames is not available.
227 */
228 /** WMM power save mode. */
229 WIFI_PS_MODE_WMM,
230 };
231
232 /** Helper function to get user-friendly ps mode name. */
233 const char *wifi_ps_mode_txt(enum wifi_ps_mode ps_mode);
234
235 /* Interface index Min and Max values */
236 #define WIFI_INTERFACE_INDEX_MIN 1
237 #define WIFI_INTERFACE_INDEX_MAX 255
238
239 /** Wifi operational mode */
240 enum wifi_operational_modes {
241 /** STA mode setting enable */
242 WIFI_STA_MODE = BIT(0),
243 /** Monitor mode setting enable */
244 WIFI_MONITOR_MODE = BIT(1),
245 /** TX injection mode setting enable */
246 WIFI_TX_INJECTION_MODE = BIT(2),
247 /** Promiscuous mode setting enable */
248 WIFI_PROMISCUOUS_MODE = BIT(3),
249 /** AP mode setting enable */
250 WIFI_AP_MODE = BIT(4),
251 /** Softap mode setting enable */
252 WIFI_SOFTAP_MODE = BIT(5),
253 };
254
255 /** Mode filter settings */
256 enum wifi_filter {
257 /** Support management, data and control packet sniffing */
258 WIFI_PACKET_FILTER_ALL = BIT(0),
259 /** Support only sniffing of management packets */
260 WIFI_PACKET_FILTER_MGMT = BIT(1),
261 /** Support only sniffing of data packets */
262 WIFI_PACKET_FILTER_DATA = BIT(2),
263 /** Support only sniffing of control packets */
264 WIFI_PACKET_FILTER_CTRL = BIT(3),
265 };
266
267 /** Wi-Fi Target Wake Time (TWT) operations. */
268 enum wifi_twt_operation {
269 /** TWT setup operation */
270 WIFI_TWT_SETUP = 0,
271 /** TWT teardown operation */
272 WIFI_TWT_TEARDOWN,
273 };
274
275 /** Helper function to get user-friendly twt operation name. */
276 const char *wifi_twt_operation_txt(enum wifi_twt_operation twt_operation);
277
278 /** Wi-Fi Target Wake Time (TWT) negotiation types. */
279 enum wifi_twt_negotiation_type {
280 /** TWT individual negotiation */
281 WIFI_TWT_INDIVIDUAL = 0,
282 /** TWT broadcast negotiation */
283 WIFI_TWT_BROADCAST,
284 /** TWT wake TBTT negotiation */
285 WIFI_TWT_WAKE_TBTT
286 };
287
288 /** Helper function to get user-friendly twt negotiation type name. */
289 const char *wifi_twt_negotiation_type_txt(enum wifi_twt_negotiation_type twt_negotiation);
290
291 /** Wi-Fi Target Wake Time (TWT) setup commands. */
292 enum wifi_twt_setup_cmd {
293 /** TWT setup request */
294 WIFI_TWT_SETUP_CMD_REQUEST = 0,
295 /** TWT setup suggest (parameters can be changed by AP) */
296 WIFI_TWT_SETUP_CMD_SUGGEST,
297 /** TWT setup demand (parameters can not be changed by AP) */
298 WIFI_TWT_SETUP_CMD_DEMAND,
299 /** TWT setup grouping (grouping of TWT flows) */
300 WIFI_TWT_SETUP_CMD_GROUPING,
301 /** TWT setup accept (parameters accepted by AP) */
302 WIFI_TWT_SETUP_CMD_ACCEPT,
303 /** TWT setup alternate (alternate parameters suggested by AP) */
304 WIFI_TWT_SETUP_CMD_ALTERNATE,
305 /** TWT setup dictate (parameters dictated by AP) */
306 WIFI_TWT_SETUP_CMD_DICTATE,
307 /** TWT setup reject (parameters rejected by AP) */
308 WIFI_TWT_SETUP_CMD_REJECT,
309 };
310
311 /** Helper function to get user-friendly twt setup cmd name. */
312 const char *wifi_twt_setup_cmd_txt(enum wifi_twt_setup_cmd twt_setup);
313
314 /** Wi-Fi Target Wake Time (TWT) negotiation status. */
315 enum wifi_twt_setup_resp_status {
316 /** TWT response received for TWT request */
317 WIFI_TWT_RESP_RECEIVED = 0,
318 /** TWT response not received for TWT request */
319 WIFI_TWT_RESP_NOT_RECEIVED,
320 };
321
322 /** Target Wake Time (TWT) error codes. */
323 enum wifi_twt_fail_reason {
324 /** Unspecified error */
325 WIFI_TWT_FAIL_UNSPECIFIED,
326 /** Command execution failed */
327 WIFI_TWT_FAIL_CMD_EXEC_FAIL,
328 /** Operation not supported */
329 WIFI_TWT_FAIL_OPERATION_NOT_SUPPORTED,
330 /** Unable to get interface status */
331 WIFI_TWT_FAIL_UNABLE_TO_GET_IFACE_STATUS,
332 /** Device not connected to AP */
333 WIFI_TWT_FAIL_DEVICE_NOT_CONNECTED,
334 /** Peer not HE (802.11ax/Wi-Fi 6) capable */
335 WIFI_TWT_FAIL_PEER_NOT_HE_CAPAB,
336 /** Peer not TWT capable */
337 WIFI_TWT_FAIL_PEER_NOT_TWT_CAPAB,
338 /** A TWT flow is already in progress */
339 WIFI_TWT_FAIL_OPERATION_IN_PROGRESS,
340 /** Invalid negotiated flow id */
341 WIFI_TWT_FAIL_INVALID_FLOW_ID,
342 /** IP address not assigned or configured */
343 WIFI_TWT_FAIL_IP_NOT_ASSIGNED,
344 /** Flow already exists */
345 WIFI_TWT_FAIL_FLOW_ALREADY_EXISTS,
346 };
347
348 /** Wi-Fi Target Wake Time (TWT) teradown status. */
349 enum wifi_twt_teardown_status {
350 /** TWT teardown success */
351 WIFI_TWT_TEARDOWN_SUCCESS = 0,
352 /** TWT teardown failure */
353 WIFI_TWT_TEARDOWN_FAILED,
354 };
355
356 /** @cond INTERNAL_HIDDEN */
357 static const char * const wifi_twt_err_code_tbl[] = {
358 [WIFI_TWT_FAIL_UNSPECIFIED] = "Unspecified",
359 [WIFI_TWT_FAIL_CMD_EXEC_FAIL] = "Command Execution failed",
360 [WIFI_TWT_FAIL_OPERATION_NOT_SUPPORTED] =
361 "Operation not supported",
362 [WIFI_TWT_FAIL_UNABLE_TO_GET_IFACE_STATUS] =
363 "Unable to get iface status",
364 [WIFI_TWT_FAIL_DEVICE_NOT_CONNECTED] =
365 "Device not connected",
366 [WIFI_TWT_FAIL_PEER_NOT_HE_CAPAB] = "Peer not HE capable",
367 [WIFI_TWT_FAIL_PEER_NOT_TWT_CAPAB] = "Peer not TWT capable",
368 [WIFI_TWT_FAIL_OPERATION_IN_PROGRESS] =
369 "Operation already in progress",
370 [WIFI_TWT_FAIL_INVALID_FLOW_ID] =
371 "Invalid negotiated flow id",
372 [WIFI_TWT_FAIL_IP_NOT_ASSIGNED] =
373 "IP address not assigned",
374 [WIFI_TWT_FAIL_FLOW_ALREADY_EXISTS] =
375 "Flow already exists",
376 };
377 /** @endcond */
378
379 /** Helper function to get user-friendly TWT error code name. */
wifi_twt_get_err_code_str(int16_t err_no)380 static inline const char *wifi_twt_get_err_code_str(int16_t err_no)
381 {
382 if ((err_no) < (int16_t)ARRAY_SIZE(wifi_twt_err_code_tbl)) {
383 return wifi_twt_err_code_tbl[err_no];
384 }
385
386 return "<unknown>";
387 }
388
389 /** Wi-Fi power save parameters. */
390 enum wifi_ps_param_type {
391 /** Power save state. */
392 WIFI_PS_PARAM_STATE,
393 /** Power save listen interval. */
394 WIFI_PS_PARAM_LISTEN_INTERVAL,
395 /** Power save wakeup mode. */
396 WIFI_PS_PARAM_WAKEUP_MODE,
397 /** Power save mode. */
398 WIFI_PS_PARAM_MODE,
399 /** Power save timeout. */
400 WIFI_PS_PARAM_TIMEOUT,
401 };
402
403 /** Wi-Fi power save modes. */
404 enum wifi_ps_wakeup_mode {
405 /** DTIM based wakeup. */
406 WIFI_PS_WAKEUP_MODE_DTIM = 0,
407 /** Listen interval based wakeup. */
408 WIFI_PS_WAKEUP_MODE_LISTEN_INTERVAL,
409 };
410
411 /** Helper function to get user-friendly ps wakeup mode name. */
412 const char *wifi_ps_wakeup_mode_txt(enum wifi_ps_wakeup_mode ps_wakeup_mode);
413
414 /** Wi-Fi power save error codes. */
415 enum wifi_config_ps_param_fail_reason {
416 /** Unspecified error */
417 WIFI_PS_PARAM_FAIL_UNSPECIFIED,
418 /** Command execution failed */
419 WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL,
420 /** Parameter not supported */
421 WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED,
422 /** Unable to get interface status */
423 WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS,
424 /** Device not connected to AP */
425 WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED,
426 /** Device already connected to AP */
427 WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED,
428 /** Listen interval out of range */
429 WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID,
430 };
431
432 /** @cond INTERNAL_HIDDEN */
433 static const char * const wifi_ps_param_config_err_code_tbl[] = {
434 [WIFI_PS_PARAM_FAIL_UNSPECIFIED] = "Unspecified",
435 [WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL] = "Command Execution failed",
436 [WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED] =
437 "Operation not supported",
438 [WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS] =
439 "Unable to get iface status",
440 [WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED] =
441 "Cannot set parameters while device not connected",
442 [WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED] =
443 "Cannot set parameters while device connected",
444 [WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID] =
445 "Parameter out of range",
446 };
447 /** @endcond */
448
449 /** Helper function to get user-friendly power save error code name. */
wifi_ps_get_config_err_code_str(int16_t err_no)450 static inline const char *wifi_ps_get_config_err_code_str(int16_t err_no)
451 {
452 if ((err_no) < (int16_t)ARRAY_SIZE(wifi_ps_param_config_err_code_tbl)) {
453 return wifi_ps_param_config_err_code_tbl[err_no];
454 }
455
456 return "<unknown>";
457 }
458
459 #ifdef __cplusplus
460 }
461 #endif
462
463 /**
464 * @}
465 */
466 #endif /* ZEPHYR_INCLUDE_NET_WIFI_H_ */
467
