blob: 1f08c0b73c063be527c726fc3b48f822c9270dc8 [file] [log] [blame]
/*
* Copyright (c) 2017 Intel Corporation.
*
* SPDX-License-Identifier: Apache-2.0
*/
/**
* @file
* @brief IEEE 802.15.4 Management interface public header
*
* @note All references to the standard in this file cite IEEE 802.15.4-2020.
*/
#ifndef ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_
#define ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_
#include <zephyr/net/ieee802154.h>
#include <zephyr/net/net_mgmt.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @defgroup ieee802154_mgmt IEEE 802.15.4 Net Management
* @since 1.0
* @version 0.8.0
* @ingroup ieee802154
*
* @brief IEEE 802.15.4 net management library
*
* @details The IEEE 802.15.4 net management library provides runtime
* configuration features that applications can interface with directly.
*
* Most of these commands are also accessible via shell commands. See the
* shell's help feature (`shell> ieee802154 help`).
*
* @note All section, table and figure references are to the IEEE 802.15.4-2020
* standard.
*
* @{
*/
/**
* @cond INTERNAL_HIDDEN
*/
#define _NET_IEEE802154_LAYER NET_MGMT_LAYER_L2
#define _NET_IEEE802154_CODE 0x154
#define _NET_IEEE802154_BASE (NET_MGMT_IFACE_BIT | \
NET_MGMT_LAYER(_NET_IEEE802154_LAYER) |\
NET_MGMT_LAYER_CODE(_NET_IEEE802154_CODE))
#define _NET_IEEE802154_EVENT (_NET_IEEE802154_BASE | NET_MGMT_EVENT_BIT)
enum net_request_ieee802154_cmd {
NET_REQUEST_IEEE802154_CMD_SET_ACK = 1,
NET_REQUEST_IEEE802154_CMD_UNSET_ACK,
NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN,
NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN,
NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN,
NET_REQUEST_IEEE802154_CMD_ASSOCIATE,
NET_REQUEST_IEEE802154_CMD_DISASSOCIATE,
NET_REQUEST_IEEE802154_CMD_SET_CHANNEL,
NET_REQUEST_IEEE802154_CMD_GET_CHANNEL,
NET_REQUEST_IEEE802154_CMD_SET_PAN_ID,
NET_REQUEST_IEEE802154_CMD_GET_PAN_ID,
NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR,
NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR,
NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR,
NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR,
NET_REQUEST_IEEE802154_CMD_GET_TX_POWER,
NET_REQUEST_IEEE802154_CMD_SET_TX_POWER,
NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS,
NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS,
};
/**
* INTERNAL_HIDDEN @endcond
*/
/**
* @name Command Macros
*
* @brief IEEE 802.15.4 net management commands.
*
* @details These IEEE 802.15.4 subsystem net management commands can be called
* by applications via @ref net_mgmt macro.
*
* All attributes and parameters are given in CPU byte order (scalars) or big
* endian (byte arrays) unless otherwise specified.
*
* The following IEEE 802.15.4 MAC management service primitives are referenced
* in this enumeration:
* - MLME-ASSOCIATE.request, see section 8.2.3
* - MLME-DISASSOCIATE.request, see section 8.2.4
* - MLME-SET/GET.request, see section 8.2.6
* - MLME-SCAN.request, see section 8.2.11
*
* The following IEEE 802.15.4 MAC data service primitives are referenced in
* this enumeration:
* - MLME-DATA.request, see section 8.3.2
*
* MAC PIB attributes (mac.../sec...): see sections 8.4.3 and 9.5.
* PHY PIB attributes (phy...): see section 11.3.
* Both are accessed through MLME-SET/GET primitives.
*
* @{
*/
/** Sets AckTx for all subsequent MLME-DATA (aka TX) requests. */
#define NET_REQUEST_IEEE802154_SET_ACK (_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_ACK)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_ACK);
/** Unsets AckTx for all subsequent MLME-DATA requests. */
#define NET_REQUEST_IEEE802154_UNSET_ACK \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_UNSET_ACK)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_UNSET_ACK);
/**
* MLME-SCAN(PASSIVE, ...) request
*
* See @ref ieee802154_req_params for associated command parameters.
*/
#define NET_REQUEST_IEEE802154_PASSIVE_SCAN \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_PASSIVE_SCAN)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_PASSIVE_SCAN);
/**
* MLME-SCAN(ACTIVE, ...) request
*
* See @ref ieee802154_req_params for associated command parameters.
*/
#define NET_REQUEST_IEEE802154_ACTIVE_SCAN \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ACTIVE_SCAN)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ACTIVE_SCAN);
/** Cancels an ongoing MLME-SCAN(...) command (non-standard). */
#define NET_REQUEST_IEEE802154_CANCEL_SCAN \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_CANCEL_SCAN)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_CANCEL_SCAN);
/** MLME-ASSOCIATE(...) request */
#define NET_REQUEST_IEEE802154_ASSOCIATE \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_ASSOCIATE)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_ASSOCIATE);
/** MLME-DISASSOCIATE(...) request */
#define NET_REQUEST_IEEE802154_DISASSOCIATE \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_DISASSOCIATE)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_DISASSOCIATE);
/** MLME-SET(phyCurrentChannel) request */
#define NET_REQUEST_IEEE802154_SET_CHANNEL \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_CHANNEL)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_CHANNEL);
/** MLME-GET(phyCurrentChannel) request */
#define NET_REQUEST_IEEE802154_GET_CHANNEL \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_CHANNEL)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_CHANNEL);
/** MLME-SET(macPanId) request */
#define NET_REQUEST_IEEE802154_SET_PAN_ID \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_PAN_ID)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_PAN_ID);
/** MLME-GET(macPanId) request */
#define NET_REQUEST_IEEE802154_GET_PAN_ID \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_PAN_ID)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_PAN_ID);
/**
* Sets the extended interface address (non-standard), see sections 7.1
* and 8.4.3.1, in big endian byte order
*/
#define NET_REQUEST_IEEE802154_SET_EXT_ADDR \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_EXT_ADDR)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_EXT_ADDR);
/** like MLME-GET(macExtendedAddress) but in big endian byte order */
#define NET_REQUEST_IEEE802154_GET_EXT_ADDR \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_EXT_ADDR)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_EXT_ADDR);
/** MLME-SET(macShortAddress) request, only allowed for co-ordinators */
#define NET_REQUEST_IEEE802154_SET_SHORT_ADDR \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SHORT_ADDR)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SHORT_ADDR);
/** MLME-GET(macShortAddress) request */
#define NET_REQUEST_IEEE802154_GET_SHORT_ADDR \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SHORT_ADDR)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SHORT_ADDR);
/**
* MLME-SET(phyUnicastTxPower/phyBroadcastTxPower) request (currently
* not distinguished)
*/
#define NET_REQUEST_IEEE802154_GET_TX_POWER \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_TX_POWER)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_TX_POWER);
/** MLME-GET(phyUnicastTxPower/phyBroadcastTxPower) request */
#define NET_REQUEST_IEEE802154_SET_TX_POWER \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_TX_POWER)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_TX_POWER);
#ifdef CONFIG_NET_L2_IEEE802154_SECURITY
/**
* Configures basic sec* MAC PIB attributes, implies
* macSecurityEnabled=true.
*
* See @ref ieee802154_security_params for associated command parameters.
*/
#define NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_SET_SECURITY_SETTINGS)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_SET_SECURITY_SETTINGS);
/**
* Gets the configured sec* attributes.
*
* See @ref ieee802154_security_params for associated command parameters.
*/
#define NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS \
(_NET_IEEE802154_BASE | NET_REQUEST_IEEE802154_CMD_GET_SECURITY_SETTINGS)
NET_MGMT_DEFINE_REQUEST_HANDLER(NET_REQUEST_IEEE802154_GET_SECURITY_SETTINGS);
#endif /* CONFIG_NET_L2_IEEE802154_SECURITY */
/**
* @}
*/
/**
* @cond INTERNAL_HIDDEN
*/
enum net_event_ieee802154_cmd {
NET_EVENT_IEEE802154_CMD_SCAN_RESULT = 1,
};
/**
* INTERNAL_HIDDEN @endcond
*/
/**
* @name Event Macros
*
* @brief IEEE 802.15.4 net management events.
*
* @details These IEEE 802.15.4 subsystem net management events can be
* subscribed to by applications via @ref net_mgmt_init_event_callback, @ref
* net_mgmt_add_event_callback and @ref net_mgmt_del_event_callback.
*
* @{
*/
/**
* Signals the result of the @ref NET_REQUEST_IEEE802154_ACTIVE_SCAN or @ref
* NET_REQUEST_IEEE802154_PASSIVE_SCAN net management commands.
*
* See @ref ieee802154_req_params for associated event parameters.
*/
#define NET_EVENT_IEEE802154_SCAN_RESULT \
(_NET_IEEE802154_EVENT | NET_EVENT_IEEE802154_CMD_SCAN_RESULT)
/**
* @}
*/
/**
* @cond INTERNAL_HIDDEN
*/
#define IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan) \
(_channel_set & BIT(_chan - 1))
#define IEEE802154_IS_CHAN_UNSCANNED(_channel_set, _chan) \
(!IEEE802154_IS_CHAN_SCANNED(_channel_set, _chan))
#define IEEE802154_ALL_CHANNELS UINT32_MAX
/**
* INTERNAL_HIDDEN @endcond
*/
/**
* @brief Scanning parameters
*
* Used to request a scan and get results as well, see section 8.2.11.2
*/
struct ieee802154_req_params {
/** The set of channels to scan, use above macros to manage it */
uint32_t channel_set;
/** Duration of scan, per-channel, in milliseconds */
uint32_t duration;
/** Current channel in use as a result */
uint16_t channel; /* in CPU byte order */
/** Current pan_id in use as a result */
uint16_t pan_id; /* in CPU byte order */
/** Result address */
union {
uint16_t short_addr; /* in CPU byte order */
uint8_t addr[IEEE802154_MAX_ADDR_LENGTH]; /* in big endian */
};
/** length of address */
uint8_t len;
/** Link quality information, between 0 and 255 */
uint8_t lqi;
};
/**
* @brief Security parameters
*
* Used to setup the link-layer security settings,
* see tables 9-9 and 9-10 in section 9.5.
*/
struct ieee802154_security_params {
uint8_t key[16]; /* secKeyDescriptor.secKey */
uint8_t key_len; /* a key length of 16 bytes is mandatory for standards conformance */
uint8_t key_mode : 2; /* secKeyIdMode */
uint8_t level : 3; /* Used instead of a frame-specific SecurityLevel parameter when
* constructing the auxiliary security header
*/
uint8_t _unused : 3;
};
#ifdef __cplusplus
}
#endif
/**
* @}
*/
#endif /* ZEPHYR_INCLUDE_NET_IEEE802154_MGMT_H_ */