bt_hal_manager.h

Go to the documentation of this file.

/*
 * FreeRTOS BLE HAL V5.1.0
 * Copyright (C) 2020-2021 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    1

#define btPATCH_VERSION    0

#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 = 0,  
    BTTransportBredr = 1, 
    BTTransportLe = 2,    
} BTTransport_t;

typedef enum
{
    eBTstateOff, 
    eBTstateOn,  
} BTState_t;

typedef struct
{
    uint8_t ucPin[ 16 ]; 
} BTPinCode_t;

typedef enum
{
    eBTauthSuccess = 0x00,                     
    eBTauthFailLmpRespTimeout = 0x01,          
    eBTauthFailKeyMissing = 0x02,              
    eBTauthFailEncrypMode = 0x03,              
    eBTauthFailUnitKey = 0x04,                 
    eBTauthFailSmpCfrmValue = 0x05,            
    eBTauthFailSmpEnc = 0x06,                  
    eBTauthFailSmpTimeout = 0x07,              
    eBTauthFailPageTimeout = 0x08,             
    eBTauthFailSmpPasskeyFail = 0x09,          
    eBTauthFailSmpOobFail = 0x0A,              
    eBTauthFailSmpFail = 0x0B,                 
    eBTauthFailConnTimeout = 0x0C,             
    eBTauthFailSmp = 0x0D,                     
    eBTauthFailSmpPairNotSupport = 0x0E,       
    eBTauthFailSmpUnknownIo = 0x0F,            
    eBTauthFailSmpUnknown = 0x10,              
    eBTauthFailHostRejectSecurity = 0x11,      
    eBTauthFailInsuffSecurity = 0x12,          
    eBTauthFailPeerUser = 0x13,                
    eBTauthFailUnspecified = 0x14,             
    eBTauthFailSmpAuthReqFail = 0x15,          
    eBTauthFailSmpEncKeySize = 0x16,           
    eBTauthFailSmpCmdNotSupport = 0x17,        
    eBTauthFailSmpRepeatedAttempt = 0x18,      
    eBTauthFailSmpInvalidParameters = 0x19,    
    eBTauthFailSmpDhkeyCheckFail = 0x1A,       
    eBTauthFailSmpNumericComparFail = 0x1B,    
    eBTauthFailSmpBrPairInProg = 0x1C,         
    eBTauthFailSmpXtransDeriveNotAllow = 0x1D, 
    eBTauthFailStackErr = 0x100,               
    eBTauthFailHciErr = 0x200                  
} 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 enum
{
    eBTaclConnected = 0,   
    eBTaclDisconnected = 1 
} BTAclState_t;

typedef enum
{
    eBTaclSuccess = 0x00,                        
    eBTaclIllegalCommand = 0x01,                 
    eBTaclNoConnection = 0x02,                   
    eBTaclHwFailure = 0x03,                      
    eBTaclPageTimeout = 0x04,                    
    eBTaclAuthFailure = 0x05,                    
    eBTaclKeyMissing = 0x06,                     
    eBTaclMemFull = 0x07,                        
    eBTaclConnectionTimeout = 0x08,              
    eBTaclMaxNumOfConnections = 0x09,            
    eBTaclMaxNumOfScos = 0x0A,                   
    eBTaclConnectionExists = 0x0B,               
    eBTaclCommandDisallowed = 0x0C,              
    eBTaclHostRejectResource = 0x0D,             
    eBTaclHostRejectSecurity = 0x0E,             
    eBTaclHostRejectDevice = 0x0F,               
    eBTaclHostTimeout = 0x10,                    
    eBTaclUnsupportedValue = 0x11,               
    eBTaclIllegalParameterFmt = 0x12,            
    eBTaclPeerUser = 0x13,                       
    eBTaclPeerLowResources = 0x14,               
    eBTaclPeerPowerOff = 0x15,                   
    eBTaclHostUser = 0x16,                       
    eBTaclRepeatedAttempts = 0x17,               
    eBTaclPairingNotAllowed = 0x18,              
    eBTaclUnknownLmpPdu = 0x19,                  
    eBTaclUnsupportedRemFeature = 0x1A,          
    eBTaclScoOffsetRejected = 0x1B,              
    eBTaclScoIntervalRejected = 0x1C,            
    eBTaclScoAirRejected = 0x1D,                 
    eBTaclInvalidLmpParam = 0x1E,                
    eBTaclUnspecified = 0x1F,                    
    eBTaclUnsupportedLmpFeature = 0x20,          
    eBTaclRoleChangeNotAllowed = 0x21,           
    eBTaclLmpResponseTimeout = 0x22,             
    eBTaclLmpErrTransCollision = 0x23,           
    eBTaclLmpPduNotAllowed = 0x24,               
    eBTaclEncryModeNotAcceptable = 0x25,         
    eBTaclUnitKeyUsed = 0x26,                    
    eBTaclQosNotSupported = 0x27,                
    eBTaclInstantPassed = 0x28,                  
    eBTaclPairingWithUnitKeyNotSupported = 0x29, 
    eBTaclDiffTransactionCollision = 0x2A,       
    eBTaclQosUnacceptableParam = 0x2C,           
    eBTaclQosRejected = 0x2D,                    
    eBTaclChanClassifNotSupported = 0x2E,        
    eBTaclInsuffcientSecurity = 0x2F,            
    eBTaclParamOutOfRange = 0x30,                
    eBTaclRoleSwitchPending = 0x32,              
    eBTaclReservedSlotViolation = 0x34,          
    eBTaclRoleSwitchFailed = 0x35,               
    eBTaclInqRspDataTooLarge = 0x36,             
    eBTaclSimplePairingNotSupported = 0x37,      
    eBTaclHostBusyPairing = 0x38,                
    eBTaclRejNoSuitableChannel = 0x39,           
    eBTaclControllerBusy = 0x3A,                 
    eBTaclUnacceptConnInterval = 0x3B,           
    eBTaclDirectedAdvertisingTimeout = 0x3C,     
    eBTaclConnToutDueToMicFailure = 0x3D,        
    eBTaclConnFailedEstablishment = 0x3E,        
    eBTaclMacConnectionFailed = 0x3F,            
} BTAclDisconnectReason_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 void (* BTAclStateChangedCallback_t)( BTStatus_t xStatus,
                                              const BTBdaddr_t * pxRemoteBdAddr,
                                              BTAclState_t xState,
                                              BTTransport_t xTransport,
                                              BTAclDisconnectReason_t xReason );

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;     
    BTAclStateChangedCallback_t pxAclStateChangedCb;               
} BTCallbacks_t;

typedef struct
{
    BTStatus_t ( * pxBtManagerInit )( const BTCallbacks_t * pxCallbacks );

    BTStatus_t ( * pxBtManagerCleanup )( void );

    BTStatus_t ( * pxEnable )( uint8_t ucGuestMode );

    BTStatus_t ( * pxDisable )( void );

    BTStatus_t ( * pxGetAllDeviceProperties )( void );

    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 )( void );

    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 )( void );

    BTStatus_t ( * pxReadRssi )( const BTBdaddr_t * pxBdAddr );

    BTStatus_t ( * pxGetTxpower )( const BTBdaddr_t * pxBdAddr,
                                   BTTransport_t xTransport );

    const void * ( *pxGetClassicAdapter )( void );

    const void * ( *pxGetLeAdapter )( void );

    uint32_t ( * pxGetLastError )( void );

    BTStatus_t ( * pxGetStackFeaturesSupport )( uint32_t * pulFeatureMask );
} BTInterface_t;

const BTInterface_t * BTGetBluetoothInterface( void );

#endif /* _BT_HAL_MANAGER_H_ */