This module implements Real Time Localization System (RTLS) Control module. More...

Modules
	RTLS Control Structures

Files
file	rtls_ble.h
	Stack specific BLE structures needed for RTLS Control.

file	rtls_ctrl.h
	RTLS Control module interface.

file	rtls_ctrl_api.h
	This file contains the RTLS Control API's.

file	rtls_ctrl_tof.h
	This file contains the functions and structures specific to ToF post processing.

file	rtls_host.h
	This file contains the host abstraction layer for a RTLS Host.

Data Structures
struct	rtlsConfiguration_t
	RTLS Configuration structure. More...

struct	rtlsCtrlReq_t
	RTLS Control request. More...

struct	rtlsEnableSync_t
	RTLS Enable Sync - This will tell the RTLS Application to start notifying RTLS Control about a specific connection. More...

struct	rtlsGetActiveConnInfo_t
	RTLS Get Active Connection Info - get the connection information for a specific handle. More...

struct	rtlsPacket_t
	RTLS Packet - Generic structure that will be translated to a specific command. More...

struct	rtlsTerminateLinkReq_t
	RTLS terminate link request. More...

struct	rtlsUpdateConnIntReq_t
	RTLS update connection interval request. More...

Macros
#define	CHIP_ID_ADDR ((uint8_t *)(0x50001000 + 0x2E8))
	Chip Identifier Address.

#define	CHIP_ID_SIZE 6
	Chip Identifier Size.

#define	MAX_TOF_SAMPLES_SINGLE_CHUNK 16
	Max Num of Samples.

#define	RTLS_CMD_AOA_ENABLE 0x14
	RTLS Node Manager command.

#define	RTLS_CMD_AOA_RESULT_ANGLE 0x23
	RTLS Node Manager command.

#define	RTLS_CMD_AOA_RESULT_PAIR_ANGLES 0x25
	RTLS Node Manager command.

#define	RTLS_CMD_AOA_RESULT_RAW 0x24
	RTLS Node Manager command.

#define	RTLS_CMD_AOA_SET_PARAMS 0x13
	RTLS Node Manager command.

#define	RTLS_CMD_BLE_LOG_STRINGS_MAX 0x32

#define	RTLS_CMD_CONN_INFO 0x27
	RTLS Node Manager command.

#define	RTLS_CMD_CONN_PARAMS 0x02
	RTLS Node Manager command.

#define	RTLS_CMD_CONNECT 0x03
	RTLS Node Manager command.

#define	RTLS_CMD_GET_ACTIVE_CONN_INFO 0x32
	RTLS Node Manager command.

#define	RTLS_CMD_GET_RTLS_PARAM 0x29
	RTLS Node Manager command.

#define	RTLS_CMD_IDENTIFY 0x00
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED 0x01
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED1 0x06
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED10 0x31
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED2 0x07
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED3 0x08
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED4 0x09
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED5 0x10
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED6 0x11
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED7 0x12
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED8 0x26
	RTLS Node Manager command.

#define	RTLS_CMD_RESERVED9 0x30
	RTLS Node Manager command.

#define	RTLS_CMD_RESET_DEVICE 0x20
	RTLS Node Manager command.

#define	RTLS_CMD_SCAN 0x04
	RTLS Node Manager command.

#define	RTLS_CMD_SCAN_STOP 0x05
	RTLS Node Manager command.

#define	RTLS_CMD_SET_RTLS_PARAM 0x28
	RTLS Node Manager command.

#define	RTLS_CMD_TERMINATE_LINK 0x22
	RTLS Node Manager command.

#define	RTLS_CONNHANDLE_ALL 0xFFFD

#define	RTLS_CONNHANDLE_INVALID 0xFFFF

#define	RTLS_CTRL_ALL_EVENTS (RTLS_QUEUE_EVT)
	RTLS Task configuration.

#define	RTLS_CTRL_ASSERT_CAUSE_INVALID_PARAM 0x02
	RTLS Assert Error code.

#define	RTLS_CTRL_ASSERT_CAUSE_NULL_POINTER_EXCEPT 0x03
	RTLS Assert Error code.

#define	RTLS_CTRL_ASSERT_CAUSE_OUT_OF_MEMORY 0x01
	RTLS Assert Error code.

#define	RTLS_CTRL_REV 0x2

