bt_hal_manager.h

Go to the documentation of this file.

/*
 * FreeRTOS BLE HAL V5.0.0
 * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy of
 * this software and associated documentation files (the "Software"), to deal in
 * the Software without restriction, including without limitation the rights to
 * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
 * the Software, and to permit persons to whom the Software is furnished to do so,
 * subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
 * http://aws.amazon.com/freertos
 * http://www.FreeRTOS.org
 */
 
#ifndef _BT_HAL_MANAGER_H_
#define _BT_HAL_MANAGER_H_
 
#include <stdint.h>
 
#include "bt_hal_manager_types.h"
 
#define btMAJOR_VERSION    5
 
#define btMINOR_VERSION    0
 
#define btPATCH_VERSION    1
 
#define btSTR_HELPER( x, y, z )    # x "." # y "." # z
#define btSTR( x, y, z )           btSTR_HELPER( x, y, z )
 
#define btSTRING_VERSION                        btSTR( btMAJOR_VERSION, btMINOR_VERSION, btPATCH_VERSION )
 
#define btBLE_ADD_BLOB_SERVICE_SUPPORTED_BIT    0x0001 
#define btBLE_ADD_BLE_DYNAMIC_PRIVACY           0x0002 
#define btBLE_BLE_CENTRAL_WHITELISTING          0x0004 
enum
{
    eBTSecLevelNoSecurity = 0x01,             
    eBTSecLevelUnauthenticatedPairing = 0x02, 
    eBTSecLevelAuthenticatedPairing = 0x03,   
    eBTSecLevelSecureConnect = 0x04,          
};
typedef uint8_t BTSecurityLevel_t;
 
enum
{
    eBTAuthReqBonding = 0x01,       
    eBTAuthReqMitm = 0x03,          
    eBTAuthReqSecureConnect = 0x04, 
    eBTAuthReqKeyPress = 0x05,
};
typedef uint8_t BTAuthReq_t;
 
typedef enum
{
    BTTransportAuto,  
    BTTransportBredr, 
    BTTransportLe,    
} BTTransport_t;
 
typedef enum
{
    eBTstateOff, 
    eBTstateOn,  
} BTState_t;
 
typedef struct
{
    uint8_t ucPin[ 16 ]; 
} BTPinCode_t;
 
typedef enum
{
    eBTauthSuccess,                
    eBTauthFailLmpRespTimeout,     
    eBTauthFailKeyMissing,         
    eBTauthFailEncrypMode,         
    eBTauthFailUnitKey,            
    eBTauthFailSmpCfrmValue,       
    eBTauthFailSmpEnc,             
    eBTauthFailSmpTimeout,         
    eBTauthFailPageTimeout,        
    eBTauthFailSmpPasskeyFail,     
    eBTauthFailSmpOobFail,         
    eBTauthFailSmpFail,            
    eBTauthFailConnTimeout,        
    eBTauthFailSmp,                
    eBTauthFailSmpPairNotSupport,  
    eBTauthFailSmpUnknownIo,       
    eBTauthFailSmpUnknown,         
    eBTauthFailHostRejectSecurity, 
    eBTauthFailInsuffSecurity,     
    eBTauthFailPeerUser,           
    eBTauthFailUnspecified,        
} BTAuthFailureReason_t;
 
 
typedef enum
{
    eBTpropertyBdname = 0x1, 
    eBTpropertyBdaddr, 
    eBTpropertyTypeOfDevice, 
    eBTpropertyAdapterBondedDevices, 
    /* Properties unique to remote device */
 
    eBTpropertyRemoteFriendlyName, 
    eBTpropertyRemoteRssi, 
    eBTpropertyRemoteVersionInfo, 
    eBTpropertyLocalMTUSize, 
    eBTpropertyBondable, 
    eBTpropertyIO, 
    eBTpropertyConnectable, 
    eBTpropertySecureConnectionOnly, 
} BTPropertyType_t;
 
typedef struct
{
    BTPropertyType_t xType; 
    size_t xLen;            
    void * pvVal;           
} BTProperty_t;
 
typedef struct
{
    uint8_t ucBleDevAddr[ btADDRESS_LEN ]; 
    uint8_t ucC192[ btKEY_MAX_LEN ];       
    uint8_t ucR192[ btKEY_MAX_LEN ];       
    uint8_t ucC256[ btKEY_MAX_LEN ];       
    uint8_t ucR256[ btKEY_MAX_LEN ];       
    uint8_t ucSm_tk[ btKEY_MAX_LEN ];      
    uint8_t ucLe_sc_c[ btKEY_MAX_LEN ];    
    uint8_t ucLe_sc_r[ btKEY_MAX_LEN ];    
} BTOutOfBandData_t;
 
