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 0x154 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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 #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 net_event_ieee802154_cmd { 259 NET_EVENT_IEEE802154_CMD_SCAN_RESULT = 1, 260 }; 261 262 /** 263 * INTERNAL_HIDDEN @endcond 264 */ 265 266 /** 267 * @name Event Macros 268 * 269 * @brief IEEE 802.15.4 net management events. 270 * 271 * @details These IEEE 802.15.4 subsystem net management events can be 272 * subscribed to by applications via @ref net_mgmt_init_event_callback, @ref 273 * net_mgmt_add_event_callback and @ref net_mgmt_del_event_callback. 274 * 275 * @{ 276 */ 277 278 /** 279 * Signals the result of the @ref NET_REQUEST_IEEE802154_ACTIVE_SCAN or @ref 280 * NET_REQUEST_IEEE802154_PASSIVE_SCAN net management commands. 281 * 282 * See @ref ieee802154_req_params for associated event parameters. 283 */ 284 #define NET_EVENT_IEEE802154_SCAN_RESULT \ 285 (_NET_IEEE802154_EVENT | NET_EVENT_IEEE802154_CMD_SCAN_RESULT) 286 287 /** 288 * @} 289 */ 290 291 /** 292 * @cond INTERNAL_HIDDEN 293 */ 294 295 #define IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan) \ 296 (_channel_set & BIT(_chan - 1)) 297 #define IEEE802154_IS_CHAN_UNSCANNED(_channel_set, _chan) \ 298 (!IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan)) 299 300 #define IEEE802154_ALL_CHANNELS UINT32_MAX 301 302 /** 303 * INTERNAL_HIDDEN @endcond 304 */ 305 306 /** 307 * @brief Scanning parameters 308 * 309 * Used to request a scan and get results as well, see section 8.2.11.2 310 */ 311 struct ieee802154_req_params { 312 /** The set of channels to scan, use above macros to manage it */ 313 uint32_t channel_set; 314 315 /** Duration of scan, per-channel, in milliseconds */ 316 uint32_t duration; 317 318 /** Current channel in use as a result */ 319 uint16_t channel; /* in CPU byte order */ 320 /** Current pan_id in use as a result */ 321 uint16_t pan_id; /* in CPU byte order */ 322 323 /** Result address */ 324 union { 325 uint16_t short_addr; /**< in CPU byte order */ 326 uint8_t addr[IEEE802154_MAX_ADDR_LENGTH]; /**< in big endian */ 327 }; 328 329 /** length of address */ 330 uint8_t len; 331 /** Link quality information, between 0 and 255 */ 332 uint8_t lqi; 333 /** Flag if association is permitted by the coordinator */ 334 bool association_permitted; 335 336 /** Additional payload of the beacon if any.*/ 337 uint8_t *beacon_payload; 338 /** Length of the additional payload. */ 339 size_t beacon_payload_len; 340 }; 341 342 /** 343 * @brief Security parameters 344 * 345 * Used to setup the link-layer security settings, 346 * see tables 9-9 and 9-10 in section 9.5. 347 */ 348 struct ieee802154_security_params { 349 uint8_t key[16]; /**< secKeyDescriptor.secKey */ 350 uint8_t key_len; /**< Key length of 16 bytes is mandatory for standards conformance */ 351 uint8_t key_mode : 2; /**< secKeyIdMode */ 352 uint8_t level : 3; /**< Used instead of a frame-specific SecurityLevel parameter when 353 * constructing the auxiliary security header 354 */ 355 uint8_t _unused : 3; /**< unused value (ignore) */ 356 }; 357 358 #ifdef __cplusplus 359 } 360 #endif 361 362 /** 363 * @} 364 */ 365 366 #endif /* ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_ */ 367
