Line data Source code
1 1 : /*
2 : * Copyright (c) 2017 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : /**
8 : * @file
9 : * @brief IEEE 802.15.4 Management interface public header
10 : *
11 : * @note All references to the standard in this file cite IEEE 802.15.4-2020.
12 : */
13 :
14 : #ifndef ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_
15 : #define ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_
16 :
17 : #include <zephyr/net/ieee802154.h>
18 : #include <zephyr/net/net_mgmt.h>
19 :
20 : #ifdef __cplusplus
21 : extern "C" {
22 : #endif
23 :
24 : /**
25 : * @defgroup ieee802154_mgmt IEEE 802.15.4 Net Management
26 : * @since 1.0
27 : * @version 0.8.0
28 : * @ingroup ieee802154
29 : *
30 : * @brief IEEE 802.15.4 net management library
31 : *
32 : * @details The IEEE 802.15.4 net management library provides runtime
33 : * configuration features that applications can interface with directly.
34 : *
35 : * Most of these commands are also accessible via shell commands. See the
36 : * shell's help feature (`shell> ieee802154 help`).
37 : *
38 : * @note All section, table and figure references are to the IEEE 802.15.4-2020
39 : * standard.
40 : *
41 : * @{
42 : */
43 :
44 : /**
45 : * @cond INTERNAL_HIDDEN
46 : */
47 :
48 : #define NET_IEEE802154_LAYER NET_MGMT_LAYER_L2
49 : #define NET_IEEE802154_CODE NET_MGMT_LAYER_CODE_IEEE802514
50 : #define NET_IEEE802154_BASE (NET_MGMT_IFACE_BIT | \
51 : NET_MGMT_LAYER(NET_IEEE802154_LAYER) |\
52 : NET_MGMT_LAYER_CODE(NET_IEEE802154_CODE))
53 : #define NET_IEEE802154_EVENT (NET_IEEE802154_BASE | NET_MGMT_EVENT_BIT)
54 :
55 : enum net_request_ieee802154_cmd {
56 : NET_REQUEST_IEEE802154_CMD_SET_ACK = 1,
57 : NET_REQUEST_IEEE802154_CMD_UNSET_ACK,
58 : NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN,
59 : NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN,
60 : NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN,
61 : NET_REQUEST_IEEE802154_CMD_ASSOCIATE,
62 : NET_REQUEST_IEEE802154_CMD_DISASSOCIATE,
63 : NET_REQUEST_IEEE802154_CMD_SET_CHANNEL,
64 : NET_REQUEST_IEEE802154_CMD_GET_CHANNEL,
65 : NET_REQUEST_IEEE802154_CMD_SET_PAN_ID,
66 : NET_REQUEST_IEEE802154_CMD_GET_PAN_ID,
67 : NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR,
68 : NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR,
69 : NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR,
70 : NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR,
71 : NET_REQUEST_IEEE802154_CMD_GET_TX_POWER,
72 : NET_REQUEST_IEEE802154_CMD_SET_TX_POWER,
73 : NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS,
74 : NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS,
75 : };
76 :
77 : /**
78 : * INTERNAL_HIDDEN @endcond
79 : */
80 :
81 : /**
82 : * @name Command Macros
83 : *
84 : * @brief IEEE 802.15.4 net management commands.
85 : *
86 : * @details These IEEE 802.15.4 subsystem net management commands can be called
87 : * by applications via @ref net_mgmt macro.
88 : *
89 : * All attributes and parameters are given in CPU byte order (scalars) or big
90 : * endian (byte arrays) unless otherwise specified.
91 : *
92 : * The following IEEE 802.15.4 MAC management service primitives are referenced
93 : * in this enumeration:
94 : * - MLME-ASSOCIATE.request, see section 8.2.3
95 : * - MLME-DISASSOCIATE.request, see section 8.2.4
96 : * - MLME-SET/GET.request, see section 8.2.6
97 : * - MLME-SCAN.request, see section 8.2.11
98 : *
99 : * The following IEEE 802.15.4 MAC data service primitives are referenced in
100 : * this enumeration:
101 : * - MLME-DATA.request, see section 8.3.2
102 : *
103 : * MAC PIB attributes (mac.../sec...): see sections 8.4.3 and 9.5.
104 : * PHY PIB attributes (phy...): see section 11.3.
105 : * Both are accessed through MLME-SET/GET primitives.
106 : *
107 : * @{
108 : */
109 :
110 : /** Sets AckTx for all subsequent MLME-DATA (aka TX) requests. */
111 1 : #define NET_REQUEST_IEEE802154_SET_ACK (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_ACK)
112 :
113 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_ACK);
114 :
115 : /** Unsets AckTx for all subsequent MLME-DATA requests. */
116 1 : #define NET_REQUEST_IEEE802154_UNSET_ACK \
117 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_UNSET_ACK)
118 :
119 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_UNSET_ACK);
120 :
121 : /**
122 : * MLME-SCAN(PASSIVE, ...) request
123 : *
124 : * See @ref ieee802154_req_params for associated command parameters.
125 : */
126 1 : #define NET_REQUEST_IEEE802154_PASSIVE_SCAN \
127 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN)
128 :
129 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_PASSIVE_SCAN);
130 :
131 : /**
132 : * MLME-SCAN(ACTIVE, ...) request
133 : *
134 : * See @ref ieee802154_req_params for associated command parameters.
135 : */
136 1 : #define NET_REQUEST_IEEE802154_ACTIVE_SCAN \
137 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN)
138 :
139 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ACTIVE_SCAN);
140 :
141 : /** Cancels an ongoing MLME-SCAN(...) command (non-standard). */
142 1 : #define NET_REQUEST_IEEE802154_CANCEL_SCAN \
143 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN)
144 :
145 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_CANCEL_SCAN);
146 :
147 : /** MLME-ASSOCIATE(...) request */
148 1 : #define NET_REQUEST_IEEE802154_ASSOCIATE \
149 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ASSOCIATE)
150 :
151 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ASSOCIATE);
152 :
153 : /** MLME-DISASSOCIATE(...) request */
154 1 : #define NET_REQUEST_IEEE802154_DISASSOCIATE \
155 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_DISASSOCIATE)
156 :
157 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_DISASSOCIATE);
158 :
159 : /** MLME-SET(phyCurrentChannel) request */
160 1 : #define NET_REQUEST_IEEE802154_SET_CHANNEL \
161 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_CHANNEL)
162 :
163 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_CHANNEL);
164 :
165 : /** MLME-GET(phyCurrentChannel) request */
166 1 : #define NET_REQUEST_IEEE802154_GET_CHANNEL \
167 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_CHANNEL)
168 :
169 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_CHANNEL);
170 :
171 : /** MLME-SET(macPanId) request */
172 1 : #define NET_REQUEST_IEEE802154_SET_PAN_ID \
173 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_PAN_ID)
174 :
175 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_PAN_ID);
176 :
177 : /** MLME-GET(macPanId) request */
178 1 : #define NET_REQUEST_IEEE802154_GET_PAN_ID \
179 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_PAN_ID)
180 :
181 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_PAN_ID);
182 :
183 : /**
184 : * Sets the extended interface address (non-standard), see sections 7.1
185 : * and 8.4.3.1, in big endian byte order
186 : */
187 1 : #define NET_REQUEST_IEEE802154_SET_EXT_ADDR \
188 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR)
189 :
190 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_EXT_ADDR);
191 :
192 : /** like MLME-GET(macExtendedAddress) but in big endian byte order */
193 1 : #define NET_REQUEST_IEEE802154_GET_EXT_ADDR \
194 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR)
195 :
196 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_EXT_ADDR);
197 :
198 : /** MLME-SET(macShortAddress) request, only allowed for co-ordinators */
199 1 : #define NET_REQUEST_IEEE802154_SET_SHORT_ADDR \
200 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR)
201 :
202 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SHORT_ADDR);
203 :
204 : /** MLME-GET(macShortAddress) request */
205 1 : #define NET_REQUEST_IEEE802154_GET_SHORT_ADDR \
206 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR)
207 :
208 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SHORT_ADDR);
209 :
210 : /**
211 : * MLME-SET(phyUnicastTxPower/phyBroadcastTxPower) request (currently
212 : * not distinguished)
213 : */
214 1 : #define NET_REQUEST_IEEE802154_GET_TX_POWER \
215 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_TX_POWER)
216 :
217 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_TX_POWER);
218 :
219 : /** MLME-GET(phyUnicastTxPower/phyBroadcastTxPower) request */
220 1 : #define NET_REQUEST_IEEE802154_SET_TX_POWER \
221 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_TX_POWER)
222 :
223 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_TX_POWER);
224 :
225 : #ifdef CONFIG_NET_L2_IEEE802154_SECURITY
226 :
227 : /**
228 : * Configures basic sec* MAC PIB attributes, implies
229 : * macSecurityEnabled=true.
230 : *
231 : * See @ref ieee802154_security_params for associated command parameters.
232 : */
233 1 : #define NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS \
234 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS)
235 :
236 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS);
237 :
238 : /**
239 : * Gets the configured sec* attributes.
240 : *
241 : * See @ref ieee802154_security_params for associated command parameters.
242 : */
243 1 : #define NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS \
244 : (NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS)
245 :
246 : NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS);
247 :
248 : #endif /* CONFIG_NET_L2_IEEE802154_SECURITY */
249 :
250 : /**
251 : * @}
252 : */
253 :
254 : /**
255 : * @cond INTERNAL_HIDDEN
256 : */
257 :
258 : enum {
259 : NET_EVENT_IEEE802154_CMD_SCAN_RESULT_VAL,
260 :
261 : NET_EVENT_IEEE802154_CMD_MAX
262 : };
263 :
264 : BUILD_ASSERT(NET_EVENT_IEEE802154_CMD_MAX <= NET_MGMT_MAX_COMMANDS,
265 : "Number of events in net_event_ieee802154_cmd exceeds the limit");
266 :
267 : enum net_event_ieee802154_cmd {
268 : NET_MGMT_CMD(NET_EVENT_IEEE802154_CMD_SCAN_RESULT),
269 : };
270 :
271 : /**
272 : * INTERNAL_HIDDEN @endcond
273 : */
274 :
275 : /**
276 : * @name Event Macros
277 : *
278 : * @brief IEEE 802.15.4 net management events.
279 : *
280 : * @details These IEEE 802.15.4 subsystem net management events can be
281 : * subscribed to by applications via @ref net_mgmt_init_event_callback, @ref
282 : * net_mgmt_add_event_callback and @ref net_mgmt_del_event_callback.
283 : *
284 : * @{
285 : */
286 :
287 : /**
288 : * Signals the result of the @ref NET_REQUEST_IEEE802154_ACTIVE_SCAN or @ref
289 : * NET_REQUEST_IEEE802154_PASSIVE_SCAN net management commands.
290 : *
291 : * See @ref ieee802154_req_params for associated event parameters.
292 : */
293 1 : #define NET_EVENT_IEEE802154_SCAN_RESULT \
294 : (NET_IEEE802154_EVENT | NET_EVENT_IEEE802154_CMD_SCAN_RESULT)
295 :
296 : /**
297 : * @}
298 : */
299 :
300 : /**
301 : * @cond INTERNAL_HIDDEN
302 : */
303 :
304 : #define IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan) \
305 : (_channel_set & BIT(_chan - 1))
306 : #define IEEE802154_IS_CHAN_UNSCANNED(_channel_set, _chan) \
307 : (!IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan))
308 :
309 : #define IEEE802154_ALL_CHANNELS UINT32_MAX
310 :
311 : /**
312 : * INTERNAL_HIDDEN @endcond
313 : */
314 :
315 : /**
316 : * @brief Scanning parameters
317 : *
318 : * Used to request a scan and get results as well, see section 8.2.11.2
319 : */
320 1 : struct ieee802154_req_params {
321 : /** The set of channels to scan, use above macros to manage it */
322 1 : uint32_t channel_set;
323 :
324 : /** Duration of scan, per-channel, in milliseconds */
325 1 : uint32_t duration;
326 :
327 : /** Current channel in use as a result */
328 1 : uint16_t channel; /* in CPU byte order */
329 : /** Current pan_id in use as a result */
330 1 : uint16_t pan_id; /* in CPU byte order */
331 :
332 : /** Result address */
333 : union {
334 1 : uint16_t short_addr; /**< in CPU byte order */
335 1 : uint8_t addr[IEEE802154_MAX_ADDR_LENGTH]; /**< in big endian */
336 1 : };
337 :
338 : /** length of address */
339 1 : uint8_t len;
340 : /** Link quality information, between 0 and 255 */
341 1 : uint8_t lqi;
342 : /** Flag if association is permitted by the coordinator */
343 1 : bool association_permitted;
344 :
345 : /** Additional payload of the beacon if any.*/
346 1 : uint8_t *beacon_payload;
347 : /** Length of the additional payload. */
348 1 : size_t beacon_payload_len;
349 : };
350 :
351 : /**
352 : * @brief Security parameters
353 : *
354 : * Used to setup the link-layer security settings,
355 : * see tables 9-9 and 9-10 in section 9.5.
356 : */
357 1 : struct ieee802154_security_params {
358 1 : uint8_t key[16]; /**< secKeyDescriptor.secKey */
359 1 : uint8_t key_len; /**< Key length of 16 bytes is mandatory for standards conformance */
360 1 : uint8_t key_mode : 2; /**< secKeyIdMode */
361 1 : uint8_t level : 3; /**< Used instead of a frame-specific SecurityLevel parameter when
362 : * constructing the auxiliary security header
363 : */
364 : uint8_t _unused : 3; /**< unused value (ignore) */
365 : };
366 :
367 : #ifdef __cplusplus
368 : }
369 : #endif
370 :
371 : /**
372 : * @}
373 : */
374 :
375 : #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_ */
|
