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 * 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 * const 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 /** @cond INTERNAL_HIDDEN */
349 static const char * const wifi_twt_err_code_tbl[] = {
350 [WIFI_TWT_FAIL_UNSPECIFIED] = "Unspecified",
351 [WIFI_TWT_FAIL_CMD_EXEC_FAIL] = "Command Execution failed",
352 [WIFI_TWT_FAIL_OPERATION_NOT_SUPPORTED] =
353 "Operation not supported",
354 [WIFI_TWT_FAIL_UNABLE_TO_GET_IFACE_STATUS] =
355 "Unable to get iface status",
356 [WIFI_TWT_FAIL_DEVICE_NOT_CONNECTED] =
357 "Device not connected",
358 [WIFI_TWT_FAIL_PEER_NOT_HE_CAPAB] = "Peer not HE capable",
359 [WIFI_TWT_FAIL_PEER_NOT_TWT_CAPAB] = "Peer not TWT capable",
360 [WIFI_TWT_FAIL_OPERATION_IN_PROGRESS] =
361 "Operation already in progress",
362 [WIFI_TWT_FAIL_INVALID_FLOW_ID] =
363 "Invalid negotiated flow id",
364 [WIFI_TWT_FAIL_IP_NOT_ASSIGNED] =
365 "IP address not assigned",
366 [WIFI_TWT_FAIL_FLOW_ALREADY_EXISTS] =
367 "Flow already exists",
368 };
369 /** @endcond */
370
371 /** Helper function to get user-friendly TWT error code name. */
wifi_twt_get_err_code_str(int16_t err_no)372 static inline const char *wifi_twt_get_err_code_str(int16_t err_no)
373 {
374 if ((err_no) < (int16_t)ARRAY_SIZE(wifi_twt_err_code_tbl)) {
375 return wifi_twt_err_code_tbl[err_no];
376 }
377
378 return "<unknown>";
379 }
380
381 /** Wi-Fi power save parameters. */
382 enum wifi_ps_param_type {
383 /** Power save state. */
384 WIFI_PS_PARAM_STATE,
385 /** Power save listen interval. */
386 WIFI_PS_PARAM_LISTEN_INTERVAL,
387 /** Power save wakeup mode. */
388 WIFI_PS_PARAM_WAKEUP_MODE,
389 /** Power save mode. */
390 WIFI_PS_PARAM_MODE,
391 /** Power save timeout. */
392 WIFI_PS_PARAM_TIMEOUT,
393 };
394
395 /** Wi-Fi power save modes. */
396 enum wifi_ps_wakeup_mode {
397 /** DTIM based wakeup. */
398 WIFI_PS_WAKEUP_MODE_DTIM = 0,
399 /** Listen interval based wakeup. */
400 WIFI_PS_WAKEUP_MODE_LISTEN_INTERVAL,
401 };
402
403 /** Helper function to get user-friendly ps wakeup mode name. */
404 const char * const wifi_ps_wakeup_mode_txt(enum wifi_ps_wakeup_mode ps_wakeup_mode);
405
406 /** Wi-Fi power save error codes. */
407 enum wifi_config_ps_param_fail_reason {
408 /** Unspecified error */
409 WIFI_PS_PARAM_FAIL_UNSPECIFIED,
410 /** Command execution failed */
411 WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL,
412 /** Parameter not supported */
413 WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED,
414 /** Unable to get interface status */
415 WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS,
416 /** Device not connected to AP */
417 WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED,
418 /** Device already connected to AP */
419 WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED,
420 /** Listen interval out of range */
421 WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID,
422 };
423
424 /** @cond INTERNAL_HIDDEN */
425 static const char * const wifi_ps_param_config_err_code_tbl[] = {
426 [WIFI_PS_PARAM_FAIL_UNSPECIFIED] = "Unspecified",
427 [WIFI_PS_PARAM_FAIL_CMD_EXEC_FAIL] = "Command Execution failed",
428 [WIFI_PS_PARAM_FAIL_OPERATION_NOT_SUPPORTED] =
429 "Operation not supported",
430 [WIFI_PS_PARAM_FAIL_UNABLE_TO_GET_IFACE_STATUS] =
431 "Unable to get iface status",
432 [WIFI_PS_PARAM_FAIL_DEVICE_NOT_CONNECTED] =
433 "Cannot set parameters while device not connected",
434 [WIFI_PS_PARAM_FAIL_DEVICE_CONNECTED] =
435 "Cannot set parameters while device connected",
436 [WIFI_PS_PARAM_LISTEN_INTERVAL_RANGE_INVALID] =
437 "Parameter out of range",
438 };
439 /** @endcond */
440
441 /** Helper function to get user-friendly power save error code name. */
wifi_ps_get_config_err_code_str(int16_t err_no)442 static inline const char *wifi_ps_get_config_err_code_str(int16_t err_no)
443 {
444 if ((err_no) < (int16_t)ARRAY_SIZE(wifi_ps_param_config_err_code_tbl)) {
445 return wifi_ps_param_config_err_code_tbl[err_no];
446 }
447
448 return "<unknown>";
449 }
450
451 #ifdef __cplusplus
452 }
453 #endif
454
455 /**
456 * @}
457 */
458 #endif /* ZEPHYR_INCLUDE_NET_WIFI_H_ */
459
