diff options
Diffstat (limited to 'thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_mlme_associate.h')
| -rw-r--r-- | thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_mlme_associate.h | 336 |
1 files changed, 336 insertions, 0 deletions
diff --git a/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_mlme_associate.h b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_mlme_associate.h new file mode 100644 index 0000000..794935c --- /dev/null +++ b/thirdparty/nRF5_SDK_15.0.0_a53641a/components/802_15_4/api/MAC/mac_mlme_associate.h @@ -0,0 +1,336 @@ +/** + * Copyright (c) 2016 - 2018 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh. + * + * All Rights Reserved. + * + * Redistribution and use in source and binary forms, with or without modification, + * are permitted provided that the following conditions are met: + * + * + * 1. Redistributions of source code must retain the above copyright notice, this + * list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form, except as embedded into a Nordic + * Semiconductor ASA integrated circuit in a product or a software update for + * such product, must reproduce the above copyright notice, this list of + * conditions and the following disclaimer in the documentation and/or other + * materials provided with the distribution. + * + * 3. Neither the name of Nordic Semiconductor ASA nor the names of its + * contributors may be used to endorse or promote products derived from this + * software without specific prior written permission. + * + * 4. This software, with or without modification, must only be used with a + * Nordic Semiconductor ASA integrated circuit. + * + * 5. Any software provided in binary form under this license must not be reverse + * engineered, decompiled, modified and/or disassembled. + * + * + * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS + * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE + * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT + * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + * + */ +#ifndef MAC_MLME_ASSOCIATE_H_INCLUDED +#define MAC_MLME_ASSOCIATE_H_INCLUDED + +#include <stdint.h> +#include "mac_common.h" +#include "mac_task_scheduler.h" + +/** @file + * The MAC Association module declares the MAC Association routines and necessary types/macros + * according to the MAC specification. + * + * @defgroup mac_assoc MAC MLME Association API + * @ingroup mac_15_4 + * @{ + * @brief Module to declare MAC MLME Association API. + * @details The MLME Association module declares Association MAC routines and necessary macros/types according + * to the MAC specification. More specifically, MLME Association request aka mlme_associate_req(), + * MLME Association confirm callback typedef aka mlme_associate_conf_cb_t, MLME Association indication + * as mlme_associate_ind(), and MLME Response aka mlme_associate_resp() primitives are declared. + */ + +/** + * @brief Capability information field. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.3.1.2. + */ +#define ALTERNATE_PAN_COORDINATOR_BIT (0) +#define DEVICE_TYPE_BIT (1) +#define POWER_SOURCE_BIT (2) +#define RECEIVER_ON_WHEN_IDLE_BIT (3) +#define SECURITY_CAPABILITY_BIT (6) +#define ALLOCATE_ADDRESS_BIT (7) + + +/** + * @brief Valid values of the Association Status field + * + * In accordance with IEEE Std 802.15.4-2006, section 7.3.2.3 + */ +typedef enum +{ + MAC_ASSOCIATION_SUCCESSFUL = 0, + MAC_PAN_AT_CAPACITY, + MAC_PAN_ACCESS_DENIED +} mac_association_status_t; + +/** + * @brief Capability information field + * + * In accordance with IEEE Std 802.15.4-2006, section 7.3.1.2. + */ +typedef struct +{ + uint8_t alternate_pan_coordinator : 1; + uint8_t device_type : 1; + uint8_t power_source : 1; + uint8_t rx_on_when_idle : 1; + uint8_t reserved : 2; + uint8_t security_capability : 1; + uint8_t allocate_address : 1; +} mac_capability_t; + +/**@brief The Alternate PAN Coordinator subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_CANNOT_BE_PAN_COORD = 0, /**< Device is not capable of becoming + the PAN coordinator.*/ + MAC_CAP_CAN_BE_PAN_COORD /**< Device is capable of becoming + the PAN coordinator.*/ +} mac_cap_alt_pan_coord_t; + +/**@brief The Device Type subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_RFD_DEVICE = 0, /**< Device is an RFD.*/ + MAC_CAP_FFD_DEVICE /**< Device is an FFD.*/ +} mac_cap_device_type_t; + +/**@brief The Power Source subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_BATTERY_POWERED = 0, /**< Device is not AC-powered.*/ + MAC_CAP_MAINS_POWERED /**< Device is receiving power from the + alternating current mains.*/ +} mac_cap_power_source_t; + +/**@brief The Receiver On When Idle subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_RX_OFF_WHEN_IDLE = 0, /**< Device conserves power during idle.*/ + MAC_CAP_RX_ON_WHEN_IDLE /**< Device does not disable its receiver + to conserve power during idle periods.*/ +} mac_cap_rx_when_idle_t; + +/**@brief The Security Capability subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_CANNOT_SECURE = 0, /**< Device does not support securing.*/ + MAC_CAP_CAN_SECURE /**< Device is capable of sending and receiving + cryptographically protected MAC frames.*/ +} mac_cap_secure_t; + +/**@brief The Allocate Address subfield of the Capability Information field. */ +typedef enum +{ + MAC_CAP_SHORT_ADDR_NOT_REQ = 0, /**< The coordinator will not allocate a + 16-bit short address as a result of + the association procedure.*/ + MAC_CAP_SHORT_ADDR_REQ /**< The coordinator will allocate a + 16-bit short address as a result of + the association procedure.*/ +} mac_cap_allocate_addr_t; + +#if (CONFIG_ASSOCIATE_REQ_ENABLED == 1) + +/** + * @brief MLME-ASSOCIATE.confirm + * + * The MLME-ASSOCIATE.confirm primitive is generated by the initiating MLME and + * issued to its next higher layer in response to an MLME-ASSOCIATE.request primitive. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.4. + */ +typedef struct +{ + uint16_t assoc_short_address; /**< Association short 16-bit address. */ + mac_status_t status; /**< Status of operation. */ +#if (CONFIG_SECURE == 1) + uint8_t security_level; /**< Security level. */ + uint8_t key_id_mode; /**< Key ID mode. */ + uint64_t key_source; /**< Key source. */ + uint8_t key_index; /**< Key index. */ +#endif +} mlme_associate_conf_t; + + +/** + * @brief MLME-ASSOCIATE.request. + * + * @details Allows a device to request an association with a coordinator. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.1. + */ +typedef struct +{ + /** Do not edit this field. */ + mac_abstract_req_t service; + + /** Confirmation to this request. */ + mlme_associate_conf_t confirm; + + /** + * A total of 27 channels numbered 0 to 26. + * are available per channel page (section 6.1.2.1). + */ + uint8_t logical_channel; + + /** + * A total of 32 channel pages are available + * with channel pages 3 to 31 being reserved + * for future use (section 6.1.2.2). + */ +#ifdef CONFIG_SUB_GHZ + uint8_t channel_page; /**< Channel page. */ +#endif + mac_addr_mode_t coord_addr_mode; /**< Coordinator address mode. */ + uint16_t coord_pan_id; /**< Coordinator PAN ID. */ + mac_addr_t coord_address; /**< Coordinator address. */ + mac_capability_t capability_information; /**< Capability information. */ +#if (CONFIG_SECURE == 1) + uint8_t security_level; /**< Security level. */ + uint8_t key_id_mode; /**< Key ID mode. */ + uint64_t key_source; /**< Key source. */ + uint8_t key_index; /**< Key index. */ +#endif +} mlme_associate_req_t; + + +#if (CONFIG_ASSOCIATE_IND_ENABLED == 1) +/** + * @brief MLME-ASSOCIATE.indication. + * + * @details The MLME-ASSOCIATE.indication primitive is generated by the MLME of + * the coordinator and issued to its next higher layer to indicate the reception + * of an association request command. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.2. + */ +typedef struct +{ + uint64_t device_address; /**< 64-bit IEEE address. */ + uint8_t capability_information; /**< Capability information. */ +#if (CONFIG_SECURE == 1) + uint8_t security_level; /**< Security level. */ + uint8_t key_id_mode; /**< Key ID mode. */ + uint64_t key_source; /**< Key source. */ + uint8_t key_index; /**< Key index. */ +#endif +} mlme_associate_ind_t; + + +/** + * @brief MLME-ASSOCIATE.response. + * + * @details Generated by the next higher layer of a coordinator and issued + * to its MLME in order to respond to the MLME-ASSOCIATE.indication primitive. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.3. + */ +typedef struct +{ + uint64_t device_address; /**< 64-bit IEEE address. */ + uint16_t assoc_short_address; /**< Association short 16-bit address. */ + mac_association_status_t status; /**< Status of operation. */ +#if (CONFIG_SECURE == 1) + uint8_t security_level; /**< Security level. */ + uint8_t key_id_mode; /**< Key ID mode. */ + uint64_t key_source; /**< Key source. */ + uint8_t key_index; /**< Key index. */ +#endif +} mlme_associate_resp_t; + +#endif // (CONFIG_ASSOCIATE_IND_ENABLED == 1) + +/** + * @brief Confirmation function. + * + * @details The MLME-ASSOCIATE.confirm primitive is generated by the + * initiating MLME and issued to its next higher layer in response to + * an MLME-ASSOCIATE.request primitive. If the request was successful, + * the status parameter will indicate a successful association, as + * contained in the Status field of the association response command. + * Otherwise, the status parameter indicates either an error code from + * the received association response command or the appropriate error + * code from Table 50. + * The status values are fully described in 7.1.3.1.3 and subclauses referenced by 7.1.3.1.3. + * + * @param Pointer to confirmation primitive. + */ +typedef void (* mlme_associate_conf_cb_t)(mlme_associate_conf_t *); + + +/** + * @brief MLME-ASSOCIATE request. + * + * @details Requests an association with a PAN through a coordinator + * After request completion, user callback will be issued with + * valid data stored in structure mlme_set_conf_t. + * + * @param req MLME_ASSOCIATE request structure. + * @param conf_cb Pointer to user callback. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5 + */ +void mlme_associate_req(mlme_associate_req_t * req, mlme_associate_conf_cb_t conf_cb); + + +#if (CONFIG_ASSOCIATE_IND_ENABLED == 1) + +/** + * @brief MLME-ASSOCIATE indication handler. + * + * @details Indicates an association with a PAN through a coordinator + * next higher layer of a coordinator receives the MLME-ASSOCIATE.indication + * primitive to determine whether to accept or reject the unassociated device + * using an algorithm outside the scope of standard. + * + * @param ind MLME ASSOCIATE indication structure. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5. + */ +extern void mlme_associate_ind(mlme_associate_ind_t * ind); + + +/** + * @brief MLME-ASSOCIATE response. + * + * @details Respond to an association with a PAN and issue to its MLME in order to + * respond to the MLME-ASSOCIATE.indication. + * Response structure passed as a parameter to this function must be retained + * in memory until the related MLME-COMM-STATUS.indication is received. + * + * @param resp MLME_ASSOCIATE response structure. + * + * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5. + */ +void mlme_associate_resp(mlme_associate_resp_t * resp); + +#endif // (CONFIG_ASSOCIATE_IND_ENABLED == 1) + +#endif // (CONFIG_ASSOCIATE_REQ_ENABLED == 1) + +/** @} */ + +#endif // MAC_MLME_ASSOCIATE_H_INCLUDED |