#define	RTLS_CTRL_TASK_PRIORITY 2
	RTLS Task configuration variable.

#define	RTLS_CTRL_TASK_STACK_SIZE 752
	RTLS Task configuration variable.

#define	RTLS_CTRL_TOF_RSSI_THRESHOLD_HYSTERESIS -5
	RSSI Hysteresis threshold.

#define	RTLS_EVT_ASSERT 0x80
	RTLS async event.

#define	RTLS_EVT_CONN_INFO 0x83
	RTLS async event.

#define	RTLS_EVT_DEBUG 0x82
	RTLS async event.

#define	RTLS_EVT_ERROR 0x81
	RTLS async event.

#define	RTLS_FALSE 0
	FALSE.

#define	RTLS_PARAM_2 0x02
	RTLS Param type RTLS_CMD_SET_RTLS_PARAM command.

#define	RTLS_PARAM_3 0x03
	RTLS Param type RTLS_CMD_SET_RTLS_PARAM command.

#define	RTLS_PARAM_CONNECTION_INTERVAL 0x01
	RTLS Param type RTLS_CMD_SET_RTLS_PARAM command.

#define	RTLS_QUEUE_EVT UTIL_QUEUE_EVENT_ID
	Event_Id_30.

#define	RTLS_REQ_AOA_ENABLE 0x7
	RTLS Application Command Opcode.

#define	RTLS_REQ_BLE_LOG_STRINGS_MAX 0x9

#define	RTLS_REQ_CONN 0x2
	RTLS Application Command Opcode.

#define	RTLS_REQ_ENABLE_SYNC 0x1
	RTLS Application Command Opcode.

#define	RTLS_REQ_GET_ACTIVE_CONN_INFO 0x9
	RTLS Application Command Opcode.

#define	RTLS_REQ_SCAN 0x3
	RTLS Application Command Opcode.

#define	RTLS_REQ_SEND_DATA 0x4
	RTLS Application Command Opcode.

#define	RTLS_REQ_SET_AOA_PARAMS 0x6
	RTLS Application Command Opcode.

#define	RTLS_REQ_TERMINATE_LINK 0x5
	RTLS Application Command Opcode.

#define	RTLS_REQ_UPDATE_CONN_INTERVAL 0x8
	RTLS Application Command Opcode.

#define	RTLS_TOF_FREQ_PER_NV_BLOCK 4
	Max Num of frequencies per NV block.

#define	RTLS_TRUE 1
	TRUE.

#define	RTLSUTIL_FREE(pFree)
	RTLSUTIL_FREE memory free without icall. More...

#define	RTLSUTIL_MALLOC(pAlloc, size)
	RTLSUTIL_MALLOC memory allocation without icall. More...

#define	SNV_ID_CAL_DATA_SET BLE_NVID_CUST_START+1

#define	SNV_ID_CAL_PARAMS BLE_NVID_CUST_START

Typedefs
typedef void(*	pfnRtlsAppCb) (uint8_t *cmd)
	Application callback function.

Enumerations
enum	rtlsCapabilities_e { RTLS_CAP_NOT_INITIALIZED = 0x00000000, RTLS_CAP_CM = 0x00000001, RTLS_CAP_AOA_TX = 0x00000002, RTLS_CAP_AOA_RX = 0x00000004, RTLS_CAP_RESERVED1 = 0x00000008, RTLS_CAP_RESERVED2 = 0x00000010, RTLS_CAP_RESERVED3 = 0x00000020, RTLS_CAP_RTLS_SLAVE = 0x00000040, RTLS_CAP_RTLS_MASTER = 0x00000080, RTLS_CAP_RTLS_PASSIVE = 0x00000100 }
	Enumeration for RTLS Capabilities.

enum	rtlsStatus_e { RTLS_SUCCESS, RTLS_FAIL, RTLS_LINK_ESTAB_FAIL, RTLS_LINK_TERMINATED, RTLS_OUT_OF_MEMORY, RTLS_CONFIG_NOT_SUPPORTED, RTLS_ILLEGAL_CMD }
	Enumeration for RTLS Status.

Functions
void	AssertHandler (uint8 assertCause, uint8 assertSubcause)

