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    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           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 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           1 : #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           1 : struct ieee802154_req_params {
     312             :         /** The set of channels to scan, use above macros to manage it */
     313           1 :         uint32_t channel_set;
     314             : 
     315             :         /** Duration of scan, per-channel, in milliseconds */
     316           1 :         uint32_t duration;
     317             : 
     318             :         /** Current channel in use as a result */
     319           1 :         uint16_t channel; /* in CPU byte order */
     320             :         /** Current pan_id in use as a result */
     321           1 :         uint16_t pan_id; /* in CPU byte order */
     322             : 
     323             :         /** Result address */
     324             :         union {
     325           1 :                 uint16_t short_addr;                      /**< in CPU byte order */
     326           1 :                 uint8_t addr[IEEE802154_MAX_ADDR_LENGTH]; /**< in big endian */
     327           1 :         };
     328             : 
     329             :         /** length of address */
     330           1 :         uint8_t len;
     331             :         /** Link quality information, between 0 and 255 */
     332           1 :         uint8_t lqi;
     333             :         /** Flag if association is permitted by the coordinator */
     334           1 :         bool association_permitted;
     335             : 
     336             :         /** Additional payload of the beacon if any.*/
     337           1 :         uint8_t *beacon_payload;
     338             :         /** Length of the additional payload. */
     339           1 :         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           1 : struct ieee802154_security_params {
     349           1 :         uint8_t key[16];      /**< secKeyDescriptor.secKey */
     350           1 :         uint8_t key_len;      /**< Key length of 16 bytes is mandatory for standards conformance */
     351           1 :         uint8_t key_mode : 2; /**< secKeyIdMode */
     352           1 :         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_ */