gap.h 53 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171
  1. /**
  2. * @file
  3. * @author chipsea
  4. * @brief
  5. * @version 0.1
  6. * @date 2020-11-30
  7. * @copyright Copyright (c) 2020, CHIPSEA Co., Ltd.
  8. * @note
  9. */
  10. /**
  11. @headerfile: gap.h
  12. $Date:
  13. $Revision:
  14. */
  15. #ifndef GAP_H
  16. #define GAP_H
  17. #ifdef __cplusplus
  18. extern "C"
  19. {
  20. #endif
  21. /*-------------------------------------------------------------------
  22. * INCLUDES
  23. */
  24. #include "bcomdef.h"
  25. #include "OSAL.h"
  26. #include "sm.h"
  27. /*-------------------------------------------------------------------
  28. * MACROS
  29. */
  30. /*-------------------------------------------------------------------
  31. * CONSTANTS
  32. */
  33. /** @defgroup BLE_GAP_DEFINES BLE GAP Constants and Structures
  34. * @{
  35. */
  36. /** @defgroup GAP_MSG_EVENT_DEFINES GAP Message IDs
  37. * @{
  38. */
  39. #define GAP_DEVICE_INIT_DONE_EVENT 0x00 //!< Sent when the Device Initialization is complete. This event is sent as an OSAL message defined as gapDeviceInitDoneEvent_t.
  40. #define GAP_DEVICE_DISCOVERY_EVENT 0x01 //!< Sent when the Device Discovery Process is complete. This event is sent as an OSAL message defined as gapDevDiscEvent_t.
  41. #define GAP_ADV_DATA_UPDATE_DONE_EVENT 0x02 //!< Sent when the Advertising Data or SCAN_RSP Data has been updated. This event is sent as an OSAL message defined as gapAdvDataUpdateEvent_t.
  42. #define GAP_MAKE_DISCOVERABLE_DONE_EVENT 0x03 //!< Sent when the Make Discoverable Request is complete. This event is sent as an OSAL message defined as gapMakeDiscoverableRspEvent_t.
  43. #define GAP_END_DISCOVERABLE_DONE_EVENT 0x04 //!< Sent when the Advertising has ended. This event is sent as an OSAL message defined as gapEndDiscoverableRspEvent_t.
  44. #define GAP_LINK_ESTABLISHED_EVENT 0x05 //!< Sent when the Establish Link Request is complete. This event is sent as an OSAL message defined as gapEstLinkReqEvent_t.
  45. #define GAP_LINK_TERMINATED_EVENT 0x06 //!< Sent when a connection was terminated. This event is sent as an OSAL message defined as gapTerminateLinkEvent_t.
  46. #define GAP_LINK_PARAM_UPDATE_EVENT 0x07 //!< Sent when an Update Parameters Event is received. This event is sent as an OSAL message defined as gapLinkUpdateEvent_t.
  47. #define GAP_RANDOM_ADDR_CHANGED_EVENT 0x08 //!< Sent when a random address was changed. This event is sent as an OSAL message defined as gapRandomAddrEvent_t.
  48. #define GAP_SIGNATURE_UPDATED_EVENT 0x09 //!< Sent when the device's signature counter is updated. This event is sent as an OSAL message defined as gapSignUpdateEvent_t.
  49. #define GAP_AUTHENTICATION_COMPLETE_EVENT 0x0A //!< Sent when the Authentication (pairing) process is complete. This event is sent as an OSAL message defined as gapAuthCompleteEvent_t.
  50. #define GAP_PASSKEY_NEEDED_EVENT 0x0B //!< Sent when a Passkey is needed. This is part of the pairing process. This event is sent as an OSAL message defined as gapPasskeyNeededEvent_t.
  51. #define GAP_SLAVE_REQUESTED_SECURITY_EVENT 0x0C //!< Sent when a Slave Security Request is received. This event is sent as an OSAL message defined as gapSlaveSecurityReqEvent_t.
  52. #define GAP_DEVICE_INFO_EVENT 0x0D //!< Sent during the Device Discovery Process when a device is discovered. This event is sent as an OSAL message defined as gapDeviceInfoEvent_t.
  53. #define GAP_BOND_COMPLETE_EVENT 0x0E //!< Sent when the bonding(bound) process is complete. This event is sent as an OSAL message defined as gapBondCompleteEvent_t.
  54. #define GAP_PAIRING_REQ_EVENT 0x0F //!< Sent when an unexpected Pairing Request is received. This event is sent as an OSAL message defined as gapPairingReqEvent_t.
  55. /** @} End GAP_MSG_EVENT_DEFINES */
  56. /** @defgroup GAP_CONN_HANDLE_DEFINES GAP Special Connection Handles
  57. * Used by GAP_TerminateLinkReq()
  58. * @{
  59. */
  60. #define GAP_CONNHANDLE_INIT 0xFFFE //!< terminates a link create
  61. #define GAP_CONNHANDLE_ALL 0xFFFF //!< terminates all links for the matching task ID.
  62. /** @} End GAP_CONN_HANDLE_DEFINES */
  63. /** @defgroup GAP_PROFILE_ROLE_DEFINES GAP Profile Roles
  64. * Bit mask values
  65. * @{
  66. */
  67. #define GAP_PROFILE_BROADCASTER 0x01 //!< A device that sends advertising events only.
  68. #define GAP_PROFILE_OBSERVER 0x02 //!< A device that receives advertising events only.
  69. #define GAP_PROFILE_PERIPHERAL 0x04 //!< A device that accepts the establishment of an LE physical link using the connection establishment procedure
  70. #define GAP_PROFILE_CENTRAL 0x08 //!< A device that supports the Central role initiates the establishment of a physical connection
  71. /** @} End GAP_PROFILE_ROLE_DEFINES */
  72. /**
  73. * @defgroup GAP_PARAMETER_ID_DEFINES GAP Parameter IDs
  74. * Used in place of gapParamIDs_t.
  75. * @{
  76. */
  77. // Timers
  78. #define TGAP_GEN_DISC_ADV_MIN 0 //!< Minimum time to remain advertising, when in Discoverable mode (mSec). Setting this parameter to 0 turns off the timeout (default).
  79. #define TGAP_LIM_ADV_TIMEOUT 1 //!< Maximum time to remain advertising, when in Limited Discoverable mode. In seconds (default 180 seconds)
  80. #define TGAP_GEN_DISC_SCAN 2 //!< Minimum time to perform scanning, when performing General Discovery proc (mSec)
  81. #define TGAP_LIM_DISC_SCAN 3 //!< Minimum time to perform scanning, when performing Limited Discovery proc (mSec)
  82. #define TGAP_CONN_EST_ADV_TIMEOUT 4 //!< Advertising timeout, when performing Connection Establishment proc (mSec)
  83. #define TGAP_CONN_PARAM_TIMEOUT 5 //!< Link Layer connection parameter update notification timer, connection parameter update proc (mSec)
  84. // Constants
  85. #define TGAP_LIM_DISC_ADV_INT_MIN 6 //!< Minimum advertising interval, when in limited discoverable mode (n * 0.625 mSec)
  86. #define TGAP_LIM_DISC_ADV_INT_MAX 7 //!< Maximum advertising interval, when in limited discoverable mode (n * 0.625 mSec)
  87. #define TGAP_GEN_DISC_ADV_INT_MIN 8 //!< Minimum advertising interval, when in General discoverable mode (n * 0.625 mSec)
  88. #define TGAP_GEN_DISC_ADV_INT_MAX 9 //!< Maximum advertising interval, when in General discoverable mode (n * 0.625 mSec)
  89. #define TGAP_CONN_ADV_INT_MIN 10 //!< Minimum advertising interval, when in Connectable mode (n * 0.625 mSec)
  90. #define TGAP_CONN_ADV_INT_MAX 11 //!< Maximum advertising interval, when in Connectable mode (n * 0.625 mSec)
  91. #define TGAP_CONN_SCAN_INT 12 //!< Scan interval used during Link Layer Initiating state, when in Connectable mode (n * 0.625 mSec)
  92. #define TGAP_CONN_SCAN_WIND 13 //!< Scan window used during Link Layer Initiating state, when in Connectable mode (n * 0.625 mSec)
  93. #define TGAP_CONN_HIGH_SCAN_INT 14 //!< Scan interval used during Link Layer Initiating state, when in Connectable mode, high duty scan cycle scan paramaters (n * 0.625 mSec)
  94. #define TGAP_CONN_HIGH_SCAN_WIND 15 //!< Scan window used during Link Layer Initiating state, when in Connectable mode, high duty scan cycle scan paramaters (n * 0.625 mSec)
  95. #define TGAP_GEN_DISC_SCAN_INT 16 //!< Scan interval used during Link Layer Scanning state, when in General Discovery proc (n * 0.625 mSec)
  96. #define TGAP_GEN_DISC_SCAN_WIND 17 //!< Scan window used during Link Layer Scanning state, when in General Discovery proc (n * 0.625 mSec)
  97. #define TGAP_LIM_DISC_SCAN_INT 18 //!< Scan interval used during Link Layer Scanning state, when in Limited Discovery proc (n * 0.625 mSec)
  98. #define TGAP_LIM_DISC_SCAN_WIND 19 //!< Scan window used during Link Layer Scanning state, when in Limited Discovery proc (n * 0.625 mSec)
  99. #define TGAP_CONN_EST_ADV 20 //!< Advertising interval, when using Connection Establishment proc (n * 0.625 mSec). Obsolete - Do not use.
  100. #define TGAP_CONN_EST_INT_MIN 21 //!< Minimum Link Layer connection interval, when using Connection Establishment proc (n * 1.25 mSec)
  101. #define TGAP_CONN_EST_INT_MAX 22 //!< Maximum Link Layer connection interval, when using Connection Establishment proc (n * 1.25 mSec)
  102. #define TGAP_CONN_EST_SCAN_INT 23 //!< Scan interval used during Link Layer Initiating state, when using Connection Establishment proc (n * 0.625 mSec)
  103. #define TGAP_CONN_EST_SCAN_WIND 24 //!< Scan window used during Link Layer Initiating state, when using Connection Establishment proc (n * 0.625 mSec)
  104. #define TGAP_CONN_EST_SUPERV_TIMEOUT 25 //!< Link Layer connection supervision timeout, when using Connection Establishment proc (n * 10 mSec)
  105. #define TGAP_CONN_EST_LATENCY 26 //!< Link Layer connection slave latency, when using Connection Establishment proc (in number of connection events)
  106. #define TGAP_CONN_EST_MIN_CE_LEN 27 //!< Local informational parameter about min len of connection needed, when using Connection Establishment proc (n * 0.625 mSec)
  107. #define TGAP_CONN_EST_MAX_CE_LEN 28 //!< Local informational parameter about max len of connection needed, when using Connection Establishment proc (n * 0.625 mSec)
  108. #define TGAP_PRIVATE_ADDR_INT 29 //!< Minimum Time Interval between private (resolvable) address changes. In minutes (default 15 minutes)
  109. #define TGAP_CONN_PAUSE_CENTRAL 30 //!< Central idle timer. In seconds (default 1 second)
  110. #define TGAP_CONN_PAUSE_PERIPHERAL 31 //!< Minimum time upon connection establishment before the peripheral starts a connection update procedure. In seconds (default 5 seconds)
  111. // Proprietary
  112. #define TGAP_SM_TIMEOUT 32 //!< SM Message Timeout (milliseconds). Default 30 seconds.
  113. #define TGAP_SM_MIN_KEY_LEN 33 //!< SM Minimum Key Length supported. Default 7.
  114. #define TGAP_SM_MAX_KEY_LEN 34 //!< SM Maximum Key Length supported. Default 16.
  115. #define TGAP_FILTER_ADV_REPORTS 35 //!< Filter duplicate advertising reports. Default TRUE.
  116. #define TGAP_SCAN_RSP_RSSI_MIN 36 //!< Minimum RSSI required for scan responses to be reported to the app. Default -127.
  117. #define TGAP_REJECT_CONN_PARAMS 37 //!< Whether or not to reject Connection Parameter Update Request received on Central device. Default FALSE.
  118. #if !defined ( TESTMODES )
  119. #define TGAP_AUTH_TASK_ID 38 //!< Task ID override for Task Authentication control (for stack internal use only)
  120. #define TGAP_PARAMID_MAX 39 //!< ID MAX-valid Parameter ID
  121. #else
  122. #define TGAP_GAP_TESTCODE 38 //!< GAP TestCodes - puts GAP into a test mode
  123. #define TGAP_SM_TESTCODE 39 //!< SM TestCodes - puts SM into a test mode
  124. #define TGAP_AUTH_TASK_ID 40 //!< Task ID override for Task Authentication control (for stack internal use only)
  125. #define TGAP_PARAMID_MAX 41 //!< ID MAX-valid Parameter ID
  126. #define TGAP_GATT_TESTCODE 100 //!< GATT TestCodes - puts GATT into a test mode (paramValue maintained by GATT)
  127. #define TGAP_ATT_TESTCODE 101 //!< ATT TestCodes - puts ATT into a test mode (paramValue maintained by ATT)
  128. #define TGAP_GGS_TESTCODE 102 //!< GGS TestCodes - puts GGS into a test mode (paramValue maintained by GGS)
  129. #endif
  130. /** @} End GAP_PARAMETER_ID_DEFINES */
  131. /** @defgroup GAP_DEVDISC_MODE_DEFINES GAP Device Discovery Modes
  132. * @{
  133. */
  134. #define DEVDISC_MODE_NONDISCOVERABLE 0x00 //!< No discoverable setting
  135. #define DEVDISC_MODE_GENERAL 0x01 //!< General Discoverable devices
  136. #define DEVDISC_MODE_LIMITED 0x02 //!< Limited Discoverable devices
  137. #define DEVDISC_MODE_ALL 0x03 //!< Not filtered
  138. /** @} End GAP_DEVDISC_MODE_DEFINES */
  139. /** @defgroup GAP_ADDR_TYPE_DEFINES GAP Address Types
  140. * @{
  141. */
  142. #define ADDRTYPE_PUBLIC 0x00 //!< Use the BD_ADDR
  143. #define ADDRTYPE_STATIC 0x01 //!< Static address
  144. #define ADDRTYPE_PRIVATE_NONRESOLVE 0x02 //!< Generate Non-Resolvable Private Address
  145. #define ADDRTYPE_PRIVATE_RESOLVE 0x03 //!< Generate Resolvable Private Address
  146. /** @} End GAP_ADDR_TYPE_DEFINES */
  147. /** @defgroup GAP_ADVERTISEMENT_TYPE_DEFINES GAP Advertising Event Types
  148. * for eventType field in gapAdvertisingParams_t
  149. * @{
  150. */
  151. #define GAP_ADTYPE_ADV_IND 0x00 //!< Connectable undirected advertisement
  152. #define GAP_ADTYPE_ADV_HDC_DIRECT_IND 0x01 //!< Connectable high duty cycle directed advertisement
  153. #define GAP_ADTYPE_ADV_SCAN_IND 0x02 //!< Scannable undirected advertisement
  154. #define GAP_ADTYPE_ADV_NONCONN_IND 0x03 //!< Non-Connectable undirected advertisement
  155. #define GAP_ADTYPE_ADV_LDC_DIRECT_IND 0x04 //!< Connectable low duty cycle directed advertisement
  156. /** @} End GAP_ADVERTISEMENT_TYPE_DEFINES */
  157. /** @defgroup GAP_ADVERTISEMENT_REPORT_TYPE_DEFINES GAP Advertising Report Event Types
  158. * for eventType field in gapDevRec_t and gapDeviceInfoEvent_t
  159. * @{
  160. */
  161. #define GAP_ADRPT_ADV_IND 0x00 //!< Connectable undirected advertisement
  162. #define GAP_ADRPT_ADV_DIRECT_IND 0x01 //!< Connectable directed advertisement
  163. #define GAP_ADRPT_ADV_SCAN_IND 0x02 //!< Scannable undirected advertisement
  164. #define GAP_ADRPT_ADV_NONCONN_IND 0x03 //!< Non-Connectable undirected advertisement
  165. #define GAP_ADRPT_SCAN_RSP 0x04 //!< Scan Response
  166. /** @} End GAP_ADVERTISEMENT_REPORT_TYPE_DEFINES */
  167. /** @defgroup GAP_FILTER_POLICY_DEFINES GAP Advertiser Filter Scan Parameters
  168. * @{
  169. */
  170. #define GAP_FILTER_POLICY_ALL 0x00 //!< Allow Scan Request from Any, Allow Connect Request from Any (default).
  171. #define GAP_FILTER_POLICY_WHITE_SCAN 0x01 //!< Allow Scan Request from White List Only, Allow Connect from Any
  172. #define GAP_FILTER_POLICY_WHITE_CON 0x02 //!< Allow Scan Request from Any, Connect from White List Only
  173. #define GAP_FILTER_POLICY_WHITE 0x03 //!< Allow Scan Request and Connect from White List Only
  174. /** @} End GAP_FILTER_POLICY_DEFINES */
  175. //! Advertiser Channel Map
  176. #define ADV_CHANMAP_SIZE 5
  177. //! Maximum Pairing Passcode/Passkey value. Range of a passkey can be 0 - 999,999.
  178. #define GAP_PASSCODE_MAX 999999
  179. /** Sign Counter Initialized - Sign counter hasn't been used yet. Used when setting up
  180. * a connection's signing information.
  181. */
  182. #define GAP_INIT_SIGN_COUNTER 0xFFFFFFFF
  183. /** @defgroup GAP_ADVCHAN_DEFINES GAP Advertisement Channel Map
  184. * @{
  185. */
  186. #define GAP_ADVCHAN_37 0x01 //!< Advertisement Channel 37
  187. #define GAP_ADVCHAN_38 0x02 //!< Advertisement Channel 38
  188. #define GAP_ADVCHAN_39 0x04 //!< Advertisement Channel 39
  189. #define GAP_ADVCHAN_ALL (GAP_ADVCHAN_37 | GAP_ADVCHAN_38 | GAP_ADVCHAN_39) //!< All Advertisement Channels Enabled
  190. /** @} End GAP_ADVCHAN_DEFINES */
  191. /** @defgroup GAP_WHITELIST_DEFINES GAP White List Options
  192. * @{
  193. */
  194. #define WL_NOTUSED 0x00 //!< White list not used but the advertiser's address in this command is used
  195. #define WL_USED 0x01 //!< White list is used and the advertiser's address in this command is not used.
  196. /** @} End GAP_WHITELIST_DEFINES */
  197. /** @defgroup GAP_ADTYPE_DEFINES GAP Advertisment Data Types
  198. * These are the data type identifiers for the data tokens in the advertisement data field.
  199. * @{
  200. */
  201. #define GAP_ADTYPE_FLAGS 0x01 //!< Discovery Mode: @ref GAP_ADTYPE_FLAGS_MODES
  202. #define GAP_ADTYPE_16BIT_MORE 0x02 //!< Service: More 16-bit UUIDs available
  203. #define GAP_ADTYPE_16BIT_COMPLETE 0x03 //!< Service: Complete list of 16-bit UUIDs
  204. #define GAP_ADTYPE_32BIT_MORE 0x04 //!< Service: More 32-bit UUIDs available
  205. #define GAP_ADTYPE_32BIT_COMPLETE 0x05 //!< Service: Complete list of 32-bit UUIDs
  206. #define GAP_ADTYPE_128BIT_MORE 0x06 //!< Service: More 128-bit UUIDs available
  207. #define GAP_ADTYPE_128BIT_COMPLETE 0x07 //!< Service: Complete list of 128-bit UUIDs
  208. #define GAP_ADTYPE_LOCAL_NAME_SHORT 0x08 //!< Shortened local name
  209. #define GAP_ADTYPE_LOCAL_NAME_COMPLETE 0x09 //!< Complete local name
  210. #define GAP_ADTYPE_POWER_LEVEL 0x0A //!< TX Power Level: 0xXX: -127 to +127 dBm
  211. #define GAP_ADTYPE_OOB_CLASS_OF_DEVICE 0x0D //!< Simple Pairing OOB Tag: Class of device (3 octets)
  212. #define GAP_ADTYPE_OOB_SIMPLE_PAIRING_HASHC 0x0E //!< Simple Pairing OOB Tag: Simple Pairing Hash C (16 octets)
  213. #define GAP_ADTYPE_OOB_SIMPLE_PAIRING_RANDR 0x0F //!< Simple Pairing OOB Tag: Simple Pairing Randomizer R (16 octets)
  214. #define GAP_ADTYPE_SM_TK 0x10 //!< Security Manager TK Value
  215. #define GAP_ADTYPE_SM_OOB_FLAG 0x11 //!< Secutiry Manager OOB Flags
  216. #define GAP_ADTYPE_SLAVE_CONN_INTERVAL_RANGE 0x12 //!< Min and Max values of the connection interval (2 octets Min, 2 octets Max) (0xFFFF indicates no conn interval min or max)
  217. #define GAP_ADTYPE_SIGNED_DATA 0x13 //!< Signed Data field
  218. #define GAP_ADTYPE_SERVICES_LIST_16BIT 0x14 //!< Service Solicitation: list of 16-bit Service UUIDs
  219. #define GAP_ADTYPE_SERVICES_LIST_128BIT 0x15 //!< Service Solicitation: list of 128-bit Service UUIDs
  220. #define GAP_ADTYPE_SERVICE_DATA 0x16 //!< Service Data
  221. #define GAP_ADTYPE_APPEARANCE 0x19 //!< Appearance
  222. #define GAP_ADTYPE_ADVERTISING_INTERVAL 0x1A /**< Advertising Interval. */
  223. #define GAP_ADTYPE_LE_BLUETOOTH_DEVICE_ADDRESS 0x1B /**< LE Bluetooth Device Address. */
  224. #define GAP_ADTYPE_LE_ROLE 0x1C /**< LE Role. */
  225. #define GAP_ADTYPE_SIMPLE_PAIRING_HASH_C256 0x1D /**< Simple Pairing Hash C-256. */
  226. #define GAP_ADTYPE_SIMPLE_PAIRING_RANDOMIZER_R256 0x1E /**< Simple Pairing Randomizer R-256. */
  227. #define GAP_ADTYPE_SERVICE_DATA_32BIT_UUID 0x20 /**< Service Data - 32-bit UUID. */
  228. #define GAP_ADTYPE_SERVICE_DATA_128BIT_UUID 0x21 /**< Service Data - 128-bit UUID. */
  229. #define GAP_ADTYPE_LESC_CONFIRMATION_VALUE 0x22 /**< LE Secure Connections Confirmation Value */
  230. #define GAP_ADTYPE_LESC_RANDOM_VALUE 0x23 /**< LE Secure Connections Random Value */
  231. #define GAP_ADTYPE_URI 0x24 /**< URI */
  232. #define GAP_ADTYPE_3D_INFORMATION_DATA 0x3D /**< 3D Information Data. */
  233. #define GAP_ADTYPE_MANUFACTURER_SPECIFIC 0xFF //!< Manufacturer Specific Data: first 2 octets contain the Company Identifier Code followed by the additional manufacturer specific data
  234. /** @} End GAP_ADTYPE_DEFINES */
  235. /** @defgroup GAP_ADTYPE_FLAGS_MODES GAP ADTYPE Flags Discovery Modes
  236. * @{
  237. */
  238. #define GAP_ADTYPE_FLAGS_LIMITED 0x01 //!< Discovery Mode: LE Limited Discoverable Mode
  239. #define GAP_ADTYPE_FLAGS_GENERAL 0x02 //!< Discovery Mode: LE General Discoverable Mode
  240. #define GAP_ADTYPE_FLAGS_BREDR_NOT_SUPPORTED 0x04 //!< Discovery Mode: BR/EDR Not Supported
  241. /** @} End GAP_ADTYPE_FLAGS_MODES */
  242. /** @defgroup GAP_APPEARANCE_VALUES GAP Appearance Values
  243. * @{
  244. */
  245. #define GAP_APPEARE_UNKNOWN 0x0000 //!< Unknown
  246. #define GAP_APPEARE_GENERIC_PHONE 0x0040 //!< Generic Phone
  247. #define GAP_APPEARE_GENERIC_COMPUTER 0x0080 //!< Generic Computer
  248. #define GAP_APPEARE_GENERIC_WATCH 0x00C0 //!< Generic Watch
  249. #define GAP_APPEARE_WATCH_SPORTS 0x00C1 //!< Watch: Sports Watch
  250. #define GAP_APPEARE_GENERIC_CLOCK 0x0100 //!< Generic Clock
  251. #define GAP_APPEARE_GENERIC_DISPLAY 0x0140 //!< Generic Display
  252. #define GAP_APPEARE_GENERIC_RC 0x0180 //!< Generic Remote Control
  253. #define GAP_APPEARE_GENERIC_EYE_GALSSES 0x01C0 //!< Generic Eye-glasses
  254. #define GAP_APPEARE_GENERIC_TAG 0x0200 //!< Generic Tag
  255. #define GAP_APPEARE_GENERIC_KEYRING 0x0240 //!< Generic Keyring
  256. #define GAP_APPEARE_GENERIC_MEDIA_PLAYER 0x0280 //!< Generic Media Player
  257. #define GAP_APPEARE_GENERIC_BARCODE_SCANNER 0x02C0 //!< Generic Barcode Scanner
  258. #define GAP_APPEARE_GENERIC_THERMOMETER 0x0300 //!< Generic Thermometer
  259. #define GAP_APPEARE_GENERIC_THERMO_EAR 0x0301 //!< Thermometer: Ear
  260. #define GAP_APPEARE_GENERIC_HR_SENSOR 0x0340 //!< Generic Heart rate Sensor
  261. #define GAP_APPEARE_GENERIC_HRS_BELT 0x0341 //!< Heart Rate Sensor: Heart Rate Belt
  262. #define GAP_APPEARE_GENERIC_BLOOD_PRESSURE 0x0380 //!< Generic Blood Pressure
  263. #define GAP_APPEARE_GENERIC_BP_ARM 0x0381 //!< Blood Pressure: Arm
  264. #define GAP_APPEARE_GENERIC_BP_WRIST 0x0382 //!< Blood Pressure: Wrist
  265. #define GAP_APPEARE_GENERIC_HID 0x03C0 //!< Generic Human Interface Device (HID)
  266. #define GAP_APPEARE_HID_KEYBOARD 0x03C1 //!< HID Keyboard
  267. #define GAP_APPEARE_HID_MOUSE 0x03C2 //!< HID Mouse
  268. #define GAP_APPEARE_HID_JOYSTIC 0x03C3 //!< HID Joystick
  269. #define GAP_APPEARE_HID_GAMEPAD 0x03C4 //!< HID Gamepad
  270. #define GAP_APPEARE_HID_DIGITIZER_TYABLET 0x03C5 //!< HID Digitizer Tablet
  271. #define GAP_APPEARE_HID_DIGITAL_CARDREADER 0x03C6 //!< HID Card Reader
  272. #define GAP_APPEARE_HID_DIGITAL_PEN 0x03C7 //!< HID Digital Pen
  273. #define GAP_APPEARE_HID_BARCODE_SCANNER 0x03C8 //!< HID Barcode Scanner
  274. /** @} End GAP_APPEARANCE_VALUES */
  275. /*-------------------------------------------------------------------
  276. * TYPEDEFS - Initialization and Configuration
  277. */
  278. /**
  279. * GAP Parameters IDs: @ref GAP_PARAMETER_ID_DEFINES
  280. */
  281. typedef uint16 gapParamIDs_t;
  282. /**
  283. * GAP event header format.
  284. */
  285. typedef struct
  286. {
  287. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  288. uint8 opcode; //!< GAP type of command. Ref: @ref GAP_MSG_EVENT_DEFINES
  289. } gapEventHdr_t;
  290. /**
  291. * GAP_RANDOM_ADDR_CHANGED_EVENT message format. This message is sent to the
  292. * app when the random address changes.
  293. */
  294. typedef struct
  295. {
  296. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  297. uint8 opcode; //!< GAP_RANDOM_ADDR_CHANGED_EVENT
  298. uint8 addrType; //!< Address type: @ref GAP_ADDR_TYPE_DEFINES
  299. uint8 newRandomAddr[B_ADDR_LEN]; //!< the new calculated private addr
  300. } gapRandomAddrEvent_t;
  301. /**
  302. * Connection parameters for the peripheral device. These numbers are used
  303. * to compare against connection events and request connection parameter
  304. * updates with the master.
  305. */
  306. typedef struct
  307. {
  308. /** Minimum value for the connection event (interval. 0x0006 - 0x0C80 * 1.25 ms) */
  309. uint16 intervalMin;
  310. /** Maximum value for the connection event (interval. 0x0006 - 0x0C80 * 1.25 ms) */
  311. uint16 intervalMax;
  312. /** Number of LL latency connection events (0x0000 - 0x03e8) */
  313. uint16 latency;
  314. /** Connection Timeout (0x000A - 0x0C80 * 10 ms) */
  315. uint16 timeout;
  316. } gapPeriConnectParams_t;
  317. /**
  318. * GAP_DEVICE_INIT_DONE_EVENT message format. This message is sent to the
  319. * app when the Device Initialization is done [initiated by calling
  320. * GAP_DeviceInit()].
  321. */
  322. typedef struct
  323. {
  324. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  325. uint8 opcode; //!< GAP_DEVICE_INIT_DONE_EVENT
  326. uint8 devAddr[B_ADDR_LEN]; //!< Device's BD_ADDR
  327. uint16 dataPktLen; //!< HC_LE_Data_Packet_Length
  328. uint8 numDataPkts; //!< HC_Total_Num_LE_Data_Packets
  329. } gapDeviceInitDoneEvent_t;
  330. /**
  331. * GAP_SIGNATURE_UPDATED_EVENT message format. This message is sent to the
  332. * app when the signature counter has changed. This message is to inform the
  333. * application in case it wants to save it to be restored on reboot or reconnect.
  334. * This message is sent to update a connection's signature counter and to update
  335. * this device's signature counter. If devAddr == BD_ADDR, then this message pertains
  336. * to this device.
  337. */
  338. typedef struct
  339. {
  340. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  341. uint8 opcode; //!< GAP_SIGNATURE_UPDATED_EVENT
  342. uint8 addrType; //!< Device's address type for devAddr
  343. uint8 devAddr[B_ADDR_LEN]; //!< Device's BD_ADDR, could be own address
  344. uint32 signCounter; //!< new Signed Counter
  345. } gapSignUpdateEvent_t;
  346. /**
  347. * GAP_DEVICE_INFO_EVENT message format. This message is sent to the
  348. * app during a Device Discovery Request, when a new advertisement or scan
  349. * response is received.
  350. */
  351. typedef struct
  352. {
  353. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  354. uint8 opcode; //!< GAP_DEVICE_INFO_EVENT
  355. uint8 eventType; //!< Advertisement Type: @ref GAP_ADVERTISEMENT_REPORT_TYPE_DEFINES
  356. uint8 addrType; //!< address type: @ref GAP_ADDR_TYPE_DEFINES
  357. uint8 addr[B_ADDR_LEN]; //!< Address of the advertisement or SCAN_RSP
  358. int8 rssi; //!< Advertisement or SCAN_RSP RSSI
  359. uint8 dataLen; //!< Length (in bytes) of the data field (evtData)
  360. uint8 *pEvtData; //!< Data field of advertisement or SCAN_RSP
  361. } gapDeviceInfoEvent_t;
  362. /*-------------------------------------------------------------------
  363. * TYPEDEFS - Device Discovery
  364. */
  365. /**
  366. * Type of device discovery (Scan) to perform.
  367. */
  368. typedef struct
  369. {
  370. uint8 taskID; //!< Requesting App's Task ID, used to return results
  371. uint8 mode; //!< Discovery Mode: @ref GAP_DEVDISC_MODE_DEFINES
  372. uint8 activeScan; //!< TRUE for active scanning
  373. uint8 whiteList; //!< TRUE to only allow advertisements from devices in the white list.
  374. } gapDevDiscReq_t;
  375. /**
  376. * Type of device discovery (Scan) to perform.
  377. */
  378. typedef struct
  379. {
  380. uint8 eventType; //!< Indicates advertising event type used by the advertiser: @ref GAP_ADVERTISEMENT_REPORT_TYPE_DEFINES
  381. uint8 addrType; //!< Address Type: @ref GAP_ADDR_TYPE_DEFINES
  382. uint8 addr[B_ADDR_LEN]; //!< Device's Address
  383. } gapDevRec_t;
  384. /**
  385. * GAP_DEVICE_DISCOVERY_EVENT message format. This message is sent to the
  386. * Application after a scan is performed.
  387. */
  388. typedef struct
  389. {
  390. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  391. uint8 opcode; //!< GAP_DEVICE_DISCOVERY_EVENT
  392. uint8 numDevs; //!< Number of devices found during scan
  393. gapDevRec_t *pDevList; //!< array of device records
  394. } gapDevDiscEvent_t;
  395. /**
  396. * Advertising Parameters
  397. */
  398. typedef struct
  399. {
  400. uint8 eventType; //!< Advertise Event Type: @ref GAP_ADVERTISEMENT_TYPE_DEFINES
  401. uint8 initiatorAddrType; //!< Initiator's address type: @ref GAP_ADDR_TYPE_DEFINES
  402. uint8 initiatorAddr[B_ADDR_LEN]; //!< Initiator's addr - used only with connectable directed eventType (ADV_EVTTYPE_CONNECTABLE_DIRECTED).
  403. uint8 channelMap; //!< Channel Map: Bit mask @ref GAP_ADVCHAN_DEFINES
  404. uint8 filterPolicy; //!< Filer Policy: @ref GAP_FILTER_POLICY_DEFINES. Ignored when directed advertising is used.
  405. } gapAdvertisingParams_t;
  406. /**
  407. * GAP_MAKE_DISCOVERABLE_DONE_EVENT message format. This message is sent to the
  408. * app when the Advertise config is complete.
  409. */
  410. typedef struct
  411. {
  412. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  413. uint8 opcode; //!< GAP_MAKE_DISCOVERABLE_DONE_EVENT
  414. uint16 interval; //!< actual advertising interval selected by controller
  415. } gapMakeDiscoverableRspEvent_t;
  416. /**
  417. * GAP_END_DISCOVERABLE_DONE_EVENT message format. This message is sent to the
  418. * app when the Advertising has stopped.
  419. */
  420. typedef struct
  421. {
  422. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  423. uint8 opcode; //!< GAP_END_DISCOVERABLE_DONE_EVENT
  424. } gapEndDiscoverableRspEvent_t;
  425. /**
  426. * GAP_ADV_DATA_UPDATE_DONE_EVENT message format. This message is sent to the
  427. * app when Advertising Data Update is complete.
  428. */
  429. typedef struct
  430. {
  431. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  432. uint8 opcode; //!< GAP_ADV_DATA_UPDATE_DONE_EVENT
  433. uint8 adType; //!< TRUE if advertising data, FALSE if SCAN_RSP
  434. } gapAdvDataUpdateEvent_t;
  435. /*-------------------------------------------------------------------
  436. * TYPEDEFS - Link Establishment
  437. */
  438. /**
  439. * Establish Link Request parameters
  440. */
  441. typedef struct
  442. {
  443. uint8 taskID; //!< Requesting App/Profile's Task ID
  444. uint8 highDutyCycle; //!< TRUE to high duty cycle scan, FALSE if not.
  445. uint8 whiteList; //!< Determines use of the white list: @ref GAP_WHITELIST_DEFINES
  446. uint8 addrTypePeer; //!< Address type of the advertiser: @ref GAP_ADDR_TYPE_DEFINES
  447. uint8 peerAddr[B_ADDR_LEN]; //!< Advertiser's address
  448. } gapEstLinkReq_t;
  449. /**
  450. * Update Link Parameters Request parameters
  451. */
  452. typedef struct
  453. {
  454. uint16 connectionHandle; //!< Connection handle of the update
  455. uint16 intervalMin; //!< Minimum Connection Interval
  456. uint16 intervalMax; //!< Maximum Connection Interval
  457. uint16 connLatency; //!< Connection Latency
  458. uint16 connTimeout; //!< Connection Timeout
  459. } gapUpdateLinkParamReq_t;
  460. /**
  461. * GAP_LINK_ESTABLISHED_EVENT message format. This message is sent to the app
  462. * when the link request is complete.<BR>
  463. * <BR>
  464. * For an Observer, this message is sent to complete the Establish Link Request.<BR>
  465. * For a Peripheral, this message is sent to indicate that a link has been created.
  466. */
  467. typedef struct
  468. {
  469. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  470. uint8 opcode; //!< GAP_LINK_ESTABLISHED_EVENT
  471. uint8 devAddrType; //!< Device address type: @ref GAP_ADDR_TYPE_DEFINES
  472. uint8 devAddr[B_ADDR_LEN]; //!< Device address of link
  473. uint16 connectionHandle; //!< Connection Handle from controller used to ref the device
  474. uint16 connInterval; //!< Connection Interval
  475. uint16 connLatency; //!< Conenction Latency
  476. uint16 connTimeout; //!< Connection Timeout
  477. uint8 clockAccuracy; //!< Clock Accuracy
  478. } gapEstLinkReqEvent_t;
  479. /**
  480. * GAP_LINK_PARAM_UPDATE_EVENT message format. This message is sent to the app
  481. * when the connection parameters update request is complete.
  482. */
  483. typedef struct
  484. {
  485. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  486. uint8 opcode; //!< GAP_LINK_PARAM_UPDATE_EVENT
  487. uint8 status; //!< bStatus_t
  488. uint16 connectionHandle; //!< Connection handle of the update
  489. uint16 connInterval; //!< Requested connection interval
  490. uint16 connLatency; //!< Requested connection latency
  491. uint16 connTimeout; //!< Requested connection timeout
  492. } gapLinkUpdateEvent_t;
  493. /**
  494. * GAP_LINK_TERMINATED_EVENT message format. This message is sent to the
  495. * app when a link to a device is terminated.
  496. */
  497. typedef struct
  498. {
  499. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  500. uint8 opcode; //!< GAP_LINK_TERMINATED_EVENT
  501. uint16 connectionHandle; //!< connection Handle
  502. uint8 reason; //!< termination reason from LL
  503. } gapTerminateLinkEvent_t;
  504. /*-------------------------------------------------------------------
  505. * TYPEDEFS - Authentication, Bounding and Pairing
  506. */
  507. /**
  508. * GAP_PASSKEY_NEEDED_EVENT message format. This message is sent to the
  509. * app when a Passkey is needed from the app's user interface.
  510. */
  511. typedef struct
  512. {
  513. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  514. uint8 opcode; //!< GAP_PASSKEY_NEEDED_EVENT
  515. uint8 deviceAddr[B_ADDR_LEN]; //!< address of device to pair with, and could be either public or random.
  516. uint16 connectionHandle; //!< Connection handle
  517. uint8 uiInputs; //!< Pairing User Interface Inputs - Ask user to input passcode
  518. uint8 uiOutputs; //!< Pairing User Interface Outputs - Display passcode
  519. } gapPasskeyNeededEvent_t;
  520. /**
  521. * GAP_AUTHENTICATION_COMPLETE_EVENT message format. This message is sent to the app
  522. * when the authentication request is complete.
  523. */
  524. typedef struct
  525. {
  526. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  527. uint8 opcode; //!< GAP_AUTHENTICATION_COMPLETE_EVENT
  528. uint16 connectionHandle; //!< Connection Handle from controller used to ref the device
  529. uint8 authState; //!< TRUE if the pairing was authenticated (MITM)
  530. smSecurityInfo_t *pSecurityInfo; //!< BOUND - security information from this device
  531. smSigningInfo_t *pSigningInfo; //!< Signing information
  532. smSecurityInfo_t *pDevSecInfo; //!< BOUND - security information from connected device
  533. smIdentityInfo_t *pIdentityInfo; //!< BOUND - identity information
  534. } gapAuthCompleteEvent_t;
  535. /**
  536. * securityInfo and identityInfo are only used if secReqs.bondable == BOUND, which means that
  537. * the device is already bound and we should use the security information and keys.
  538. */
  539. typedef struct
  540. {
  541. uint16 connectionHandle; //!< Connection Handle from controller,
  542. smLinkSecurityReq_t secReqs; //!< Pairing Control info
  543. } gapAuthParams_t;
  544. /**
  545. * GAP_SLAVE_REQUESTED_SECURITY_EVENT message format. This message is sent to the app
  546. * when a Slave Security Request is received.
  547. */
  548. typedef struct
  549. {
  550. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  551. uint8 opcode; //!< GAP_SLAVE_REQUESTED_SECURITY_EVENT
  552. uint16 connectionHandle; //!< Connection Handle
  553. uint8 deviceAddr[B_ADDR_LEN]; //!< address of device requesting security
  554. uint8 authReq; //!< Authentication Requirements: Bit 2: MITM, Bits 0-1: bonding (0 - no bonding, 1 - bonding)
  555. } gapSlaveSecurityReqEvent_t;
  556. /**
  557. * GAP_BOND_COMPLETE_EVENT message format. This message is sent to the
  558. * app when a bonding is complete. This means that a key is loaded and the link is encrypted.
  559. */
  560. typedef struct
  561. {
  562. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  563. uint8 opcode; //!< GAP_BOND_COMPLETE_EVENT
  564. uint16 connectionHandle; //!< connection Handle
  565. } gapBondCompleteEvent_t;
  566. /**
  567. * Pairing Request fields - the parsed fields of the SMP Pairing Request command.
  568. */
  569. typedef struct
  570. {
  571. uint8 ioCap; //!< Pairing Request ioCap field
  572. uint8 oobDataFlag; //!< Pairing Request OOB Data Flag field
  573. uint8 authReq; //!< Pairing Request Auth Req field
  574. uint8 maxEncKeySize; //!< Pairing Request Maximum Encryption Key Size field
  575. keyDist_t keyDist; //!< Pairing Request Key Distribution field
  576. } gapPairingReq_t;
  577. /**
  578. * GAP_PAIRING_REQ_EVENT message format.<BR>
  579. * <BR>
  580. * This message is sent to the
  581. * app when an unexpected Pairing Request is received. The application is
  582. * expected to setup for a Security Manager pairing/bonding.<BR>
  583. * <BR>
  584. * To setup an SM Pairing, the application should call GAP_Authenticate() with these "pairReq" fields.<BR>
  585. * <BR>
  586. * NOTE: This message should only be sent to peripheral devices.
  587. */
  588. typedef struct
  589. {
  590. osal_event_hdr_t hdr; //!< GAP_MSG_EVENT and status
  591. uint8 opcode; //!< GAP_PAIRING_REQ_EVENT
  592. uint16 connectionHandle; //!< connection Handle
  593. gapPairingReq_t pairReq; //!< The Pairing Request fields received.
  594. } gapPairingReqEvent_t;
  595. /**
  596. * GAP Advertisement/Scan Response Data Token - These data items are stored as low byte first (OTA
  597. * format). The data space for these items are passed in and maintained by
  598. * the calling application
  599. */
  600. typedef struct
  601. {
  602. uint8 adType; //!< ADTYPE value: @ref GAP_ADTYPE_DEFINES
  603. uint8 attrLen; //!< Number of bytes in the attribute data
  604. uint8 *pAttrData; //!< pointer to Attribute data
  605. } gapAdvDataToken_t;
  606. /** @} End BLE_GAP_DEFINES */
  607. /*-------------------------------------------------------------------
  608. * GLOBAL VARIABLES
  609. */
  610. /**
  611. * @defgroup GAP_API GAP API Functions
  612. *
  613. * @{
  614. */
  615. /*-------------------------------------------------------------------
  616. * FUNCTIONS - Initialization and Configuation
  617. */
  618. /**
  619. * @brief Called to setup the device. Call just once on initialization.
  620. *
  621. * NOTE: When initialization is complete, the calling app will be
  622. * sent the GAP_DEVICE_INIT_DONE_EVENT
  623. *
  624. * @param taskID - Default task ID to send events.
  625. * @param profileRole - GAP Profile Roles: @ref GAP_PROFILE_ROLE_DEFINES
  626. * @param maxScanResponses - maximum number to scan responses
  627. * we can receive during a device discovery.
  628. * @param pIRK - pointer to Identity Root Key, NULLKEY (all zeroes) if the app
  629. * wants the GAP to generate the key.
  630. * @param pSRK - pointer to Sign Resolving Key, NULLKEY if the app
  631. * wants the GAP to generate the key.
  632. * @param pSignCounter - 32 bit value used in the SM Signing
  633. * algorithm that shall be initialized to zero and incremented
  634. * with every new signing. This variable must also be maintained
  635. * by the application.
  636. *
  637. * @return SUCCESS - Processing, expect GAP_DEVICE_INIT_DONE_EVENT, <BR>
  638. * INVALIDPARAMETER - for invalid profile role or role combination, <BR>
  639. * bleIncorrectMode - trouble communicating with HCI
  640. */
  641. extern bStatus_t GAP_DeviceInit( uint8 taskID,
  642. uint8 profileRole,
  643. uint8 maxScanResponses,
  644. uint8 *pIRK,
  645. uint8 *pSRK,
  646. uint32 *pSignCounter );
  647. /**
  648. * @brief Called to setup a GAP Advertisement/Scan Response data token.
  649. *
  650. * NOTE: The data in these items are stored as low byte first (OTA format).
  651. * The passed in structure "token" should be allocated by the calling app/profile
  652. * and not released until after calling GAP_RemoveAdvToken().
  653. *
  654. * @param pToken - Advertisement/Scan response token to write.
  655. *
  656. * @return SUCCESS - advertisement token added to the GAP list <BR>
  657. * INVALIDPARAMETER - Invalid Advertisement Type or pAttrData is NULL <BR>
  658. * INVALID_MEM_SIZE - The tokens take up too much space and don't fit into Advertisment data and Scan Response Data<BR>
  659. * bleInvalidRange - token ID already exists.<BR>
  660. * bleIncorrectMode - not a peripheral device<BR>
  661. * bleMemAllocError - memory allocation failure,
  662. */
  663. extern bStatus_t GAP_SetAdvToken( gapAdvDataToken_t *pToken );
  664. /**
  665. * @brief Called to read a GAP Advertisement/Scan Response data token.
  666. *
  667. * @param adType - Advertisement type to get
  668. *
  669. * @return pointer to the advertisement data token structure, NULL if not found.
  670. */
  671. extern gapAdvDataToken_t *GAP_GetAdvToken( uint8 adType );
  672. /**
  673. * @brief Called to remove a GAP Advertisement/Scan Response data token.
  674. *
  675. * @param adType - Advertisement type to remove
  676. *
  677. * @return pointer to the token structure removed from the GAP ADType list
  678. * NULL if the requested adType wasn't found.
  679. */
  680. extern gapAdvDataToken_t *GAP_RemoveAdvToken( uint8 adType );
  681. /**
  682. * @brief Called to rebuild and load Advertisement and Scan Response data from existing
  683. * GAP Advertisement Tokens.
  684. *
  685. * @return SUCCESS or bleIncorrectMode
  686. */
  687. extern bStatus_t GAP_UpdateAdvTokens( void );
  688. /**
  689. * @brief Set a GAP Parameter value. Use this function to change
  690. * the default GAP parameter values.
  691. *
  692. * @param paramID - parameter ID: @ref GAP_PARAMETER_ID_DEFINES
  693. * @param paramValue - new param value
  694. *
  695. * @return SUCCESS or INVALIDPARAMETER (invalid paramID)
  696. */
  697. extern bStatus_t GAP_SetParamValue( gapParamIDs_t paramID, uint16 paramValue );
  698. /**
  699. * @brief Get a GAP Parameter value.
  700. *
  701. * @param paramID - parameter ID: @ref GAP_PARAMETER_ID_DEFINES
  702. *
  703. * @return GAP Parameter value or 0xFFFF if invalid
  704. */
  705. extern uint16 GAP_GetParamValue( gapParamIDs_t paramID );
  706. /**
  707. * @brief Setup the device's address type. If ADDRTYPE_PRIVATE_RESOLVE
  708. * is selected, the address will change periodically.
  709. *
  710. * @param addrType - @ref GAP_ADDR_TYPE_DEFINES
  711. * @param pStaticAddr - Only used with ADDRTYPE_STATIC
  712. * or ADDRTYPE_PRIVATE_NONRESOLVE type.<BR>
  713. * NULL to auto generate otherwise the application
  714. * can specify the address value
  715. *
  716. * @return SUCCESS: address type updated,<BR>
  717. * bleNotReady: Can't be called until GAP_DeviceInit() is called
  718. * and the init process is completed,<BR>
  719. * bleIncorrectMode: can't change with an active connection,<BR>
  720. * or INVALIDPARAMETER.<BR>
  721. *
  722. * If return value isn't SUCCESS, the address type remains
  723. * the same as before this call.
  724. */
  725. extern bStatus_t GAP_ConfigDeviceAddr( uint8 addrType, uint8 *pStaticAddr );
  726. /**
  727. * @brief Register your task ID to receive extra (unwanted)
  728. * HCI status and complete events.
  729. *
  730. * @param taskID - Default task ID to send events.
  731. *
  732. * @return none
  733. */
  734. extern void GAP_RegisterForHCIMsgs( uint8 taskID );
  735. /*-------------------------------------------------------------------
  736. * FUNCTIONS - Device Discovery
  737. */
  738. /**
  739. * @brief Start a device discovery scan.
  740. *
  741. * @param pParams - Device Discovery parameters
  742. *
  743. * @return SUCCESS: scan started,<BR>
  744. * bleIncorrectMode: invalid profile role,<BR>
  745. * bleAlreadyInRequestedMode: not available<BR>
  746. */
  747. extern bStatus_t GAP_DeviceDiscoveryRequest( gapDevDiscReq_t *pParams );
  748. /**
  749. * @brief Cancel an existing device discovery request.
  750. *
  751. * @param taskID - used to return GAP_DEVICE_DISCOVERY_EVENT
  752. *
  753. * @return SUCCESS: cancel started,<BR>
  754. * bleInvalidTaskID: Not the task that started discovery,<BR>
  755. * bleIncorrectMode: not in discovery mode<BR>
  756. */
  757. extern bStatus_t GAP_DeviceDiscoveryCancel( uint8 taskID );
  758. /**
  759. * @brief Setup or change advertising. Also starts advertising.
  760. *
  761. * @param taskID - used to return GAP_DISCOVERABLE_RESPONSE_EVENT
  762. * @param pParams - advertising parameters
  763. *
  764. * @return SUCCESS: advertising started,<BR>
  765. * bleIncorrectMode: invalid profile role,<BR>
  766. * bleAlreadyInRequestedMode: not available at this time,<BR>
  767. * bleNotReady: advertising data isn't set up yet.<BR>
  768. */
  769. extern bStatus_t GAP_MakeDiscoverable( uint8 taskID, gapAdvertisingParams_t *pParams );
  770. /**
  771. * @brief Setup or change advertising and scan response data.
  772. *
  773. * NOTE: if the return status from this function is SUCCESS,
  774. * the task isn't complete until the GAP_ADV_DATA_UPDATE_DONE_EVENT
  775. * is sent to the calling application task.
  776. *
  777. * @param taskID - task ID of the app requesting the change
  778. * @param adType - TRUE - advertisement data, FALSE - scan response data
  779. * @param dataLen - Octet length of advertData
  780. * @param pAdvertData - advertising or scan response data
  781. *
  782. * @return SUCCESS: data accepted,<BR>
  783. * bleIncorrectMode: invalid profile role,<BR>
  784. */
  785. extern bStatus_t GAP_UpdateAdvertisingData( uint8 taskID, uint8 adType,
  786. uint8 dataLen, uint8 *pAdvertData );
  787. /**
  788. * @brief Stops advertising.
  789. *
  790. * @param taskID - of task that called GAP_MakeDiscoverable
  791. *
  792. * @return SUCCESS: stopping discoverable mode,<BR>
  793. * bleIncorrectMode: not in discoverable mode,<BR>
  794. * bleInvalidTaskID: not correct task<BR>
  795. */
  796. extern bStatus_t GAP_EndDiscoverable( uint8 taskID );
  797. /**
  798. * @brief Resolves a private address against an IRK.
  799. *
  800. * @param pIRK - pointer to the IRK
  801. * @param pAddr - pointer to the Resovable Private address
  802. *
  803. * @return SUCCESS: match,<BR>
  804. * FAILURE: don't match,<BR>
  805. * INVALIDPARAMETER: parameters invalid<BR>
  806. */
  807. extern bStatus_t GAP_ResolvePrivateAddr( uint8 *pIRK, uint8 *pAddr );
  808. /*-------------------------------------------------------------------
  809. * FUNCTIONS - Link Establishment
  810. */
  811. /**
  812. * @brief Establish a link to a slave device.
  813. *
  814. * @param pParams - link establishment parameters
  815. *
  816. * @return SUCCESS: started establish link process,<BR>
  817. * bleIncorrectMode: invalid profile role,<BR>
  818. * bleNotReady: a scan is in progress,<BR>
  819. * bleAlreadyInRequestedMode: can’t process now,<BR>
  820. * bleNoResources: Too many links<BR>
  821. */
  822. extern bStatus_t GAP_EstablishLinkReq( gapEstLinkReq_t *pParams );
  823. /**
  824. * @brief Terminate a link connection.
  825. *
  826. * @param taskID - requesting app's task id.
  827. * @param connectionHandle - connection handle of link to terminate
  828. * or @ref GAP_CONN_HANDLE_DEFINES
  829. * @param reason - terminate reason.
  830. *
  831. * @return SUCCESS: Terminate started,<BR>
  832. * bleIncorrectMode: No Link to terminate,<BR>
  833. * bleInvalidTaskID: not app that established link<BR>
  834. */
  835. extern bStatus_t GAP_TerminateLinkReq( uint8 taskID, uint16 connectionHandle, uint8 reason );
  836. /**
  837. * @brief Update the link parameters to a slave device.
  838. *
  839. * @param pParams - link update parameters
  840. *
  841. * @return SUCCESS: started update link process,<BR
  842. * INVALIDPARAMETER: one of the parameters were invalid,<BR>
  843. * bleIncorrectMode: invalid profile role,<BR>
  844. * bleNotConnected: not in a connection<BR>
  845. */
  846. extern bStatus_t GAP_UpdateLinkParamReq( gapUpdateLinkParamReq_t *pParams );
  847. /**
  848. * @brief Returns the number of active connections.
  849. *
  850. * @return Number of active connections.
  851. */
  852. extern uint8 GAP_NumActiveConnections( void );
  853. /*-------------------------------------------------------------------
  854. * FUNCTIONS - Pairing
  855. */
  856. /**
  857. * @brief Start the Authentication process with the requested device.
  858. * This function is used to Initiate/Allow pairing.
  859. * Called by both master and slave device (Central and Peripheral).
  860. *
  861. * NOTE: This function is called after the link is established.
  862. *
  863. * @param pParams - Authentication parameters
  864. * @param pPairReq - Enter these parameters if the Pairing Request was already received.
  865. * NULL, if waiting for Pairing Request or if initiating.
  866. *
  867. * @return SUCCESS,<BR>
  868. * bleIncorrectMode: Not correct profile role,<BR>
  869. * INVALIDPARAMETER, <BR>
  870. * bleNotConnected,<BR>
  871. * bleAlreadyInRequestedMode,<BR>
  872. * FAILURE - not workable.<BR>
  873. */
  874. extern bStatus_t GAP_Authenticate( gapAuthParams_t *pParams, gapPairingReq_t *pPairReq );
  875. /**
  876. * @brief Send a Pairing Failed message and end any existing pairing.
  877. *
  878. * @param connectionHandle - connection handle.
  879. * @param reason - Pairing Failed reason code.
  880. *
  881. * @return SUCCESS - function was successful,<BR>
  882. * bleMemAllocError - memory allocation error,<BR>
  883. * INVALIDPARAMETER - one of the parameters were invalid,<BR>
  884. * bleNotConnected - link not found,<BR>
  885. * bleInvalidRange - one of the parameters were not within range.
  886. */
  887. extern bStatus_t GAP_TerminateAuth( uint16 connectionHandle, uint8 reason );
  888. /**
  889. * @brief Update the passkey in string format. This function is called by the
  890. * application/profile in response to receiving the
  891. * GAP_PASSKEY_NEEDED_EVENT message.
  892. *
  893. * NOTE: This function is the same as GAP_PasscodeUpdate(), except that
  894. * the passkey is passed in as a string format.
  895. *
  896. * @param pPasskey - new passkey - pointer to numeric string (ie. "019655" ).
  897. * This string's range is "000000" to "999999".
  898. * @param connectionHandle - connection handle.
  899. *
  900. * @return SUCCESS: will start pairing with this entry,<BR>
  901. * bleIncorrectMode: Link not found,<BR>
  902. * INVALIDPARAMETER: passkey == NULL or passkey isn't formatted properly.<BR>
  903. */
  904. extern bStatus_t GAP_PasskeyUpdate( uint8 *pPasskey, uint16 connectionHandle );
  905. /**
  906. * @brief Update the passkey in a numeric value (not string).
  907. * This function is called by the application/profile in response
  908. * to receiving the GAP_PASSKEY_NEEDED_EVENT message.
  909. *
  910. * NOTE: This function is the same as GAP_PasskeyUpdate(), except that
  911. * the passkey is passed in as a non-string format.
  912. *
  913. * @param passcode - not string - range: 0 - 999,999.
  914. * @param connectionHandle - connection handle.
  915. *
  916. * @return SUCCESS: will start pairing with this entry,<BR>
  917. * bleIncorrectMode: Link not found,<BR>
  918. * INVALIDPARAMETER: passkey == NULL or passkey isn't formatted properly.<BR>
  919. */
  920. extern bStatus_t GAP_PasscodeUpdate( uint32 passcode, uint16 connectionHandle );
  921. /**
  922. * @brief Generate a Slave Requested Security message to the master.
  923. *
  924. * @param connectionHandle - connection handle.
  925. * @param authReq - Authentication Requirements: Bit 2: MITM, Bits 0-1: bonding (0 - no bonding, 1 - bonding)
  926. *
  927. * @return SUCCESS: will send,<BR>
  928. * bleNotConnected: Link not found,<BR>
  929. * bleIncorrectMode: wrong GAP role, must be a Peripheral Role<BR>
  930. */
  931. extern bStatus_t GAP_SendSlaveSecurityRequest( uint16 connectionHandle, uint8 authReq );
  932. /**
  933. * @brief Set up the connection to accept signed data.
  934. *
  935. * NOTE: This function is called after the link is established.
  936. *
  937. * @param connectionHandle - connection handle of the signing information
  938. * @param authenticated - TRUE if the signing information is authenticated, FALSE otherwise
  939. * @param pParams - signing parameters
  940. *
  941. * @return SUCCESS, <BR>
  942. * bleIncorrectMode: Not correct profile role,<BR>
  943. * INVALIDPARAMETER, <BR>
  944. * bleNotConnected,<BR>
  945. * FAILURE: not workable.<BR>
  946. */
  947. extern bStatus_t GAP_Signable( uint16 connectionHandle, uint8 authenticated, smSigningInfo_t *pParams );
  948. /**
  949. * @brief Set up the connection's bound paramaters.
  950. *
  951. * NOTE: This function is called after the link is established.
  952. *
  953. * @param connectionHandle - connection handle of the signing information
  954. * @param authenticated - this connection was previously authenticated
  955. * @param pParams - the connected device's security parameters
  956. * @param startEncryption - whether or not to start encryption
  957. *
  958. * @return SUCCESS, <BR>
  959. * bleIncorrectMode: Not correct profile role,<BR>
  960. * INVALIDPARAMETER, <BR>
  961. * bleNotConnected,<BR>
  962. * FAILURE: not workable.<BR>
  963. */
  964. extern bStatus_t GAP_Bond( uint16 connectionHandle, uint8 authenticated,
  965. smSecurityInfo_t *pParams, uint8 startEncryption );
  966. /**
  967. * @} End GAP_API
  968. */
  969. /*-------------------------------------------------------------------
  970. * Internal API - These functions are only called from gap.c module.
  971. */
  972. /**
  973. * @internal
  974. *
  975. * @brief Setup the device configuration parameters.
  976. *
  977. * @param taskID - Default task ID to send events.
  978. * @param profileRole - GAP Profile Roles
  979. *
  980. * @return SUCCESS or bleIncorrectMode
  981. */
  982. extern bStatus_t GAP_ParamsInit( uint8 taskID, uint8 profileRole );
  983. /**
  984. * @internal
  985. *
  986. * @brief Setup the device security configuration parameters.
  987. *
  988. * @param pIRK - pointer to Identity Root Key, NULLKEY (all zeroes) if the app
  989. * wants the GAP to generate the key.
  990. * @param pSRK - pointer to Sign Resolving Key, NULLKEY if the app
  991. * wants the GAP to generate the key.
  992. * @param pSignCounter - 32 bit value used in the SM Signing
  993. * algorithm that shall be initialized to zero and incremented
  994. * with every new signing. This variable must also be maintained
  995. * by the application.
  996. *
  997. * @return none
  998. */
  999. extern void GAP_SecParamsInit( uint8 *pIRK, uint8 *pSRK, uint32 *pSignCounter );
  1000. /**
  1001. * @internal
  1002. *
  1003. * @brief Initialize the GAP Peripheral Dev Manager.
  1004. *
  1005. * @param none
  1006. *
  1007. * @return SUCCESS or bleMemAllocError
  1008. */
  1009. extern bStatus_t GAP_PeriDevMgrInit( void );
  1010. /**
  1011. * @internal
  1012. *
  1013. * @brief Initialize the GAP Central Dev Manager.
  1014. *
  1015. * @param maxScanResponses - maximum number to scan responses
  1016. * we can receive during a device discovery.
  1017. *
  1018. * @return SUCCESS or bleMemAllocError
  1019. */
  1020. extern bStatus_t GAP_CentDevMgrInit( uint8 maxScanResponses );
  1021. /**
  1022. * @internal
  1023. *
  1024. * @brief Register the GAP Central Connection processing functions.
  1025. *
  1026. * @param none
  1027. *
  1028. * @return none
  1029. */
  1030. extern void GAP_CentConnRegister( void );
  1031. /*-------------------------------------------------------------------
  1032. * TASK API - These functions must only be called OSAL.
  1033. */
  1034. /**
  1035. * @internal
  1036. *
  1037. * @brief GAP Task initialization function.
  1038. *
  1039. * @param taskID - GAP task ID.
  1040. *
  1041. * @return void
  1042. */
  1043. extern void GAP_Init( uint8 task_id );
  1044. /**
  1045. * @internal
  1046. *
  1047. * @brief GAP Task event processing function.
  1048. *
  1049. * @param taskID - GAP task ID
  1050. * @param events - GAP events.
  1051. *
  1052. * @return events not processed
  1053. */
  1054. extern uint16 GAP_ProcessEvent( uint8 task_id, uint16 events );
  1055. /*-------------------------------------------------------------------
  1056. -------------------------------------------------------------------*/
  1057. #ifdef __cplusplus
  1058. }
  1059. #endif
  1060. #endif /* GAP_H */