gap.h

Go to the documentation of this file.

/******************************************************************************

 Group: WCS, BTS
 $Target Device: DEVICES $

 ******************************************************************************
 $License: TISD 2009 $
 ******************************************************************************
 $Release Name: PACKAGE NAME $
 $Release Date: PACKAGE RELEASE DATE $
 *****************************************************************************/

#ifndef GAP_H
#define GAP_H

#ifdef __cplusplus
extern "C"
{
#endif

/*-------------------------------------------------------------------
 * INCLUDES
 */
#include <stdbool.h>
#include "bcomdef.h"
#include "osal.h"
#include "sm.h"
#include "ll_ae.h"

/*-------------------------------------------------------------------
 * MACROS
 */
#ifndef status_t
  #define status_t bStatus_t
#endif

#define GAP_IS_ADDR_RPR(pAddr) ((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == PRIVATE_RESOLVE_ADDR_HDR)

#define GAP_IS_ADDR_RPN(pAddr) ((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == PRIVATE_NON_RESOLVE_ADDR_HDR)

#define GAP_IS_ADDR_RS(pAddr)  ((pAddr[B_ADDR_LEN-1] & RANDOM_ADDR_HDR_MASK) \
                                 == STATIC_ADDR_HDR)

#define GAP_IS_ADDR_RAND(pAddr) (GAP_IS_ADDR_RPR(pAddr) | \
                                 GAP_IS_ADDR_RPN(pAddr) | \
                                 GAP_IS_ADDR_RS(pAddr))

/*-------------------------------------------------------------------
 * CONSTANTS
 */

#define GAP_DEVICE_INIT_DONE_EVENT            0x00

#define GAP_LINK_ESTABLISHED_EVENT            0x05

#define GAP_LINK_TERMINATED_EVENT             0x06

#define GAP_LINK_PARAM_UPDATE_EVENT           0x07

#define GAP_SIGNATURE_UPDATED_EVENT           0x09

#define GAP_AUTHENTICATION_COMPLETE_EVENT     0x0A

#define GAP_PASSKEY_NEEDED_EVENT              0x0B

#define GAP_SLAVE_REQUESTED_SECURITY_EVENT    0x0C

#define GAP_BOND_COMPLETE_EVENT               0x0E

#define GAP_PAIRING_REQ_EVENT                 0x0F

#define GAP_AUTHENTICATION_FAILURE_EVT        0x10

#define GAP_UPDATE_LINK_PARAM_REQ_EVENT       0x11
#define GAP_SCAN_SESSION_END_EVENT            0x12
#define GAP_ADV_REMOVE_SET_EVENT              0x13

#define GAP_CONNECTING_CANCELLED_EVENT        0x15

#define GAP_EVT_ADV_START_AFTER_ENABLE             (uint32_t)BV(0)

#define GAP_EVT_ADV_END_AFTER_DISABLE              (uint32_t)BV(1)

#define GAP_EVT_ADV_START                          (uint32_t)BV(2)

#define GAP_EVT_ADV_END                            (uint32_t)BV(3)

#define GAP_EVT_ADV_SET_TERMINATED                 (uint32_t)BV(4)

#define GAP_EVT_SCAN_REQ_RECEIVED                  (uint32_t)BV(5)

#define GAP_EVT_ADV_DATA_TRUNCATED                 (uint32_t)BV(6)
#define GAP_EVT_SCAN_ENABLED                       (uint32_t)BV(16)

#define GAP_EVT_SCAN_DISABLED                      (uint32_t)BV(17)

#define GAP_EVT_SCAN_PRD_ENDED                     (uint32_t)BV(18)
#define GAP_EVT_SCAN_DUR_ENDED                     (uint32_t)BV(19)

#define GAP_EVT_SCAN_INT_ENDED                     (uint32_t)BV(20)
#define GAP_EVT_SCAN_WND_ENDED                     (uint32_t)BV(21)

#define GAP_EVT_ADV_REPORT                         (uint32_t)BV(22)

#define GAP_EVT_ADV_REPORT_FULL                    (uint32_t)BV(23)

#define GAP_EVT_PRD_ADV_SYNC_ESTABLISHED           (uint32_t)BV(24)

