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.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	rtlsPacket_t
	RTLS Packet - Generic structure that will be translated to a specific command. More...

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

#define	CHIP_ID_SIZE 6
	Chip Identifier Size.

#define	HAL_ASSERT_CAUSE_OUT_OF_MEMORY 0x04
	RTLS Assert Error code.

#define	MAX_SAMPLES_SINGLE_CHUNK 32
	Max number of samples reported in a single chunk when using RAW mode.

#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_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_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_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_CMD_TOF_CALIB_NV_READ 0x30
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_CALIBRATE 0x26
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_ENABLE 0x12
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_GET_SEC_SEED 0x10
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_RESULT_DIST 0x06
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_RESULT_RAW 0x08
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_RESULT_STAT 0x07
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_SET_PARAMS 0x11
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_SET_SEC_SEED 0x09
	RTLS Node Manager command.

#define	RTLS_CMD_TOF_SWITCH_ROLE 0x31
	RTLS Node Manager command.

#define	RTLS_CTRL_ALL_EVENTS (RTLS_QUEUE_EVT)
	RTLS Task configuration.

#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_CONN 0x2
	RTLS Application Command Opcode.

#define	RTLS_REQ_ENABLE_SYNC 0x1
	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_TERMINATE_LINK 0x5
	RTLS Application Command Opcode.

#define	RTLS_REQ_UPDATE_CONN_INTERVAL 0x6
	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_TOF_SLAVE = 0x00000008, RTLS_CAP_TOF_PASSIVE = 0x00000010, RTLS_CAP_TOF_MASTER = 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	RTLSCtrl_aoaDisable (void)
	Disables AoA. More...

void	RTLSCtrl_aoaEnable (rtlsAoa_t *aoaControlBlock)
	Enables AoA passing the relevant parameters. More...

void	RTLSCtrl_connInfoEvt (uint8_t *connInfo, uint16_t connInfoLen)
	RTLS Control Connection Info. More...

void	RTLSCtrl_connResultEvt (uint8_t status)
	RTLS Control Connection Results. More...

void	RTLSCtrl_initAoa (uint8_t startAntenna)
	Initialize AoA - has to be called before running AoA. 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_postProcessAoa (rtlsAoa_t *aoaControlBlock, int8_t rssi, uint8_t channel)
	Called at the end of each connection event to extract I/Q samples. More...

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

void	RTLSCtrl_processDataSent (uint8_t status)
	RTLS Application Data Sent. More...

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

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

void	RTLSCtrl_scanResultEvt (rtlsStatus_e status, uint8_t *scanResult, uint8_t size)
	RTLS Control Scan Results. More...

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

void	RTLSCtrl_syncEventNotify (rtlsStatus_e status, uint32_t timeToNextEvent, int8_t rssi, uint8_t channel)
	RTLSCtrl_syncEventNotify. 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...

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_aoaDisable()

void RTLSCtrl_aoaDisable ( void )

Disables AoA.

Returns: none

§ RTLSCtrl_aoaEnable()

void RTLSCtrl_aoaEnable ( rtlsAoa_t * aoaControlBlock )

Enables AoA passing the relevant parameters.

Parameters

aoaControlBlock - AoA information saved by RTLS Control

Returns: none

§ RTLSCtrl_connInfoEvt()

void RTLSCtrl_connInfoEvt	(	uint8_t *	connInfo,
		uint16_t	connInfoLen
	)

RTLS Control Connection Info.

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 ( uint8_t status )

RTLS Control Connection Results.

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

Parameters

status - Whether the connection was formed successfully

§ RTLSCtrl_initAoa()

void RTLSCtrl_initAoa ( uint8_t startAntenna )

Initialize AoA - has to be called before running AoA.

Parameters

startAntenna - start samples with antenna 1 ro 2

Returns: none

§ 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

§ 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_postProcessAoa()

void RTLSCtrl_postProcessAoa	(	rtlsAoa_t *	aoaControlBlock,
		int8_t	rssi,
		uint8_t	channel
	)

Called at the end of each connection event to extract I/Q samples.

Parameters

aoaControlBlock	- AoA information saved by RTLS Control
rssi	- rssi to be reported to RTLS Host
channel	- Channel used

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_processDataSent()

void RTLSCtrl_processDataSent ( uint8_t status )

RTLS Application Data Sent.

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

§ RTLSCtrl_processRtlsPacket()

void RTLSCtrl_processRtlsPacket ( uint8_t * pPkt )

RTLSCtrl_processRtlsPacket.

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_readCalibFromNV()

void RTLSCtrl_readCalibFromNV ( rtlsTof_t * tofControlBlock )

Read calibration From NV.

Parameters

tofControlBlock - pointer to ToF control block

Returns: none

§ RTLSCtrl_scanResultEvt()

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

RTLS Control Scan Results.

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_sendDebugEvent()

void RTLSCtrl_sendDebugEvent	(	uint8_t *	debug_string,
		uint32_t	debug_value
	)

RTLSCtrl_sendDebugEvent.

Send debug info

Parameters

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

§ RTLSCtrl_syncEventNotify()

void RTLSCtrl_syncEventNotify	(	rtlsStatus_e	status,
		uint32_t	timeToNextEvent,
		int8_t	rssi,
		uint8_t	channel
	)

RTLSCtrl_syncEventNotify.

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

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: none

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

§ RTLSUTIL_FREE

§ RTLSUTIL_MALLOC

Function Documentation

§ RTLSCtrl_aoaDisable()

§ RTLSCtrl_aoaEnable()

§ RTLSCtrl_connInfoEvt()

§ RTLSCtrl_connResultEvt()

§ RTLSCtrl_initAoa()

§ RTLSCtrl_loadAndverifyCalibNVParams()

§ RTLSCtrl_malloc()

§ RTLSCtrl_open()

§ RTLSCtrl_outputCalibFromNV()

§ RTLSCtrl_outputTofStat()

§ RTLSCtrl_postProcessAoa()

§ RTLSCtrl_postProcessTof()

§ RTLSCtrl_processDataSent()

§ RTLSCtrl_processRtlsPacket()

§ RTLSCtrl_readCalibFromNV()

§ RTLSCtrl_scanResultEvt()

§ RTLSCtrl_sendDebugEvent()

§ RTLSCtrl_syncEventNotify()

§ RTLSCtrl_writeCalibToNV()

§ RTLSHost_openHostIf()

§ RTLSHost_sendMsg()