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