#define GAP_EVT_PRD_ADV_REPORT                     (uint32_t)BV(25)

#define GAP_EVT_PRD_ADV_SYNC_LOST                  (uint32_t)BV(26)
#define GAP_EVT_INSUFFICIENT_MEMORY                (uint32_t)BV(31)

#define GAP_EVT_ADV_EVT_MASK   (GAP_EVT_ADV_START_AFTER_ENABLE |   \
                                GAP_EVT_ADV_END_AFTER_DISABLE |    \
                                GAP_EVT_ADV_START |                \
                                GAP_EVT_ADV_END |                  \
                                GAP_EVT_ADV_SET_TERMINATED |       \
                                GAP_EVT_SCAN_REQ_RECEIVED |        \
                                GAP_EVT_ADV_DATA_TRUNCATED |       \
                                GAP_EVT_INSUFFICIENT_MEMORY)

#define GAP_EVT_SCAN_EVT_MASK  (GAP_EVT_SCAN_ENABLED |                    \
                                GAP_EVT_SCAN_DISABLED |                   \
                                GAP_EVT_SCAN_PRD_ENDED |                  \
                                GAP_EVT_SCAN_DUR_ENDED |                  \
                                GAP_EVT_SCAN_INT_ENDED |                  \
                                GAP_EVT_SCAN_WND_ENDED |                  \
                                GAP_EVT_ADV_REPORT |                      \
                                GAP_EVT_ADV_REPORT_FULL |                 \
                                GAP_EVT_PRD_ADV_SYNC_ESTABLISHED |        \
                                GAP_EVT_PRD_ADV_REPORT |                  \
                                GAP_EVT_PRD_ADV_SYNC_LOST |               \
                                GAP_EVT_INSUFFICIENT_MEMORY)

typedef enum
{
  GAP_CONFIG_PARAM_IRK,

  GAP_CONFIG_PARAM_SRK,

  GAP_CONFIG_PARAM_COUNT
} Gap_configParamIds_t;

enum Gap_ParamIDs_t
{
  GAP_PARAM_LINK_UPDATE_DECISION,

  GAP_PARAM_CONN_PARAM_TIMEOUT,

  GAP_PARAM_PRIVATE_ADDR_INT,

  GAP_PARAM_SM_TIMEOUT,

  GAP_PARAM_SM_MIN_KEY_LEN,

  GAP_PARAM_SM_MAX_KEY_LEN,


  GAP_PARAM_AUTH_TASK_ID,

  GAP_PARAM_DEPRECATED,

  GAP_PARAM_GGS_PARAMS,

#if defined ( TESTMODES )

  GAP_PARAM_GAP_TESTCODE,

  GAP_PARAM_SM_TESTCODE,

  GAP_PARAM_GATT_TESTCODE,

  GAP_PARAM_ATT_TESTCODE,

  GAP_PARAM_L2CAP_TESTCODE,
#endif // TESTMODES

  GAP_PARAMID_MAX
};

#define GAP_PROFILE_BROADCASTER   0x01
#define GAP_PROFILE_OBSERVER      0x02

#define GAP_PROFILE_PERIPHERAL    0x04

#define GAP_PROFILE_CENTRAL       0x08

typedef enum
{
  GAP_UPDATE_REQ_ACCEPT_ALL,     
  GAP_UPDATE_REQ_DENY_ALL,       

  GAP_UPDATE_REQ_PASS_TO_APP
} Gap_updateDecision_t;

typedef enum
{
  ADDRMODE_PUBLIC            = 0x00,  
  ADDRMODE_RANDOM            = 0x01,  
  ADDRMODE_RP_WITH_PUBLIC_ID = 0x02,
  ADDRMODE_RP_WITH_RANDOM_ID = 0x03,
} GAP_Addr_Modes_t;

typedef enum
{
  ADDRTYPE_PUBLIC    = 0x00,  
  ADDRTYPE_RANDOM    = 0x01,  
  ADDRTYPE_PUBLIC_ID = 0x02,
  ADDRTYPE_RANDOM_ID = 0x03,
  ADDRTYPE_RANDOM_NR = 0xFE,
  ADDRTYPE_NONE      = 0xFF   
} GAP_Addr_Types_t;

