/** * 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 #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