mac_mlme_associate.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  3. *
  4. * All Rights Reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef MAC_MLME_ASSOCIATE_H_INCLUDED
  43. #define MAC_MLME_ASSOCIATE_H_INCLUDED
  44. #include <stdint.h>
  45. #include "mac_common.h"
  46. #include "mac_task_scheduler.h"
  47. /** @file
  48. * The MAC Association module declares the MAC Association routines and necessary types/macros
  49. * according to the MAC specification.
  50. *
  51. * @defgroup mac_assoc MAC MLME Association API
  52. * @ingroup mac_15_4
  53. * @{
  54. * @brief Module to declare MAC MLME Association API.
  55. * @details The MLME Association module declares Association MAC routines and necessary macros/types according
  56. * to the MAC specification. More specifically, MLME Association request aka mlme_associate_req(),
  57. * MLME Association confirm callback typedef aka mlme_associate_conf_cb_t, MLME Association indication
  58. * as mlme_associate_ind(), and MLME Response aka mlme_associate_resp() primitives are declared.
  59. */
  60. /**
  61. * @brief Capability information field.
  62. *
  63. * In accordance with IEEE Std 802.15.4-2006, section 7.3.1.2.
  64. */
  65. #define ALTERNATE_PAN_COORDINATOR_BIT (0)
  66. #define DEVICE_TYPE_BIT (1)
  67. #define POWER_SOURCE_BIT (2)
  68. #define RECEIVER_ON_WHEN_IDLE_BIT (3)
  69. #define SECURITY_CAPABILITY_BIT (6)
  70. #define ALLOCATE_ADDRESS_BIT (7)
  71. /**
  72. * @brief Valid values of the Association Status field
  73. *
  74. * In accordance with IEEE Std 802.15.4-2006, section 7.3.2.3
  75. */
  76. typedef enum
  77. {
  78. MAC_ASSOCIATION_SUCCESSFUL = 0,
  79. MAC_PAN_AT_CAPACITY,
  80. MAC_PAN_ACCESS_DENIED
  81. } mac_association_status_t;
  82. /**
  83. * @brief Capability information field
  84. *
  85. * In accordance with IEEE Std 802.15.4-2006, section 7.3.1.2.
  86. */
  87. typedef struct
  88. {
  89. uint8_t alternate_pan_coordinator : 1;
  90. uint8_t device_type : 1;
  91. uint8_t power_source : 1;
  92. uint8_t rx_on_when_idle : 1;
  93. uint8_t reserved : 2;
  94. uint8_t security_capability : 1;
  95. uint8_t allocate_address : 1;
  96. } mac_capability_t;
  97. /**@brief The Alternate PAN Coordinator subfield of the Capability Information field. */
  98. typedef enum
  99. {
  100. MAC_CAP_CANNOT_BE_PAN_COORD = 0, /**< Device is not capable of becoming
  101. the PAN coordinator.*/
  102. MAC_CAP_CAN_BE_PAN_COORD /**< Device is capable of becoming
  103. the PAN coordinator.*/
  104. } mac_cap_alt_pan_coord_t;
  105. /**@brief The Device Type subfield of the Capability Information field. */
  106. typedef enum
  107. {
  108. MAC_CAP_RFD_DEVICE = 0, /**< Device is an RFD.*/
  109. MAC_CAP_FFD_DEVICE /**< Device is an FFD.*/
  110. } mac_cap_device_type_t;
  111. /**@brief The Power Source subfield of the Capability Information field. */
  112. typedef enum
  113. {
  114. MAC_CAP_BATTERY_POWERED = 0, /**< Device is not AC-powered.*/
  115. MAC_CAP_MAINS_POWERED /**< Device is receiving power from the
  116. alternating current mains.*/
  117. } mac_cap_power_source_t;
  118. /**@brief The Receiver On When Idle subfield of the Capability Information field. */
  119. typedef enum
  120. {
  121. MAC_CAP_RX_OFF_WHEN_IDLE = 0, /**< Device conserves power during idle.*/
  122. MAC_CAP_RX_ON_WHEN_IDLE /**< Device does not disable its receiver
  123. to conserve power during idle periods.*/
  124. } mac_cap_rx_when_idle_t;
  125. /**@brief The Security Capability subfield of the Capability Information field. */
  126. typedef enum
  127. {
  128. MAC_CAP_CANNOT_SECURE = 0, /**< Device does not support securing.*/
  129. MAC_CAP_CAN_SECURE /**< Device is capable of sending and receiving
  130. cryptographically protected MAC frames.*/
  131. } mac_cap_secure_t;
  132. /**@brief The Allocate Address subfield of the Capability Information field. */
  133. typedef enum
  134. {
  135. MAC_CAP_SHORT_ADDR_NOT_REQ = 0, /**< The coordinator will not allocate a
  136. 16-bit short address as a result of
  137. the association procedure.*/
  138. MAC_CAP_SHORT_ADDR_REQ /**< The coordinator will allocate a
  139. 16-bit short address as a result of
  140. the association procedure.*/
  141. } mac_cap_allocate_addr_t;
  142. #if (CONFIG_ASSOCIATE_REQ_ENABLED == 1)
  143. /**
  144. * @brief MLME-ASSOCIATE.confirm
  145. *
  146. * The MLME-ASSOCIATE.confirm primitive is generated by the initiating MLME and
  147. * issued to its next higher layer in response to an MLME-ASSOCIATE.request primitive.
  148. *
  149. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.4.
  150. */
  151. typedef struct
  152. {
  153. uint16_t assoc_short_address; /**< Association short 16-bit address. */
  154. mac_status_t status; /**< Status of operation. */
  155. #if (CONFIG_SECURE == 1)
  156. uint8_t security_level; /**< Security level. */
  157. uint8_t key_id_mode; /**< Key ID mode. */
  158. uint64_t key_source; /**< Key source. */
  159. uint8_t key_index; /**< Key index. */
  160. #endif
  161. } mlme_associate_conf_t;
  162. /**
  163. * @brief MLME-ASSOCIATE.request.
  164. *
  165. * @details Allows a device to request an association with a coordinator.
  166. *
  167. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.1.
  168. */
  169. typedef struct
  170. {
  171. /** Do not edit this field. */
  172. mac_abstract_req_t service;
  173. /** Confirmation to this request. */
  174. mlme_associate_conf_t confirm;
  175. /**
  176. * A total of 27 channels numbered 0 to 26.
  177. * are available per channel page (section 6.1.2.1).
  178. */
  179. uint8_t logical_channel;
  180. /**
  181. * A total of 32 channel pages are available
  182. * with channel pages 3 to 31 being reserved
  183. * for future use (section 6.1.2.2).
  184. */
  185. #ifdef CONFIG_SUB_GHZ
  186. uint8_t channel_page; /**< Channel page. */
  187. #endif
  188. mac_addr_mode_t coord_addr_mode; /**< Coordinator address mode. */
  189. uint16_t coord_pan_id; /**< Coordinator PAN ID. */
  190. mac_addr_t coord_address; /**< Coordinator address. */
  191. mac_capability_t capability_information; /**< Capability information. */
  192. #if (CONFIG_SECURE == 1)
  193. uint8_t security_level; /**< Security level. */
  194. uint8_t key_id_mode; /**< Key ID mode. */
  195. uint64_t key_source; /**< Key source. */
  196. uint8_t key_index; /**< Key index. */
  197. #endif
  198. } mlme_associate_req_t;
  199. #if (CONFIG_ASSOCIATE_IND_ENABLED == 1)
  200. /**
  201. * @brief MLME-ASSOCIATE.indication.
  202. *
  203. * @details The MLME-ASSOCIATE.indication primitive is generated by the MLME of
  204. * the coordinator and issued to its next higher layer to indicate the reception
  205. * of an association request command.
  206. *
  207. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.2.
  208. */
  209. typedef struct
  210. {
  211. uint64_t device_address; /**< 64-bit IEEE address. */
  212. uint8_t capability_information; /**< Capability information. */
  213. #if (CONFIG_SECURE == 1)
  214. uint8_t security_level; /**< Security level. */
  215. uint8_t key_id_mode; /**< Key ID mode. */
  216. uint64_t key_source; /**< Key source. */
  217. uint8_t key_index; /**< Key index. */
  218. #endif
  219. } mlme_associate_ind_t;
  220. /**
  221. * @brief MLME-ASSOCIATE.response.
  222. *
  223. * @details Generated by the next higher layer of a coordinator and issued
  224. * to its MLME in order to respond to the MLME-ASSOCIATE.indication primitive.
  225. *
  226. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.3.
  227. */
  228. typedef struct
  229. {
  230. uint64_t device_address; /**< 64-bit IEEE address. */
  231. uint16_t assoc_short_address; /**< Association short 16-bit address. */
  232. mac_association_status_t status; /**< Status of operation. */
  233. #if (CONFIG_SECURE == 1)
  234. uint8_t security_level; /**< Security level. */
  235. uint8_t key_id_mode; /**< Key ID mode. */
  236. uint64_t key_source; /**< Key source. */
  237. uint8_t key_index; /**< Key index. */
  238. #endif
  239. } mlme_associate_resp_t;
  240. #endif // (CONFIG_ASSOCIATE_IND_ENABLED == 1)
  241. /**
  242. * @brief Confirmation function.
  243. *
  244. * @details The MLME-ASSOCIATE.confirm primitive is generated by the
  245. * initiating MLME and issued to its next higher layer in response to
  246. * an MLME-ASSOCIATE.request primitive. If the request was successful,
  247. * the status parameter will indicate a successful association, as
  248. * contained in the Status field of the association response command.
  249. * Otherwise, the status parameter indicates either an error code from
  250. * the received association response command or the appropriate error
  251. * code from Table 50.
  252. * The status values are fully described in 7.1.3.1.3 and subclauses referenced by 7.1.3.1.3.
  253. *
  254. * @param Pointer to confirmation primitive.
  255. */
  256. typedef void (* mlme_associate_conf_cb_t)(mlme_associate_conf_t *);
  257. /**
  258. * @brief MLME-ASSOCIATE request.
  259. *
  260. * @details Requests an association with a PAN through a coordinator
  261. * After request completion, user callback will be issued with
  262. * valid data stored in structure mlme_set_conf_t.
  263. *
  264. * @param req MLME_ASSOCIATE request structure.
  265. * @param conf_cb Pointer to user callback.
  266. *
  267. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5
  268. */
  269. void mlme_associate_req(mlme_associate_req_t * req, mlme_associate_conf_cb_t conf_cb);
  270. #if (CONFIG_ASSOCIATE_IND_ENABLED == 1)
  271. /**
  272. * @brief MLME-ASSOCIATE indication handler.
  273. *
  274. * @details Indicates an association with a PAN through a coordinator
  275. * next higher layer of a coordinator receives the MLME-ASSOCIATE.indication
  276. * primitive to determine whether to accept or reject the unassociated device
  277. * using an algorithm outside the scope of standard.
  278. *
  279. * @param ind MLME ASSOCIATE indication structure.
  280. *
  281. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5.
  282. */
  283. extern void mlme_associate_ind(mlme_associate_ind_t * ind);
  284. /**
  285. * @brief MLME-ASSOCIATE response.
  286. *
  287. * @details Respond to an association with a PAN and issue to its MLME in order to
  288. * respond to the MLME-ASSOCIATE.indication.
  289. * Response structure passed as a parameter to this function must be retained
  290. * in memory until the related MLME-COMM-STATUS.indication is received.
  291. *
  292. * @param resp MLME_ASSOCIATE response structure.
  293. *
  294. * In accordance with IEEE Std 802.15.4-2006, section 7.1.3.5.
  295. */
  296. void mlme_associate_resp(mlme_associate_resp_t * resp);
  297. #endif // (CONFIG_ASSOCIATE_IND_ENABLED == 1)
  298. #endif // (CONFIG_ASSOCIATE_REQ_ENABLED == 1)
  299. /** @} */
  300. #endif // MAC_MLME_ASSOCIATE_H_INCLUDED