typedef enum
{
  PEER_ADDRTYPE_PUBLIC_OR_PUBLIC_ID = 0x00,  
  PEER_ADDRTYPE_RANDOM_OR_RANDOM_ID = 0x01   
} GAP_Peer_Addr_Types_t;

#define SET_ADDRTYPE_ID               0x02
#define MASK_ADDRTYPE_ID              0x01

#define RANDOM_ADDR_HDR_MASK          0xC0
#define STATIC_ADDR_HDR               0xC0
#define PRIVATE_NON_RESOLVE_ADDR_HDR  0x80
#define PRIVATE_RESOLVE_ADDR_HDR      0x40

#define GAP_ADTYPE_FLAGS                        0x01
#define GAP_ADTYPE_16BIT_MORE                   0x02
#define GAP_ADTYPE_16BIT_COMPLETE               0x03
#define GAP_ADTYPE_32BIT_MORE                   0x04
#define GAP_ADTYPE_32BIT_COMPLETE               0x05
#define GAP_ADTYPE_128BIT_MORE                  0x06
#define GAP_ADTYPE_128BIT_COMPLETE              0x07
#define GAP_ADTYPE_LOCAL_NAME_SHORT             0x08
#define GAP_ADTYPE_LOCAL_NAME_COMPLETE          0x09
#define GAP_ADTYPE_POWER_LEVEL                  0x0A
#define GAP_ADTYPE_OOB_CLASS_OF_DEVICE          0x0D
#define GAP_ADTYPE_OOB_SIMPLE_PAIRING_HASHC     0x0E
#define GAP_ADTYPE_OOB_SIMPLE_PAIRING_RANDR     0x0F
#define GAP_ADTYPE_SM_TK                        0x10
#define GAP_ADTYPE_SM_OOB_FLAG                  0x11

#define GAP_ADTYPE_SLAVE_CONN_INTERVAL_RANGE    0x12
#define GAP_ADTYPE_SIGNED_DATA                  0x13
#define GAP_ADTYPE_SERVICES_LIST_16BIT          0x14
#define GAP_ADTYPE_SERVICES_LIST_128BIT         0x15
#define GAP_ADTYPE_SERVICE_DATA                 0x16
#define GAP_ADTYPE_PUBLIC_TARGET_ADDR           0x17
#define GAP_ADTYPE_RANDOM_TARGET_ADDR           0x18
#define GAP_ADTYPE_APPEARANCE                   0x19
#define GAP_ADTYPE_ADV_INTERVAL                 0x1A
#define GAP_ADTYPE_LE_BD_ADDR                   0x1B
#define GAP_ADTYPE_LE_ROLE                      0x1C
#define GAP_ADTYPE_SIMPLE_PAIRING_HASHC_256     0x1D
#define GAP_ADTYPE_SIMPLE_PAIRING_RANDR_256     0x1E
#define GAP_ADTYPE_SERVICE_DATA_32BIT           0x20
#define GAP_ADTYPE_SERVICE_DATA_128BIT          0x21
#define GAP_ADTYPE_3D_INFO_DATA                 0x3D

#define GAP_ADTYPE_MANUFACTURER_SPECIFIC        0xFF
#define GAP_ADTYPE_FLAGS_LIMITED                0x01
#define GAP_ADTYPE_FLAGS_GENERAL                0x02
#define GAP_ADTYPE_FLAGS_BREDR_NOT_SUPPORTED    0x04

#define GAP_STATE_IDLE                          0x00 
#define GAP_STATE_ADV                           0x01 
#define GAP_STATE_SCAN                          0x02 
#define GAP_STATE_INIT                          0x04 