void	RTLSCtrl_aoaResultEvt (uint16_t connHandle, int8_t rssi, uint8_t channel, uint16_t numIqSamples, uint8_t sampleRate, uint8_t sampleSize, uint8_t sampleCtrl, uint8_t slotDuration, uint8_t numAnt, int8_t *pIQ)
	RTLSCtrl_aoaResultEvt. More...

void	RTLSCtrl_connInfoEvt (uint8_t *connInfo, uint16_t connInfoLen)
	RTLSCtrl_connInfoEvt. More...

void	RTLSCtrl_connResultEvt (uint16_t connHandle, uint8_t status)
	RTLSCtrl_connResultEvt. More...

void	RTLSCtrl_dataSentEvt (uint16_t connHandle, uint8_t status)
	RTLSCtrl_dataSentEvt. More...

rtlsStatus_e	RTLSCtrl_loadAndverifyCalibNVParams (rtlsTof_t *tofControlBlock)
	Verify calibration and load calibration from NV. More...

void *	RTLSCtrl_malloc (uint32_t sz)
	This function will allocate memory, if we were unable to allocate we will report to RTLS Host. More...

void	RTLSCtrl_open (rtlsConfiguration_t *rtlsConfig)
	RTLSCtrl_open. More...

void	RTLSCtrl_outputCalibFromNV (uint8_t cmdId, uint8_t numFreq, uint16_t calibDistance, ToF_BurstStat *pCalibVals)
	Output calibration parameters and values. More...

void	RTLSCtrl_outputTofStat (uint8_t cmdId, uint16_t numFreq, ToF_BurstStat *tofStatArray, uint8_t rssi)
	Output array of ToF_BurstStat. More...

void	RTLSCtrl_postProcessTof (rtlsTof_t *tofControlBlock, int8_t rssi)
	Post process a ToF run. More...

void	RTLSCtrl_readCalibFromNV (rtlsTof_t *tofControlBlock)
	Read calibration From NV. More...

void	RTLSCtrl_rtlsPacketEvt (uint8_t *pPkt)
	RTLSCtrl_rtlsPacketEvt. More...

void	RTLSCtrl_scanResultEvt (rtlsStatus_e status, uint8_t *scanResult, uint8_t size)
	RTLSCtrl_scanResultEvt. More...

void	RTLSCtrl_sendDebugEvt (uint8_t *debug_string, uint32_t debug_value)
	RTLSCtrl_sendDebugEvt. More...

void	RTLSCtrl_syncNotifyEvt (uint16_t connHandle, rtlsStatus_e status, uint32_t timeToNextEvent, int8_t rssi, uint8_t channel)
	RTLSCtrl_syncNotifyEvt. More...

rtlsStatus_e	RTLSCtrl_writeCalibToNV (rtlsTofCalibParams_t calibParams, ToF_BurstStat *pCalibVals)
	Write calibration to NV. More...

void	RTLSHost_openHostIf (pfnRtlsCtrlProcessMsgCb rtlsHostMsgCb)
	This function opens the host interface and registers the application callback. More...

uint8_t	RTLSHost_sendMsg (uint8_t cmdId, uint8_t cmdType, uint8_t *pData, uint16_t dataLen)
	This function is an abstraction of sending messages to a RTLS Host. More...

Variables
char *	rtlsCmd_BleLogStrings []

char *	rtlsReq_BleLogStrings []

Detailed Description

This module implements Real Time Localization System (RTLS) Control module.

Macro Definition Documentation

§ RTLSUTIL_FREE

#define RTLSUTIL_FREE ( pFree )

Value:

{                           \
                                        volatile uint32_t keyHwi; \
                                        volatile uint32_t keySwi; \
                                        keyHwi = Hwi_disable();   \
                                        keySwi = Swi_disable();   \
                                        free(pFree);              \
                                        pFree = NULL;             \
                                        Swi_restore(keySwi);      \
                                        Hwi_restore(keyHwi);      \
                                      }

RTLSUTIL_FREE memory free without icall.

§ RTLSUTIL_MALLOC

#define RTLSUTIL_MALLOC	(	pAlloc,
		size
	)

Value:

{                           \
                                        volatile uint32_t keyHwi; \
                                        volatile uint32_t keySwi; \
                                        keyHwi = Hwi_disable();   \
                                        keySwi = Swi_disable();   \
                                        pAlloc = malloc(size);    \
                                        Swi_restore(keySwi);      \
                                        Hwi_restore(keyHwi);      \
                                      }