typedef enum
{
    eBTdeviceDevtypeBredr = 0x1, 
    eBTdeviceDevtypeBle,         
    eBTdeviceDevtypeDual,        
} BTDeviceType_t;
 
typedef enum
{
    eBTbondStateNone,
    eBTbondStateBonding,
    eBTbondStateBonded,
} BTBondState_t;
 
typedef enum
{
    eBTsspVariantPasskeyConfirmation, 
    eBTsspVariantPasskeyEntry,        
    eBTsspVariantConsent,             
    eBTsspVariantPasskeyNotification, 
} BTSspVariant_t;
 
typedef struct
{
    uint8_t ucStatus;
    uint8_t ucCtrlState;    
    uint64_t ullTxTime;     
    uint64_t ullRxTime;     
    uint64_t ullIdleTime;   
    uint64_t ullEnergyUsed; 
} BTActivityEnergyInfo;
 
typedef struct
{
    int32_t lAppUid;
    uint64_t ullTxBytes;
    uint64_t ullRxBytes;
} BTUidTraffic_t;
 
typedef void ( * BTDeviceStateChangedCallback_t )( BTState_t xState );
 
typedef void ( * BTDevicePropertiesCallback_t )( BTStatus_t xStatus,
                                                 uint32_t ulNumProperties,
                                                 BTProperty_t * pxProperties );
 
typedef void ( * BTRemoteDevicePropertiesCallback_t )( BTStatus_t xStatus,
                                                       BTBdaddr_t * pxBdAddr,
                                                       uint32_t ulNumProperties,
                                                       BTProperty_t * pxProperties );
 
typedef void (* BTPinRequestCallback_t)( BTBdaddr_t * pxRemoteBdAddr,
                                         BTBdname_t * pxBdName,
                                         uint32_t ulCod,
                                         uint8_t ucMin16Digit );
 
 
typedef void ( * BTSspRequestCallback_t )( BTBdaddr_t * pxRemoteBdAddr,
                                           BTBdname_t * pxRemoteBdName,
                                           uint32_t ulCod,
                                           BTSspVariant_t xPairingVariant,
                                           uint32_t ulPassKey );
 
typedef void ( * BTPairingStateChangedCallback_t )( BTStatus_t xStatus,
                                                    BTBdaddr_t * pxRemoteBdAddr,
                                                    BTBondState_t xState,
                                                    BTSecurityLevel_t xSecurityLevel,
                                                    BTAuthFailureReason_t xReason );
 
typedef void ( * BTEnergyInfoCallback_t )( BTActivityEnergyInfo * pxEnergyInfo,
                                           BTUidTraffic_t * pxUidData );
 
/* Receive any HCI event from controller. Must be in DUT Mode for this callback to be received */
typedef void ( * BTDutModeRecvCallback_t )( uint16_t usOpcode,
                                            uint8_t * pucBuf,
                                            size_t xLen );
 
/*
 * This callback shall be invoked whenever the le_tx_test, le_rx_test or le_test_end is invoked
 * The num_packets is valid only for le_test_end command */
 
typedef void ( * BTLeTestModeCallback_t )( BTStatus_t xStatus,
                                           uint16_t usNumPackets );
 
typedef void ( * BTReadRssiCallback_t )( BTBdaddr_t * pxBda,
                                         uint32_t ulRssi,
                                         BTStatus_t xStatus );
 
typedef void ( * BTSlaveSecurityRequestCallBack_t )( BTBdaddr_t * pxBda,
                                                     BTSecurityLevel_t xSecurityLevel,
                                                     bool bBonding );
 
typedef void ( * BTTxPowerCallback_t )( BTBdaddr_t * pxBda,
                                        BTTransport_t xTransport,
                                        uint8_t ucTxPowerValue,
                                        BTStatus_t xStatus );
 
typedef void ( * BTBondedCallback_t)( BTStatus_t xStatus,
                                      BTBdaddr_t * pxRemoteBdAddr,
                                      bool bIsBonded );
 