#define GAP_APPEARE_UNKNOWN                     0x0000 
#define GAP_APPEARE_GENERIC_PHONE               0x0040 
#define GAP_APPEARE_GENERIC_COMPUTER            0x0080 
#define GAP_APPEARE_GENERIC_WATCH               0x00C0 
#define GAP_APPEARE_WATCH_SPORTS                0x00C1 
#define GAP_APPEARE_GENERIC_CLOCK               0x0100 
#define GAP_APPEARE_GENERIC_DISPLAY             0x0140 
#define GAP_APPEARE_GENERIC_RC                  0x0180 
#define GAP_APPEARE_GENERIC_EYE_GALSSES         0x01C0 
#define GAP_APPEARE_GENERIC_TAG                 0x0200 
#define GAP_APPEARE_GENERIC_KEYRING             0x0240 
#define GAP_APPEARE_GENERIC_MEDIA_PLAYER        0x0280 
#define GAP_APPEARE_GENERIC_BARCODE_SCANNER     0x02C0 
#define GAP_APPEARE_GENERIC_THERMOMETER         0x0300 
#define GAP_APPEARE_GENERIC_THERMO_EAR          0x0301 
#define GAP_APPEARE_GENERIC_HR_SENSOR           0x0340 
#define GAP_APPEARE_GENERIC_HRS_BELT            0x0341 
#define GAP_APPEARE_GENERIC_BLOOD_PRESSURE      0x0380 
#define GAP_APPEARE_GENERIC_BP_ARM              0x0381 
#define GAP_APPEARE_GENERIC_BP_WRIST            0x0382 
#define GAP_APPEARE_GENERIC_HID                 0x03C0 
#define GAP_APPEARE_HID_KEYBOARD                0x03C1 
#define GAP_APPEARE_HID_MOUSE                   0x03C2 
#define GAP_APPEARE_HID_JOYSTIC                 0x03C3 
#define GAP_APPEARE_HID_GAMEPAD                 0x03C4 
#define GAP_APPEARE_HID_DIGITIZER_TYABLET       0x03C5 
#define GAP_APPEARE_HID_DIGITAL_CARDREADER      0x03C6 
#define GAP_APPEARE_HID_DIGITAL_PEN             0x03C7 
#define GAP_APPEARE_HID_BARCODE_SCANNER         0x03C8 

#define GAP_PRIVACY_MODE_NETWORK                0 
#define GAP_PRIVACY_MODE_DEVICE                 1 

typedef enum
{
  GAP_CONN_EVT_PHY_1MBPS = 1, 
  GAP_CONN_EVT_PHY_2MBPS = 2, 
  GAP_CONN_EVT_PHY_CODED = 4, 
} GAP_ConnEvtPhy_t;

typedef enum
{
  GAP_CONN_EVT_STAT_SUCCESS   = LL_CONN_EVT_STAT_SUCCESS,
  GAP_CONN_EVT_STAT_CRC_ERROR = LL_CONN_EVT_STAT_CRC_ERROR,
  GAP_CONN_EVT_STAT_MISSED    = LL_CONN_EVT_STAT_MISSED
} GAP_ConnEvtStat_t;

typedef enum
{
  GAP_CONN_EVT_TASK_TYPE_ADV    = LL_TASK_ID_ADVERTISER,
  GAP_CONN_EVT_TASK_TYPE_INIT   = LL_TASK_ID_INITIATOR,
  GAP_CONN_EVT_TASK_TYPE_SLAVE  = LL_TASK_ID_SLAVE,
  GAP_CONN_EVT_TASK_TYPE_SCAN   = LL_TASK_ID_SCANNER,
  GAP_CONN_EVT_TASK_TYPE_MASTER = LL_TASK_ID_MASTER,
  // No task
  GAP_CONN_EVT_TASK_TYPE_NONE   = LL_TASK_ID_NONE
} GAP_ConnEvtTaskType_t;

typedef enum
{
  GAP_CB_REGISTER, 
  GAP_CB_UNREGISTER 
} GAP_CB_Action_t;

/*-------------------------------------------------------------------
 * TYPEDEFS
 */

typedef struct
{
  osal_event_hdr_t  hdr;           
  uint8_t opcode;                  
} gapEventHdr_t;

typedef struct
{
  uint16_t intervalMin;
  uint16_t intervalMax;
  uint16_t latency;
  uint16_t timeout;
} gapPeriConnectParams_t;

typedef struct
{
  osal_event_hdr_t  hdr;                
  uint8_t  opcode;                      
  uint8_t  numDataPkts;                 
  uint16_t dataPktLen;                  
  uint8_t  devAddr[B_ADDR_LEN];         
} gapDeviceInitDoneEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;            
  uint8_t opcode;                   
  uint8_t addrType;                 
  uint8_t devAddr[B_ADDR_LEN];      
  uint32_t signCounter;             
} gapSignUpdateEvent_t;