RTLSUTIL_MALLOC memory allocation without icall.

Function Documentation

§ RTLSCtrl_aoaResultEvt()

void RTLSCtrl_aoaResultEvt	(	uint16_t	connHandle,
		int8_t	rssi,
		uint8_t	channel,
		uint16_t	numIqSamples,
		uint8_t	sampleRate,
		uint8_t	sampleSize,
		uint8_t	sampleCtrl,
		uint8_t	slotDuration,
		uint8_t	numAnt,
		int8_t *	pIQ
	)

RTLSCtrl_aoaResultEvt.

RTLS Control I/Q samples processing function Results will be output to RTLS Node Manager after processing

Parameters

connHandle	- connection handle
rssi	- rssi for this CTE
channel	- channel this CTE was captured on
numIqSamples-	Number of I/Q samples
sampleRate	- Sampling rate that was used for the run
sampleSize	- Sample Size 1 = 8 bit, 2 = 16 bit
sampleCtrl	- Sampling control flags
numAnt	- Number of Antennas that were used for the run
pIQ	- Pointer to IQ samples

§ RTLSCtrl_connInfoEvt()

void RTLSCtrl_connInfoEvt	(	uint8_t *	connInfo,
		uint16_t	connInfoLen
	)

RTLSCtrl_connInfoEvt.

This function sends connection information and parameters to RTLS Control

Parameters

connInfo	- Connection information
connInfoLen	- Connection Information length (needed to send the packet over NPI)

§ RTLSCtrl_connResultEvt()

void RTLSCtrl_connResultEvt	(	uint16_t	connHandle,
		uint8_t	status
	)

RTLSCtrl_connResultEvt.

This function notifies the RTLS Control that a connection has been formed

Parameters

connHandle	- Connection handle
status	- Whether the connection was formed successfully

§ RTLSCtrl_dataSentEvt()

void RTLSCtrl_dataSentEvt	(	uint16_t	connHandle,
		uint8_t	status
	)

RTLSCtrl_dataSentEvt.

This function is used by the RTLS Application to report the status of a sent packet This is used to let RTLS Control know whether RTLS data has been successfully transmitted

Parameters

status	- SUCCESS or FAILURE for sending data to our peer
connHandle	- Connection handle

§ RTLSCtrl_loadAndverifyCalibNVParams()

rtlsStatus_e RTLSCtrl_loadAndverifyCalibNVParams ( rtlsTof_t * tofControlBlock )

Verify calibration and load calibration from NV.

Parameters

tofControlBlock - pointer to ToF control block

Returns: RTLS status

§ RTLSCtrl_malloc()

void* RTLSCtrl_malloc ( uint32_t sz )

This function will allocate memory, if we were unable to allocate we will report to RTLS Host.

Parameters

sz	- size (Allocated pointer has to be cast)

Returns: none

§ RTLSCtrl_open()

void RTLSCtrl_open ( rtlsConfiguration_t * rtlsConfig )

RTLSCtrl_open.

Used to create and initialize the RTLS Control task

Parameters

rtlsConfig - pointer to the RTLS Application callbacks and configuration

§ RTLSCtrl_outputCalibFromNV()

void RTLSCtrl_outputCalibFromNV	(	uint8_t	cmdId,
		uint8_t	numFreq,
		uint16_t	calibDistance,
		ToF_BurstStat *	pCalibVals
	)

Output calibration parameters and values.

Parameters

cmdId	- RTLS_CMD_TOF_* - command to the host
numFreq	- Needed for size calculation
calibrationOffset	- The distance at which calibration is being performed (will be subtracted from final result)
tofCalArray	- Calibration array

Returns: None

§ RTLSCtrl_outputTofStat()

void RTLSCtrl_outputTofStat	(	uint8_t	cmdId,
		uint16_t	numFreq,
		ToF_BurstStat *	tofStatArray,
		uint8_t	rssi
	)

Output array of ToF_BurstStat.

Parameters

cmdId	- RTLS_CMD_TOF_* - command to the host
numFreq	- needed for size calculation
tofStatArray	- Array to output
rssi	- current rssi

Returns: None

§ RTLSCtrl_postProcessTof()