typedef struct
{
    BTDeviceStateChangedCallback_t pxDeviceStateChangedCb;
    BTDevicePropertiesCallback_t pxAdapterPropertiesCb;
    BTRemoteDevicePropertiesCallback_t pxRemoteDevicePropertiesCb;
    BTPinRequestCallback_t pxPinRequestCb;
    BTSspRequestCallback_t pxSspRequestCb;
    BTPairingStateChangedCallback_t pxPairingStateChangedCb;
    BTBondedCallback_t pxBondedCb; 
    BTDutModeRecvCallback_t pxDutModeRecvCb;
    BTLeTestModeCallback_t pxleTestModeCb;
    BTEnergyInfoCallback_t pxEnergyInfoCb;
    BTReadRssiCallback_t pxReadRssiCb;
    BTTxPowerCallback_t pxTxPowerCb;
    BTSlaveSecurityRequestCallBack_t pxSlaveSecurityRequestCb;
} BTCallbacks_t;
 
typedef struct
{
    BTStatus_t ( * pxBtManagerInit )( const BTCallbacks_t * pxCallbacks );
 
    BTStatus_t ( * pxBtManagerCleanup )( void );
 
    BTStatus_t ( * pxEnable )( uint8_t ucGuestMode );
 
    BTStatus_t ( * pxDisable )();
 
    BTStatus_t ( * pxGetAllDeviceProperties )();
 
    BTStatus_t ( * pxGetDeviceProperty )( BTPropertyType_t xType );
 
    BTStatus_t ( * pxSetDeviceProperty )( const BTProperty_t * pxProperty );
 
    BTStatus_t ( * pxGetAllRemoteDeviceProperties )( BTBdaddr_t * pxRemoteAddr );
 
    BTStatus_t ( * pxGetRemoteDeviceProperty )( BTBdaddr_t * pxRemoteAddr,
                                                BTPropertyType_t xType );
 
    BTStatus_t ( * pxSetRemoteDeviceProperty )( BTBdaddr_t * pxRemoteAddr,
                                                const BTProperty_t * pxProperty );
 
    BTStatus_t ( * pxPair )( const BTBdaddr_t * pxBdAddr,
                             BTTransport_t xTransport,
                             bool bCreateBond );
 
    BTStatus_t ( * pxCreateBondOutOfBand )( const BTBdaddr_t * pxBdAddr,
                                            BTTransport_t xTransport,
                                            const BTOutOfBandData_t * pxOobData );
 
    BTStatus_t ( * pxSendSlaveSecurityRequest )( const BTBdaddr_t * pxBdAddr,
                                                 BTSecurityLevel_t xSecurityLevel,
                                                 bool bBonding );
 
    /* TODO:Handle out of band pairing in better way */
 
    BTStatus_t ( * pxCancelBond )( const BTBdaddr_t * pxBdAddr );
 
    BTStatus_t ( * pxRemoveBond )( const BTBdaddr_t * pxBdAddr );
    BTStatus_t ( * pxGetConnectionState )( const BTBdaddr_t * pxBdAddr,
                                           bool * bConnectionState );
 
    BTStatus_t ( * pxPinReply )( const BTBdaddr_t * pxBdAddr,
                                 uint8_t ucAccept,
                                 uint8_t ucPinLen,
                                 BTPinCode_t * pxPinCode );
 
    BTStatus_t ( * pxSspReply )( const BTBdaddr_t * pxBdAddr,
                                 BTSspVariant_t xVariant,
                                 uint8_t ucAccept,
                                 uint32_t ulPasskey );
 
    BTStatus_t ( * pxReadEnergyInfo )();
 
    BTStatus_t ( * pxDutModeConfigure )( bool bEnable );
 
    BTStatus_t ( * pxDutModeSend )( uint16_t usOpcode,
                                    uint8_t * pucBuf,
                                    size_t xLen );
 
    BTStatus_t ( * pxLeTestMode )( uint16_t usOpcode,
                                   uint8_t * pucBuf,
                                   size_t xLen );
 
    BTStatus_t ( * pxConfigHCISnoopLog )( bool bEnable );
 
    BTStatus_t ( * pxConfigClear )();
 
    BTStatus_t ( * pxReadRssi )( const BTBdaddr_t * pxBdAddr );
 
    BTStatus_t ( * pxGetTxpower )( const BTBdaddr_t * pxBdAddr,
                                   BTTransport_t xTransport );
 
    const void * ( *pxGetClassicAdapter )( );
 
    const void * ( *pxGetLeAdapter )( );
 
    uint32_t ( * pxGetLastError )();
 
    BTStatus_t ( * pxGetStackFeaturesSupport )( uint32_t * pulFeatureMask );
} BTInterface_t;
 
const BTInterface_t * BTGetBluetoothInterface();
 
#endif /* _BT_HAL_MANAGER_H_ */