typedef struct
{
  uint16_t connectionHandle; 
  uint16_t intervalMin;      
  uint16_t intervalMax;      
  uint16_t connLatency;      
  uint16_t connTimeout;      
  uint8_t  signalIdentifier; 
} gapUpdateLinkParamReq_t;

typedef struct
{
  uint16_t connectionHandle; 
  uint16_t intervalMin;      
  uint16_t intervalMax;      
  uint16_t connLatency;      
  uint16_t connTimeout;      
  uint8_t  signalIdentifier; 
  uint8_t  accepted;         
} gapUpdateLinkParamReqReply_t;

typedef struct
{
  osal_event_hdr_t  hdr;              
  uint8_t opcode;                     
  gapUpdateLinkParamReq_t req;        
} gapUpdateLinkParamReqEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;       
  uint8_t opcode;              
  uint8_t devAddrType;         
  uint8_t devAddr[B_ADDR_LEN]; 
  uint16_t connectionHandle;   
  uint8_t connRole;            
  uint16_t connInterval;       
  uint16_t connLatency;        
  uint16_t connTimeout;        
  uint8_t clockAccuracy;       
} gapEstLinkReqEvent_t;

typedef struct
{
  osal_event_hdr_t hdr;       
  uint8_t opcode;             
  uint8_t status;             
  uint16_t connectionHandle;  
  uint16_t connInterval;      
  uint16_t connLatency;       
  uint16_t connTimeout;       
} gapLinkUpdateEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;     
  uint8_t opcode;            
  uint16_t connectionHandle; 
  uint8_t reason;            
} gapTerminateLinkEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;          
  uint8_t opcode;                 
  uint8_t deviceAddr[B_ADDR_LEN]; 
  uint16_t connectionHandle;      
  uint8_t uiInputs;               
  uint8_t uiOutputs;              
  uint32_t numComparison;         
} gapPasskeyNeededEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;           
  uint8_t opcode;                  
  uint16_t connectionHandle;       
  uint8_t authState;               
  smSecurityInfo_t *pSecurityInfo; 
  smSigningInfo_t *pSigningInfo;   
  smSecurityInfo_t *pDevSecInfo;   
  smIdentityInfo_t *pIdentityInfo; 
} gapAuthCompleteEvent_t;

typedef struct
{
  uint16_t connectionHandle;    
  smLinkSecurityReq_t  secReqs; 
} gapAuthParams_t;

typedef struct
{
  osal_event_hdr_t  hdr;          
  uint8_t opcode;                 
  uint16_t connectionHandle;      
  uint8_t deviceAddr[B_ADDR_LEN]; 

  uint8_t authReq;
} gapSlaveSecurityReqEvent_t;

typedef struct
{
  osal_event_hdr_t  hdr;     
  uint8_t opcode;            
  uint16_t connectionHandle; 
} gapBondCompleteEvent_t;

typedef struct
{
  uint8_t ioCap;         
  uint8_t oobDataFlag;   
  uint8_t authReq;       
  uint8_t maxEncKeySize; 
  keyDist_t keyDist;     
} gapPairingReq_t;

typedef struct
{
  osal_event_hdr_t hdr;      
  uint8_t opcode;            
  uint16_t connectionHandle; 
  gapPairingReq_t pairReq;   
} gapPairingReqEvent_t;

typedef struct
{
  GAP_ConnEvtStat_t     status;   
  uint16_t              handle;   
  uint8_t               channel;  
  GAP_ConnEvtPhy_t      phy;      
  int8_t                lastRssi; 
  uint16_t              packets;
  uint16_t              errors;
  GAP_ConnEvtTaskType_t nextTaskType;
  uint32_t              nextTaskTime;
} Gap_ConnEventRpt_t;

/*-------------------------------------------------------------------
 * CALLBACKS
 */

typedef uint8_t(*pfnSuppCentAddrRes_t)
(
  uint8_t *deviceAddr,           
  GAP_Peer_Addr_Types_t addrType 
);