void RTLSCtrl_postProcessTof	(	rtlsTof_t *	tofControlBlock,
		int8_t	rssi
	)

Post process a ToF run.

Parameters

tofControlBlock	- pointer to ToF information
rssi	- current rssi

Returns: None

§ RTLSCtrl_readCalibFromNV()

void RTLSCtrl_readCalibFromNV ( rtlsTof_t * tofControlBlock )

Read calibration From NV.

Parameters

tofControlBlock - pointer to ToF control block

Returns: none

§ RTLSCtrl_rtlsPacketEvt()

void RTLSCtrl_rtlsPacketEvt ( uint8_t * pPkt )

RTLSCtrl_rtlsPacketEvt.

This function is used by the RTLS Application to notify RTLS Control that a RTLS packet has been received

Parameters

pPkt	- The RTLS packet to parse

§ RTLSCtrl_scanResultEvt()

void RTLSCtrl_scanResultEvt	(	rtlsStatus_e	status,
		uint8_t *	scanResult,
		uint8_t	size
	)

RTLSCtrl_scanResultEvt.

This function notifies the RTLS Control that a connection has been formed

Parameters

scanResult	- Pointer to scan results array
size	- Size of scanResults array
status	- scanResults status

§ RTLSCtrl_sendDebugEvt()

void RTLSCtrl_sendDebugEvt	(	uint8_t *	debug_string,
		uint32_t	debug_value
	)

RTLSCtrl_sendDebugEvt.

Send debug info

Parameters

debug_string	- 32 bytes debug string
debug_value	- 32 bits debug value

§ RTLSCtrl_syncNotifyEvt()

void RTLSCtrl_syncNotifyEvt	(	uint16_t	connHandle,
		rtlsStatus_e	status,
		uint32_t	timeToNextEvent,
		int8_t	rssi,
		uint8_t	channel
	)

RTLSCtrl_syncNotifyEvt.

Synchronization function provided to the Application by RTLS Control This is the function that the application will be calling when a sync event is in place e.g BLE Connection Event

Parameters

connHandle	- connection handle
timeToNextEvent	- the time until the next sync event
rssi	- rssi measurement against the RTLS Slave
channel	- the channel on which the syncEvent was received
status

§ RTLSCtrl_writeCalibToNV()

rtlsStatus_e RTLSCtrl_writeCalibToNV	(	rtlsTofCalibParams_t	calibParams,
		ToF_BurstStat *	pCalibVals
	)

Write calibration to NV.

Parameters

pCalibVals	- pointer to calibration values
calibParams	- calibration parameters

Returns: RTLS status

§ RTLSHost_openHostIf()

void RTLSHost_openHostIf ( pfnRtlsCtrlProcessMsgCb rtlsHostMsgCb )

This function opens the host interface and registers the application callback.

Parameters

rtlsHostMsgCb - Callback to use when a message arrives

Returns: none

§ RTLSHost_sendMsg()

uint8_t RTLSHost_sendMsg	(	uint8_t	cmdId,
		uint8_t	cmdType,
		uint8_t *	pData,
		uint16_t	dataLen
	)

This function is an abstraction of sending messages to a RTLS Host.

Parameters

cmdId	- RTLS Cmd Id
cmdType	- Async/Sync message
pData	- Pointer to message data
dataLen	- Length of data in pData

Returns: status - 0 = success, 1 = failed

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

§ RTLSUTIL_FREE

§ RTLSUTIL_MALLOC

Function Documentation

§ RTLSCtrl_aoaResultEvt()

§ RTLSCtrl_connInfoEvt()

§ RTLSCtrl_connResultEvt()

§ RTLSCtrl_dataSentEvt()

§ RTLSCtrl_loadAndverifyCalibNVParams()

§ RTLSCtrl_malloc()

§ RTLSCtrl_open()

§ RTLSCtrl_outputCalibFromNV()

§ RTLSCtrl_outputTofStat()

§ RTLSCtrl_postProcessTof()

§ RTLSCtrl_readCalibFromNV()

§ RTLSCtrl_rtlsPacketEvt()

§ RTLSCtrl_scanResultEvt()

§ RTLSCtrl_sendDebugEvt()

§ RTLSCtrl_syncNotifyEvt()

§ RTLSCtrl_writeCalibToNV()

§ RTLSHost_openHostIf()

§ RTLSHost_sendMsg()