/**************************************************************************************************
Phyplus Microelectronics Limited confidential and proprietary.
All rights reserved.
IMPORTANT: All rights of this software belong to Phyplus Microelectronics
Limited ("Phyplus"). Your use of this Software is limited to those
specific rights granted under the terms of the business contract, the
confidential agreement, the non-disclosure agreement and any other forms
of agreements as a customer or a partner of Phyplus. You may not use this
Software unless you agree to abide by the terms of these agreements.
You acknowledge that the Software may not be modified, copied,
distributed or disclosed unless embedded on a Phyplus Bluetooth Low Energy
(BLE) integrated circuit, either as a product or is integrated into your
products. Other than for the aforementioned purposes, you may not use,
reproduce, copy, prepare derivative works of, modify, distribute, perform,
display or sell this Software and/or its documentation for any purposes.
YOU FURTHER ACKNOWLEDGE AND AGREE THAT THE SOFTWARE AND DOCUMENTATION ARE
PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY, TITLE,
NON-INFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL
PHYPLUS OR ITS SUBSIDIARIES BE LIABLE OR OBLIGATED UNDER CONTRACT,
NEGLIGENCE, STRICT LIABILITY, CONTRIBUTION, BREACH OF WARRANTY, OR OTHER
LEGAL EQUITABLE THEORY ANY DIRECT OR INDIRECT DAMAGES OR EXPENSES
INCLUDING BUT NOT LIMITED TO ANY INCIDENTAL, SPECIAL, INDIRECT, PUNITIVE
OR CONSEQUENTIAL DAMAGES, LOST PROFITS OR LOST DATA, COST OF PROCUREMENT
OF SUBSTITUTE GOODS, TECHNOLOGY, SERVICES, OR ANY CLAIMS BY THIRD PARTIES
(INCLUDING BUT NOT LIMITED TO ANY DEFENSE THEREOF), OR OTHER SIMILAR COSTS.
**************************************************************************************************/
#ifndef CENTRAL_H
#define CENTRAL_H
#ifdef __cplusplus
extern "C"
{
#endif
/*********************************************************************
* INCLUDES
*/
#include "bcomdef.h"
#include "OSAL.h"
#include "gap.h"
/*********************************************************************
* CONSTANTS
*/
/** @defgroup GAPCENTRALROLE_PROFILE_PARAMETERS GAP Central Role Parameters
* @{
*/
#define GAPCENTRALROLE_IRK 0x400 //!< Identity Resolving Key. Read/Write. Size is uint8[KEYLEN]. Default is all 0, which means that the IRK will be randomly generated.
#define GAPCENTRALROLE_SRK 0x401 //!< Signature Resolving Key. Read/Write. Size is uint8[KEYLEN]. Default is all 0, which means that the SRK will be randomly generated.
#define GAPCENTRALROLE_SIGNCOUNTER 0x402 //!< Sign Counter. Read/Write. Size is uint32. Default is 0.
#define GAPCENTRALROLE_BD_ADDR 0x403 //!< Device's Address. Read Only. Size is uint8[B_ADDR_LEN]. This item is read from the controller.
#define GAPCENTRALROLE_MAX_SCAN_RES 0x404 //!< Maximum number of discover scan results to receive. Default is 0 = unlimited.
/** @} End GAPCENTRALROLE_PROFILE_PARAMETERS */
/**
* Number of simultaneous links with periodic RSSI reads
*/
#ifndef GAPCENTRALROLE_NUM_RSSI_LINKS
#define GAPCENTRALROLE_NUM_RSSI_LINKS 4
#endif
/*********************************************************************
* VARIABLES
*/
/*********************************************************************
* MACROS
*/
/*********************************************************************
* TYPEDEFS
*/
/**
* Central Event Structure
*/
typedef union
{
gapEventHdr_t gap; //!< GAP_MSG_EVENT and status.
gapDeviceInitDoneEvent_t initDone; //!< GAP initialization done.
gapDeviceInfoEvent_t deviceInfo; //!< Discovery device information event structure.
gapDevDiscEvent_t discCmpl; //!< Discovery complete event structure.
gapEstLinkReqEvent_t linkCmpl; //!< Link complete event structure.
gapLinkUpdateEvent_t linkUpdate; //!< Link update event structure.
gapTerminateLinkEvent_t linkTerminate; //!< Link terminated event structure.
} gapCentralRoleEvent_t;
/**
* RSSI Read Callback Function
*/
typedef void (*pfnGapCentralRoleRssiCB_t)
(
uint16 connHandle, //!< Connection handle.
int8 rssi //!< New RSSI value.
);
/**
* Central Event Callback Function
*/
typedef void (*pfnGapCentralRoleEventCB_t)
(
gapCentralRoleEvent_t *pEvent //!< Pointer to event structure.
);
/**
* Central Callback Structure
*/
typedef struct
{
pfnGapCentralRoleRssiCB_t rssiCB; //!< RSSI callback.
pfnGapCentralRoleEventCB_t eventCB; //!< Event callback.
} gapCentralRoleCB_t;
/*********************************************************************
* VARIABLES
*/
/*********************************************************************
* API FUNCTIONS
*/
/*-------------------------------------------------------------------
* Central Profile Public APIs
*/
/**
* @defgroup CENTRAL_PROFILE_API Central Profile API Functions
*
* @{
*/
/**
* @brief Start the device in Central role. This function is typically
* called once during system startup.
*
* @param pAppCallbacks - pointer to application callbacks
*
* @return SUCCESS: Operation successful.
* bleAlreadyInRequestedMode: Device already started.
*/
extern bStatus_t GAPCentralRole_StartDevice( gapCentralRoleCB_t *pAppCallbacks );
/**
* @brief Set a parameter in the Central Profile.
*
* @param param - profile parameter ID: @ref GAPCENTRALROLE_PROFILE_PARAMETERS
* @param len - length of data to write
* @param pValue - pointer to data to write. This is dependent on
* the parameter ID and WILL be cast to the appropriate
* data type.
*
* @return SUCCESS: Operation successful.
* INVALIDPARAMETER: Invalid parameter ID.
*/
extern bStatus_t GAPCentralRole_SetParameter( uint16 param, uint8 len, void *pValue );
/**
* @brief Get a parameter in the Central Profile.
*
* @param param - profile parameter ID: @ref GAPCENTRALROLE_PROFILE_PARAMETERS
* @param pValue - pointer to buffer to contain the read data
*
* @return SUCCESS: Operation successful.
* INVALIDPARAMETER: Invalid parameter ID.
*/
extern bStatus_t GAPCentralRole_GetParameter( uint16 param, void *pValue );
/**
* @brief Terminate a link.
*
* @param connHandle - connection handle of link to terminate
* or @ref GAP_CONN_HANDLE_DEFINES
*
* @return SUCCESS: Terminate started.
* bleIncorrectMode: No link to terminate.
*/
extern bStatus_t GAPCentralRole_TerminateLink( uint16 connHandle );
/**
* @brief Establish a link to a peer device.
*
* @param highDutyCycle - TRUE to high duty cycle scan, FALSE if not
* @param whiteList - determines use of the white list: @ref GAP_WHITELIST_DEFINES
* @param addrTypePeer - address type of the peer device: @ref GAP_ADDR_TYPE_DEFINES
* @param peerAddr - peer device address
*
* @return SUCCESS: started establish link process.
* bleIncorrectMode: invalid profile role.
* bleNotReady: a scan is in progress.
* bleAlreadyInRequestedMode: can?t process now.
* bleNoResources: too many links.
*/
extern bStatus_t GAPCentralRole_EstablishLink( uint8 highDutyCycle, uint8 whiteList,
uint8 addrTypePeer, uint8 *peerAddr );
/**
* @brief Update the link connection parameters.
*
* @param connHandle - connection handle
* @param connIntervalMin - minimum connection interval in 1.25ms units
* @param connIntervalMax - maximum connection interval in 1.25ms units
* @param connLatency - number of LL latency connection events
* @param connTimeout - connection timeout in 10ms units
*
* @return SUCCESS: Connection update started started.
* bleIncorrectMode: No connection to update.
*/
extern bStatus_t GAPCentralRole_UpdateLink( uint16 connHandle, uint16 connIntervalMin,
uint16 connIntervalMax, uint16 connLatency,
uint16 connTimeout );
/**
* @brief Start a device discovery scan.
*
* @param mode - discovery mode: @ref GAP_DEVDISC_MODE_DEFINES
* @param activeScan - TRUE to perform active scan
* @param whiteList - TRUE to only scan for devices in the white list
*
* @return SUCCESS: Discovery scan started.
* bleIncorrectMode: Invalid profile role.
* bleAlreadyInRequestedMode: Not available.
*/
extern bStatus_t GAPCentralRole_StartDiscovery( uint8 mode, uint8 activeScan, uint8 whiteList );
/**
* @brief Cancel a device discovery scan.
*
* @return SUCCESS: Cancel started.
* bleInvalidTaskID: Not the task that started discovery.
* bleIncorrectMode: Not in discovery mode.
*/
extern bStatus_t GAPCentralRole_CancelDiscovery( void );
/**
* @brief Start periodic RSSI reads on a link.
*
* @param connHandle - connection handle of link
* @param period - RSSI read period in ms
*
* @return SUCCESS: Terminate started.
* bleIncorrectMode: No link.
* bleNoResources: No resources.
*/
extern bStatus_t GAPCentralRole_StartRssi( uint16 connHandle, uint16 period );
/**
* @brief Cancel periodic RSSI reads on a link.
*
* @param connHandle - connection handle of link
*
* @return SUCCESS: Operation successful.
* bleIncorrectMode: No link.
*/
extern bStatus_t GAPCentralRole_CancelRssi(uint16 connHandle );
/**
* @}
*/
/*-------------------------------------------------------------------
* TASK API - These functions must only be called by OSAL.
*/
/**
* @internal
*
* @brief Central Profile Task initialization function.
*
* @param taskId - Task ID.
*
* @return void
*/
extern void GAPCentralRole_Init( uint8 taskId );
/**
* @internal
*
* @brief Central Profile Task event processing function.
*
* @param taskId - Task ID
* @param events - Events.
*
* @return events not processed
*/
extern uint16 GAPCentralRole_ProcessEvent( uint8 taskId, uint16 events );
/*********************************************************************
*********************************************************************/
#ifdef __cplusplus
}
#endif
#endif /* CENTRAL_H */