//TODO try to move these to gap_internal.h

typedef void (*pfnGapIdleCB_t)();

typedef uint8_t(*pfnGapDevPrivModeCB_t)
(
  GAP_Peer_Addr_Types_t  addrType,    
  uint8_t                *pAddr       
);

typedef struct
{
  pfnSuppCentAddrRes_t   suppCentAddrResCB;  
  pfnGapIdleCB_t         gapIdleCB;          
  pfnGapDevPrivModeCB_t  gapDevPrivModeCB;   
} gapBondMgrCBs_t;

typedef void (*pfnGapCB_t)
(
  uint32_t event,   
  void *pBuf,       
  uintptr_t arg     
);

typedef void (*pfnGapConnEvtCB_t)
(
  Gap_ConnEventRpt_t *pReport
);

/*-------------------------------------------------------------------
 * FUNCTIONS - Initialization and Configuration
 */

extern bStatus_t GAP_DeviceInit(uint8_t profileRole, uint8_t taskID,
                                GAP_Addr_Modes_t addrMode,
                                uint8_t* pRandomAddr);

extern bStatus_t GAP_SetParamValue(uint16_t paramID, uint16_t paramValue);

extern uint16_t GAP_GetParamValue(uint16_t paramID);

extern void GAP_RegisterForMsgs(uint8_t taskID);

extern void GAP_RegisterBondMgrCBs(gapBondMgrCBs_t *pCBs);

extern bStatus_t GAP_SetPrivacyMode(GAP_Peer_Addr_Types_t addrType,
                                    uint8_t *pAddr, uint8_t mode);

/*-------------------------------------------------------------------
 * FUNCTIONS - Link Establishment
 */

extern bStatus_t GAP_TerminateLinkReq(uint16_t connectionHandle, uint8_t reason);

extern bStatus_t GAP_UpdateLinkParamReq(gapUpdateLinkParamReq_t *pParams);

extern bStatus_t GAP_UpdateLinkParamReqReply(gapUpdateLinkParamReqReply_t
   *pParams);

extern uint8_t GAP_NumActiveConnections(void);

extern bStatus_t Gap_RegisterConnEventCb(pfnGapConnEvtCB_t cb,
                                         GAP_CB_Action_t action,
                                         uint16_t connHandle);

/*-------------------------------------------------------------------
 * FUNCTIONS - GAP Configuration
 */

extern bStatus_t GapConfig_SetParameter(Gap_configParamIds_t param,
                                        void *pValue);

extern uint8_t *GAP_GetDevAddress(uint8 wantIA);

extern uint8_t *GAP_GetIRK(void);

extern uint8_t *GAP_GetSRK(void);

/*-------------------------------------------------------------------
 * FUNCTIONS - Pairing
 */

extern bStatus_t GAP_Authenticate(gapAuthParams_t *pParams,
                                  gapPairingReq_t *pPairReq);

extern uint8_t GAP_isPairing(void);

extern bStatus_t GAP_TerminateAuth(uint16_t connectionHandle, uint8_t reason);

extern bStatus_t GAP_PasskeyUpdate(uint8_t *pPasskey, uint16_t connectionHandle);

extern bStatus_t GAP_PasscodeUpdate(uint32_t passcode, uint16_t connectionHandle);

extern bStatus_t GAP_SendSlaveSecurityRequest(uint16_t connectionHandle,
                                              uint8_t authReq);

extern bStatus_t GAP_Signable(uint16_t connectionHandle, uint8_t authenticated,
                              smSigningInfo_t *pParams);

extern bStatus_t GAP_Bond(uint16_t connectionHandle, uint8_t authenticated,
                          uint8_t secureConnections, smSecurityInfo_t *pParams,
                          uint8_t startEncryption);

/*-------------------------------------------------------------------
 * TASK FUNCTIONS - To only be used in osal_icall_ble.c
 */

extern void GAP_Init(uint8_t task_id);

extern uint16_t GAP_ProcessEvent(uint8_t task_id, uint16_t events);

/*-------------------------------------------------------------------
-------------------------------------------------------------------*/

#ifdef __cplusplus
}
#endif

#endif /* GAP_H */