The main header for BltTofApi. Includes all interface functions, the config struct and the declaration of the config struct organisation. More...

#include <bta_status.h>
#include <bta_frame.h>
#include <bta_filters.h>
#include <bta_discovery.h>
#include <bta_flash_update.h>

Data Structures
struct	BTA_Config
	Configuration structure to be passed with BTAopen. More...

struct	BTA_GrabbingConfig
	Configuration structure to be passed with BTAstartDiscovery. More...

struct	BTA_ConfigStructOrg
	This struct is used for the representation of the BTA_Config struct. Programming languages that don't use header files are able to query the elements of BTA_Config generically. More...

Macros
#define	BTA_CONFIG_STRUCT_STRIDE 8
	The BTA_Config shall be 8-byte aligned.

Typedefs
typedef void *	BTA_Handle
	The handle to hold the instance created by BTAopen.

typedef int8_t *	msg

typedef BTA_Status	status

typedef BTA_Frame *	frame

typedef uint8_t	percentage

typedef enum BTA_QueueMode	BTA_QueueMode
	Enumerator with queuing modes.

typedef enum BTA_LibParam	BTA_LibParam
	Enumerator with runtime configuration parameters for the library. The behaviour of the library can be changed by setting various LibParams. Some information about the state of the library can be retrieved by reading various LibParams. Never are they affecting the devices configuration (registers).

typedef struct BTA_Config	BTA_Config
	Configuration structure to be passed with BTAopen.

typedef struct BTA_GrabbingConfig	BTA_GrabbingConfig
	Configuration structure to be passed with BTAstartDiscovery.

typedef struct BTA_ConfigStructOrg	BTA_ConfigStructOrg
	This struct is used for the representation of the BTA_Config struct. Programming languages that don't use header files are able to query the elements of BTA_Config generically.

Enumerations
enum	BTA_QueueMode { BTA_QueueModeDoNotQueue = 0, BTA_QueueModeDropOldest = 1, BTA_QueueModeDropCurrent = 2, BTA_QueueModeAvoidDrop = 3 }
	Enumerator with queuing modes. More...

enum	BTA_LibParam { BTA_LibParamKeepAliveMsgInterval, BTA_LibParamCrcControlEnabled, BTA_LibParamStreamTotalFrameCount, BTA_LibParamStreamAutoPlaybackSpeed, BTA_LibParamStreamPos, BTA_LibParamStreamPosIncrement, BTA_LibParamEnableTestPattern, BTA_LibParamPauseCaptureThread }
	Enumerator with runtime configuration parameters for the library. The behaviour of the library can be changed by setting various LibParams. Some information about the state of the library can be retrieved by reading various LibParams. Never are they affecting the devices configuration (registers). More...

Functions
typedef	void (1 *FN_BTA_InfoEvent)(BTA_Status status
	Callback function to report on informative events. The implementation of this function in the application must copy the relevant data and return immediately. The parameter 'verbosity' in BTA_Config can be used to turn on/off certain events. More...

typedef	int (1 *FN_BTA_ProgressReport)(BTA_Status status
	Callback function to report status and progress during transfer and programming. More...

BTA_Status	BTAgetVersion (uint32_t verMaj, uint32_t verMin, uint32_t verNonFun, uint8_t buildDateTime, uint32_t buildDateTimeLen, uint16_t supportedDeviceTypes, uint32_t supportedDeviceTypesLen)
	For querying API version. More...

BTA_Status	BTAinitDiscoveryConfig (BTA_DiscoveryConfig *config)
	Fills the discovery config structure with standard values. More...

BTA_Status	BTAstartDiscovery (BTA_DiscoveryConfig discoveryConfig, FN_BTA_DeviceFound deviceFound, FN_BTA_InfoEvent infoEvent, BTA_Handle handle)
	Starts the discovery of devices. If possible, broadcast messages are transmitted otherwise all possible connections are tested. More...

BTA_Status	BTAstopDiscovery (BTA_Handle *handle)
	Stops the discovery of devices. More...

BTA_ConfigStructOrg *	BTAgetConfigStructOrg (uint32_t fieldCount, uint8_t bytesPerField)
	With this function a literal description of the config struct can be retrieved. In programming languages which do not support header files it can be used to allocate and fill the BTA_Config struct. More...

BTA_Status	BTAinitConfig (BTA_Config *config)
	Fills the config structure with standard values. More...

BTA_Status	BTAopen (BTA_Config config, BTA_Handle handle)
	Establishes a connection to the device and returns a handle. More...

BTA_Status	BTAclose (BTA_Handle *handle)
	Disconnects from the sensor and closes the handle. More...

BTA_Status	BTAgetDeviceInfo (BTA_Handle handle, BTA_DeviceInfo **deviceInfo)
	For querying information about the device. If successful, BTAfreeDeviceInfo must be called afterwards. More...

BTA_Status	BTAfreeDeviceInfo (BTA_DeviceInfo *deviceInfo)
	For freeing the device information structure. More...

uint8_t	BTAisRunning (BTA_Handle handle)
	Queries whether the handle is open and background threads are running correctly. More...

uint8_t	BTAisConnected (BTA_Handle handle)
	Queries whether the library has a valid connection to the sensor. More...

BTA_Status	BTAsetFrameMode (BTA_Handle handle, BTA_FrameMode frameMode)
	Allows to set a BTA_FrameMode which defines the data delivered by the sensor. The device and/or the SDK is configured depending on the frame mode, so that the desired channels are included in each BTA_Frame. More...

BTA_Status	BTAcloneFrame (BTA_Frame frameSrc, BTA_Frame *frameDst)
	Helper function to clone/duplicate/deep-copy a BTA_Frame structure. If successful, BTAfreeFrame must be called on frameDst afterwards. More...

BTA_Status	BTAgetFrame (BTA_Handle handle, BTA_Frame **frame, uint32_t timeout)
	Actively requests a frame. The device-specific library implementation defines if. More...

BTA_Status	BTAfreeFrame (BTA_Frame **frame)
	Helper function to free a BTA_Frame structure. More...

BTA_Status	BTAgetSerializedLength (BTA_Frame frame, uint32_t frameSerializedLen)
	Helper function to calculate the length of a frame in serialized form; needed for BTAserializeFrame. More...

BTA_Status	BTAserializeFrame (BTA_Frame frame, uint8_t frameSerialized, uint32_t *frameSerializedLen)
	Helper function to convert a BTA_Frame structure into a serialized stream; useful for recording frames to files. More...

BTA_Status	BTAdeserializeFrame (BTA_Frame *frame, uint8_t frameSerialized, uint32_t *frameSerializedLen)
	Helper function to convert a serialized stream into a BTA_Frame structure; useful for replaying recorded frames from files. More...

BTA_Status	BTAgetDistances (BTA_Frame frame, void distBuffer, BTA_DataFormat dataFormat, BTA_Unit unit, uint16_t xRes, uint16_t *yRes)
	Convenience function for extracting distances from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with distance data present in the frame, an error is returned. More...

BTA_Status	BTAgetAmplitudes (BTA_Frame frame, void ampBuffer, BTA_DataFormat dataFormat, BTA_Unit unit, uint16_t xRes, uint16_t *yRes)
	Convenience function for extracting amplitudes from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with amplitude data present in the frame, an error is returned. More...

BTA_Status	BTAgetFlags (BTA_Frame frame, void flagBuffer, BTA_DataFormat dataFormat, BTA_Unit unit, uint16_t xRes, uint16_t *yRes)
	Convenience function for extracting flags from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with flag data present in the frame, an error is returned. More...

BTA_Status	BTAgetXYZcoordinates (BTA_Frame frame, void xBuffer, void yBuffer, void zBuffer, BTA_DataFormat dataFormat, BTA_Unit unit, uint16_t xRes, uint16_t *yRes)
	Convenience function for extracting the 3D-coordinates from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there are not 3 channels with coordinate data present in the sensor data, an error is returned. More...

BTA_Status	BTAgetColors (BTA_Frame frame, void colorBuffer, BTA_DataFormat dataFormat, BTA_Unit unit, uint16_t xRes, uint16_t *yRes)
	Convenience function for extracting colors from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with color data present in the frame, an error is returned. More...

BTA_Status	BTAgetMetadata (BTA_Channel channel, uint32_t metadataId, void metadata, uint32_t metadataLen)
	Convenience function for extracting metadata from a provided channel. It simply returns the pointer and the length of the data. The same data can be accessed directly going through the BTA_Channel structure. If there is no metadata with the right id present in the channel, an error is returned. More...

BTA_Status	BTAsetIntegrationTime (BTA_Handle handle, uint32_t integrationTime)
	Facilitates setting the integration time for the default capture sequence(s) More...

BTA_Status	BTAgetIntegrationTime (BTA_Handle handle, uint32_t *integrationTime)
	Facilitates the retrieval of the current integration time of the default capture sequence(s) More...

BTA_Status	BTAsetFrameRate (BTA_Handle handle, float frameRate)
	Facilitates setting the frame rate for the default capture sequence. More...

BTA_Status	BTAgetFrameRate (BTA_Handle handle, float *frameRate)
	Facilitates the retrieval of the current theoretical frame rate of the default capture sequence(s) More...

BTA_Status	BTAsetModulationFrequency (BTA_Handle handle, uint32_t modulationFrequency)
	Facilitates setting the modulation frequency for the default capture sequence(s) More...

BTA_Status	BTAgetModulationFrequency (BTA_Handle handle, uint32_t *modulationFrequency)
	Facilitates the retrieval of the current theoretical frame rate of the default capture sequence(s) More...

BTA_Status	BTAsetGlobalOffset (BTA_Handle handle, float globalOffset)
	Function for setting the distance offset being applied to all pixels equally. It is, for all current devices, valid for the currently set modulation frequency. It can only be set for predefined modulation frequencies (see device’s SUM). More...

BTA_Status	BTAgetGlobalOffset (BTA_Handle handle, float *globalOffset)
	Function for getting the distance offset being applied to all pixels equally. It is, for all current devices, valid for the currently set modulation frequency. When changing the modulation frequency, the global offset changes. More...

BTA_Status	BTAreadRegister (BTA_Handle handle, uint32_t address, uint32_t data, uint32_t registerCount)
	Reads registers from the device/SDK. More...

BTA_Status	BTAwriteRegister (BTA_Handle handle, uint32_t address, uint32_t data, uint32_t registerCount)
	Writes registers to the device/SDK. More...

BTA_Status	BTAsetLibParam (BTA_Handle handle, BTA_LibParam libParam, float value)
	Function for setting a parameter for the library. Library parameters do not directly affect the camera's configuration. More...

BTA_Status	BTAgetLibParam (BTA_Handle handle, BTA_LibParam libParam, float *value)
	Function for getting a parameter from the library. More...

BTA_Status	BTAsendReset (BTA_Handle handle)
	Initiates a reset of the device. More...

BTA_Status	BTAflashUpdate (BTA_Handle handle, BTA_FlashUpdateConfig *flashUpdateConfig, FN_BTA_ProgressReport progressReport)
	Allows sending large data to the device. Mainly this is used for sending calibration data and firmware updates. This function handles the complete transfer of the file and blocks during transmission. If possible, this function performs its task in a way that allows the OS to regain control periodically, i.e. it uses blocking functions in a fine granularity. The callback function is called (if not null) in the following cases: More...

BTA_Status	BTAfirmwareUpdate (BTA_Handle handle, const uint8_t *filename, FN_BTA_ProgressReport progressReport)
	Convenience function for doing a firmware update. Uses BTAflashUpdate() internally. More...

BTA_Status	BTAwigglingUpdate (BTA_Handle handle, const uint8_t *filename, FN_BTA_ProgressReport progressReport)
	Convenience function for doing a firmware update. Uses BTAflashUpdate() internally. More...

BTA_Status	BTAfpnUpdate (BTA_Handle handle, const uint8_t *filename, FN_BTA_ProgressReport progressReport)
	Convenience function for doing a firmware update. Uses BTAflashUpdate() internally. More...

BTA_Status	BTAfppnUpdate (BTA_Handle handle, const uint8_t *filename, FN_BTA_ProgressReport progressReport)
	Convenience function for doing a firmware update. Uses BTAflashUpdate() internally. More...

BTA_Status	BTAflashRead (BTA_Handle handle, BTA_FlashUpdateConfig *flashUpdateConfig, FN_BTA_ProgressReport progressReport)
	Allows reading large data from the device. This function handles the complete transfer of the file and blocks during transmission. If possible, this function performs its task in a way that allows the OS to regain control periodically, i.e. it uses blocking functions in a fine granularity. The callback function is called (if not null) in the following cases: More...

BTA_Status	BTAwriteCurrentConfigToNvm (BTA_Handle handle)
	Writes the current configuration (i.e. register values) to non-volatile memory. More...

BTA_Status	BTArestoreDefaultConfig (BTA_Handle handle)
	Erases the register settings previously stored with BTAwriteCurrentConfigToNvm (May require rebbot for loading default values) More...

BTA_Status	BTAaddFilter (BTA_Handle handle, BTA_FltConfig fltConfig, BTA_FltType fltType, BTA_FltHandle fltHandle)
	(The development of filter functionality is still in progress!) Instantiates the specified filter wih specified parameters and adds it at the end of the filter processing queue More...

BTA_Status	BTAremoveFilter (BTA_Handle handle, BTA_FltHandle fltHandle)
	(The development of filter functionality is still in progress!) Removes the last filter added More...

BTA_Status	BTAinitGrabbingConfig (BTA_GrabbingConfig *config)
	Fills the grab config structure with standard values. More...

BTA_Status	BTAstartGrabbing (BTA_Handle handle, BTA_GrabbingConfig *config)
	Issues the library to grab (or stop grabbing) all the frames and store them to the file provided in the config. When connected to USB (P100) the capture thread must be running or the BTAgetFrame must be called frequently in order for the library to grab frames. More...

BTA_Status	BTAstatusToString (BTA_Status status, char *statusString, uint16_t statusStringLen)
	A convenience function to convert a BTA_Status into a string. More...

BTA_Status	BTAeventIdToString (BTA_EventId eventId, char *eventIdString, uint16_t eventIdStringLen)
	Deprecated. Use BTAstatusToString.

BTA_Status	BTAsetKeepAliveMsgInterval (BTA_Handle handle, float interval)
	DEPRECATED Please use LibParam BTA_LibParamKeepAliveMsgInterval instead.

BTA_Status	BTAsetControlCrcEnabled (BTA_Handle handle, uint8_t enabled)
	DEPRECATED Please use LibParam BTA_LibParamCrcControlEnabled instead.

Variables
BTA_ConfigStructOrg	btaConfigStructOrg []
	This struct contains information about the BTA_Config struct.

const uint32_t	btaConfigStructOrgLen
	The size of the struct containing information about the BTA_Config struct.

Detailed Description

The main header for BltTofApi. Includes all interface functions, the config struct and the declaration of the config struct organisation.

Version: 2.2.4

Copyright Bluetechnix 2016

Author: Alex Falkensteiner

Enumeration Type Documentation

enum BTA_LibParam

Enumerator with runtime configuration parameters for the library. The behaviour of the library can be changed by setting various LibParams. Some information about the state of the library can be retrieved by reading various LibParams. Never are they affecting the devices configuration (registers).

Enumerator
BTA_LibParamKeepAliveMsgInterval	The interval in seconds. If no communication during this time, a keep alive is sent. (Supported only by Ethernet cameras).
BTA_LibParamCrcControlEnabled	Set > 0 in order to activate CRC sums for the control connection. (Supported only by Ethernet cameras).
BTA_LibParamStreamTotalFrameCount	Readonly. Contains the total amount of frames loaded from bltstream file.
BTA_LibParamStreamAutoPlaybackSpeed	Set > 0 in order to activate playback at recording rate times this factor. Set to 0 to pause playback.
BTA_LibParamStreamPos	Get and set the index in the bltstream file. The first frame has index 0. If set, BTA_LibParamStreamAutoPlaybackSpeed is set to 0.
BTA_LibParamStreamPosIncrement	Writeonly. Set the increment to which position to jump to in the bltstream file. If set, BTA_LibParamStreamAutoPlaybackSpeed is set to 0.
BTA_LibParamEnableTestPattern	override camera data with test data: 0: Disabled > 0: Testpattern depending on the connected interface
BTA_LibParamPauseCaptureThread	Set > 0 in order to pause internal capture thread. It saves CPU and/or bandwith, depending on the implementation and interface.

enum BTA_QueueMode

Enumerator with queuing modes.

Enumerator
BTA_QueueModeDoNotQueue	No queueing.
BTA_QueueModeDropOldest	Before an overflow, the oldest item in the queue is removed.
BTA_QueueModeDropCurrent	When full, the queue remains unchanged.
BTA_QueueModeAvoidDrop	When full, the equeue function returns an error to the producer (do not use in BTAopen()!)

Function Documentation

BTA_Status BTAaddFilter	(	BTA_Handle	handle,
		BTA_FltConfig *	fltConfig,
		BTA_FltType	fltType,
		BTA_FltHandle *	fltHandle
	)

(The development of filter functionality is still in progress!) Instantiates the specified filter wih specified parameters and adds it at the end of the filter processing queue

Parameters

handle	Handle of the device to be used
fltConfig	Pointer to the structure containing the parameters for the filter
fltType	Enum value denoting which filter implementation to add
fltHandle	The handle to hold the filter instance on return

Returns: Please refer to bta_status.h

BTA_Status BTAcloneFrame	(	BTA_Frame *	frameSrc,
		BTA_Frame **	frameDst
	)

Helper function to clone/duplicate/deep-copy a BTA_Frame structure. If successful, BTAfreeFrame must be called on frameDst afterwards.

Parameters

frameSrc	The pointer to the frame to be copied
frameDst	The pointer to the new duplicated frame

Returns: Please refer to bta_status.h

BTA_Status BTAclose ( BTA_Handle * handle )

Disconnects from the sensor and closes the handle.

Parameters

handle Pointer to the handle of the device to be closed; points to null on return

Returns: Please refer to bta_status.h

BTA_Status BTAdeserializeFrame	(	BTA_Frame **	frame,
		uint8_t *	frameSerialized,
		uint32_t *	frameSerializedLen
	)

Helper function to convert a serialized stream into a BTA_Frame structure; useful for replaying recorded frames from files.

Parameters

frame	Double pointer to the deserialized frame on return. Don't forget to call BTAfreeFrame.
frameSerialized	Buffer that contains the frame data
frameSerializedLen	Pointer to length of the buffer frameSerialized; number of bytes parsed on return

Returns: Please refer to bta_status.h

BTA_Status BTAfirmwareUpdate	(	BTA_Handle	handle,
		const uint8_t *	filename,
		FN_BTA_ProgressReport	progressReport
	)

Convenience function for doing a firmware update. Uses BTAflashUpdate() internally.

Parameters

handle	Handle of the device to be used
filename	Name of the binary file
progressReport	Callback function for reporting the status and progress during transfer and programming. Can be null

Returns: Please refer to bta_status.h

BTA_Status BTAflashRead	(	BTA_Handle	handle,
		BTA_FlashUpdateConfig *	flashUpdateConfig,
		FN_BTA_ProgressReport	progressReport
	)

Allows reading large data from the device. This function handles the complete transfer of the file and blocks during transmission. If possible, this function performs its task in a way that allows the OS to regain control periodically, i.e. it uses blocking functions in a fine granularity. The callback function is called (if not null) in the following cases:

An error occurs -> report error status ignoring percentage.
An transmission starts -> report BTA_StatusOk with percentage 0%.

An transmission ends -> report BTA_StatusOk with percentage 100%. (–> so the callback will always be used at least once and at least twice in case of success). During transmission, progress is reported repeatedly when possible (report BTA_StatusOk with percentage).

Parameters

handle	Handle of the device to be used
flashUpdateConfig	Must contain the flash target and flash id to read from and optionally the flash address. Must also have have the pointer data with preallocated space denoted in dataLen. On return it contains the data read and its actual length.
progressReport	Callback function for reporting the status and progress during transfer

Returns: Please refer to bta_status.h

BTA_Status BTAflashUpdate	(	BTA_Handle	handle,
		BTA_FlashUpdateConfig *	flashUpdateConfig,
		FN_BTA_ProgressReport	progressReport
	)

Allows sending large data to the device. Mainly this is used for sending calibration data and firmware updates. This function handles the complete transfer of the file and blocks during transmission. If possible, this function performs its task in a way that allows the OS to regain control periodically, i.e. it uses blocking functions in a fine granularity. The callback function is called (if not null) in the following cases:

An error occurs -> report error status ignoring percentage.
An transmission starts -> report BTA_StatusOk with percentage 0%.

An transmission ends -> report BTA_StatusOk with percentage 100%. (–> so the callback will always be used at least once and at least twice in case of success). During transmission, progress is reported repeatedly when possible (report BTA_StatusOk with percentage).

Parameters

handle	Handle of the device to be used
flashUpdateConfig	Contains the data and all the necessary information for handling it
progressReport	Callback function for reporting the status and progress during transfer and programming

Returns: Please refer to bta_status.h

BTA_Status BTAfpnUpdate	(	BTA_Handle	handle,
		const uint8_t *	filename,
		FN_BTA_ProgressReport	progressReport
	)

Convenience function for doing a firmware update. Uses BTAflashUpdate() internally.

Parameters

handle	Handle of the device to be used
filename	Name of the binary file
progressReport	Callback function for reporting the status and progress during transfer and programming. Can be null

Returns: Please refer to bta_status.h

BTA_Status BTAfppnUpdate	(	BTA_Handle	handle,
		const uint8_t *	filename,
		FN_BTA_ProgressReport	progressReport
	)

Convenience function for doing a firmware update. Uses BTAflashUpdate() internally.

Parameters

handle	Handle of the device to be used
filename	Name of the binary file
progressReport	Callback function for reporting the status and progress during transfer and programming. Can be null

Returns: Please refer to bta_status.h

BTA_Status BTAfreeDeviceInfo ( BTA_DeviceInfo * deviceInfo )

For freeing the device information structure.

Parameters

deviceInfo Pointer to structure to be freed

BTA_Status BTAfreeFrame ( BTA_Frame ** frame )

Helper function to free a BTA_Frame structure.

Parameters

frame The pointer to the frame to be freed; points to null on return

Returns: Please refer to bta_status.h

BTA_Status BTAgetAmplitudes	(	BTA_Frame *	frame,
		void **	ampBuffer,
		BTA_DataFormat *	dataFormat,
		BTA_Unit *	unit,
		uint16_t *	xRes,
		uint16_t *	yRes
	)

Convenience function for extracting amplitudes from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with amplitude data present in the frame, an error is returned.

Parameters

frame	The frame from which to extract the data
ampBuffer	Pointer to the amplitudes on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'ampBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'ampBuffer'
xRes	Pointer to the number of columns of 'ampBuffer'
yRes	Pointer to the number of rows of 'ampBuffer'

Returns: Please refer to bta_status.h

BTA_Status BTAgetColors	(	BTA_Frame *	frame,
		void **	colorBuffer,
		BTA_DataFormat *	dataFormat,
		BTA_Unit *	unit,
		uint16_t *	xRes,
		uint16_t *	yRes
	)

Convenience function for extracting colors from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with color data present in the frame, an error is returned.

Parameters

frame	The frame from which to extract the data
colorBuffer	Pointer to the colors on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'colorBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'colorBuffer'
xRes	Pointer to the number of columns of 'colorBuffer'
yRes	Pointer to the number of rows of 'colorBuffer'

Returns: Please refer to bta_status.h

BTA_ConfigStructOrg* BTAgetConfigStructOrg	(	uint32_t *	fieldCount,
		uint8_t *	bytesPerField
	)

With this function a literal description of the config struct can be retrieved. In programming languages which do not support header files it can be used to allocate and fill the BTA_Config struct.

Parameters

fieldCount	The number of elements (config struct fields) in the result on return
bytesPerField	The number of bytes per element (config struct field) in the result on return

BTA_Status BTAgetDeviceInfo	(	BTA_Handle	handle,
		BTA_DeviceInfo **	deviceInfo
	)

For querying information about the device. If successful, BTAfreeDeviceInfo must be called afterwards.

Parameters

handle	Handle of the device to be used
deviceInfo	Pointer to pointer to structure with information about the device on return

BTA_Status BTAgetDistances	(	BTA_Frame *	frame,
		void **	distBuffer,
		BTA_DataFormat *	dataFormat,
		BTA_Unit *	unit,
		uint16_t *	xRes,
		uint16_t *	yRes
	)

Convenience function for extracting distances from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with distance data present in the frame, an error is returned.

Parameters

frame	The frame from which to extract the data
distBuffer	Pointer to the distances on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'distBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'distBuffer'
xRes	Pointer to the number of columns of 'distBuffer'
yRes	Pointer to the number of rows of 'distBuffer'

Returns: Please refer to bta_status.h

BTA_Status BTAgetFlags	(	BTA_Frame *	frame,
		void **	flagBuffer,
		BTA_DataFormat *	dataFormat,
		BTA_Unit *	unit,
		uint16_t *	xRes,
		uint16_t *	yRes
	)

Convenience function for extracting flags from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there is no channel with flag data present in the frame, an error is returned.

Parameters

frame	The frame from which to extract the data
flagBuffer	Pointer to the flags on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'flagBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'flagBuffer'
xRes	Pointer to the number of columns of 'flagBuffer'
yRes	Pointer to the number of rows of 'flagBuffer'

Returns: Please refer to bta_status.h

BTA_Status BTAgetFrame	(	BTA_Handle	handle,
		BTA_Frame **	frame,
		uint32_t	timeout
	)

Actively requests a frame. The device-specific library implementation defines if.

it triggers the capturing of a new frame, or

it returns a queued frame / it waits for the next frame. If successful, BTAfreeFrame must be called afterwards.

Parameters

handle	Handle of the device to be used
frame	Pointer to frame (null if failed) on return (needs to be freed with BTAfreeFrame)
timeout	Timeout to wait if no frame is yet available in [ms]. If timeout == 0 the function waits endlessly for a frame from the device.

Returns: Please refer to bta_status.h

BTA_Status BTAgetFrameRate	(	BTA_Handle	handle,
		float *	frameRate
	)

Facilitates the retrieval of the current theoretical frame rate of the default capture sequence(s)

Parameters

handle	Handle of the device to be used
frameRate	Pointer containing the frame rate in [Hz] on return

Returns: Please refer to bta_status.h

BTA_Status BTAgetGlobalOffset	(	BTA_Handle	handle,
		float *	globalOffset
	)

Function for getting the distance offset being applied to all pixels equally. It is, for all current devices, valid for the currently set modulation frequency. When changing the modulation frequency, the global offset changes.

Parameters

handle	Handle of the device to be used
globalOffset	Pointer to hold offset in mm

Returns: Please refer to bta_status.h

BTA_Status BTAgetIntegrationTime	(	BTA_Handle	handle,
		uint32_t *	integrationTime
	)

Facilitates the retrieval of the current integration time of the default capture sequence(s)

Parameters

handle	Handle of the device to be used
integrationTime	Pointer containing the integration time in [us] on return

Returns: Please refer to bta_status.h

BTA_Status BTAgetLibParam	(	BTA_Handle	handle,
		BTA_LibParam	libParam,
		float *	value
	)

Function for getting a parameter from the library.

Parameters

handle	Handle of the device to be used
libParam	Identifier for the parameter (consult the support wiki for a description of its function)
value	On return it points to the value of the library parameter

Returns: Please refer to bta_status.h

BTA_Status BTAgetMetadata	(	BTA_Channel *	channel,
		uint32_t	metadataId,
		void **	metadata,
		uint32_t *	metadataLen
	)

Convenience function for extracting metadata from a provided channel. It simply returns the pointer and the length of the data. The same data can be accessed directly going through the BTA_Channel structure. If there is no metadata with the right id present in the channel, an error is returned.

Parameters

channel	The channel from which to extract the metadata
colorBuffer	Pointer to the colors on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'colorBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'colorBuffer'
xRes	Pointer to the number of columns of 'colorBuffer'
yRes	Pointer to the number of rows of 'colorBuffer'

Returns: Please refer to bta_status.h

BTA_Status BTAgetModulationFrequency	(	BTA_Handle	handle,
		uint32_t *	modulationFrequency
	)

Facilitates the retrieval of the current theoretical frame rate of the default capture sequence(s)

Parameters

handle	Handle of the device to be used
modulationFrequency	Pointer containing the modulation frequency in [Hz] on return

Returns: Please refer to bta_status.h

BTA_Status BTAgetSerializedLength	(	BTA_Frame *	frame,
		uint32_t *	frameSerializedLen
	)

Helper function to calculate the length of a frame in serialized form; needed for BTAserializeFrame.

Parameters

frame	The pointer to the frame to be serialized
frameSerializedLen	Pointer to the length of the (to be) serialized frame on return.

Returns: Please refer to bta_status.h

BTA_Status BTAgetVersion	(	uint32_t *	verMaj,
		uint32_t *	verMin,
		uint32_t *	verNonFun,
		uint8_t *	buildDateTime,
		uint32_t	buildDateTimeLen,
		uint16_t *	supportedDeviceTypes,
		uint32_t *	supportedDeviceTypesLen
	)

For querying API version.

Parameters

verMaj	If not null it points to the major firmware version of the device on return
verMin	If not null it points to the minor firmware version of the device on return
verNonFun	If not null it points to the non functional firmware version of the device on return
buildDateTime	A char array allocated by the caller containing the date/time string (ASCII) of build on return (can be left null)
buildDateTimeLen	Size of the preallocated buffer behind buildDateTime in [byte]
supportedDeviceTypes	Array allocated by the caller containing the codes of all devices supported by a specifiy BTA implementation on return (can be left null)
supportedDeviceTypesLen	Pointer to size of supportedDeviceTypes (the number of supported devices); on return it contains number of supported device types

Returns: Please refer to bta_status.h

BTA_Status BTAgetXYZcoordinates	(	BTA_Frame *	frame,
		void **	xBuffer,
		void **	yBuffer,
		void **	zBuffer,
		BTA_DataFormat *	dataFormat,
		BTA_Unit *	unit,
		uint16_t *	xRes,
		uint16_t *	yRes
	)

Convenience function for extracting the 3D-coordinates from a provided frame. It simply returns the pointer and copies some information. The same data can be accessed directly going through the BTA_Frame structure. If there are not 3 channels with coordinate data present in the sensor data, an error is returned.

Parameters

frame	The frame from which to extract the data
xBuffer	A pointer to the cartesian x coordinates on return (null on error)
yBuffer	A pointer to the cartesian y coordinates on return (null on error)
zBuffer	A pointer to the cartesian z coordinates on return (null on error)
dataFormat	Pointer to the BTA_DataFormat, thus how to parse 'xBuffer', 'yBuffer' and 'zBuffer'
unit	Pointer to BTA_Unit, thus how to interpret 'xBuffer', 'yBuffer' and 'zBuffer'
xRes	Pointer to the number of columns of 'xBuffer', 'yBuffer' and 'zBuffer'
yRes	Pointer to the number of rows of 'xBuffer', 'yBuffer' and 'zBuffer'

Returns: Please refer to bta_status.h

BTA_Status BTAinitConfig ( BTA_Config * config )

Fills the config structure with standard values.

Parameters

config Pointer to the structure to be initialized to standard values

Returns: Please refer to bta_status.h

BTA_Status BTAinitDiscoveryConfig ( BTA_DiscoveryConfig * config )

Fills the discovery config structure with standard values.

Parameters

config Pointer to the structure to be initialized to standard values

Returns: Please refer to bta_status.h

BTA_Status BTAinitGrabbingConfig ( BTA_GrabbingConfig * config )

Fills the grab config structure with standard values.

Parameters

config Pointer to the structure to be initialized to standard values

Returns: Please refer to bta_status.h

uint8_t BTAisConnected ( BTA_Handle handle )

Queries whether the library has a valid connection to the sensor.

Parameters

handle Handle of the device to be used

Returns: 1 if connected to the sensor, 0 otherwise

uint8_t BTAisRunning ( BTA_Handle handle )

Queries whether the handle is open and background threads are running correctly.

Parameters

handle Handle of the device to be used

Returns: 1 if the service is running, 0 otherwise

BTA_Status BTAopen	(	BTA_Config *	config,
		BTA_Handle *	handle
	)

Establishes a connection to the device and returns a handle.

Parameters

config	Pointer to the previously initialized config structure
handle	Pointer containing the handle to the device on return

Returns: Please refer to bta_status.h

BTA_Status BTAreadRegister	(	BTA_Handle	handle,
		uint32_t	address,
		uint32_t *	data,
		uint32_t *	registerCount
	)

Reads registers from the device/SDK.

Parameters

handle	Handle of the device to be used
address	The address of the first register to read from
data	Pointer to buffer allocated by the caller. Contains register data on return. The data in the buffer on return consists of one or more register values, each 4 bytes wide.
registerCount	Pointer to the number of registers to be read. On return, if not null, it contains the number of registers actually read. If null is passed, one register is read.

Returns: Please refer to bta_status.h

BTA_Status BTAremoveFilter	(	BTA_Handle	handle,
		BTA_FltHandle	fltHandle
	)

(The development of filter functionality is still in progress!) Removes the last filter added

Parameters

handle	Handle of the device to be used
fltHandle	The handle of the filter to be removed

Returns: Please refer to bta_status.h

BTA_Status BTArestoreDefaultConfig ( BTA_Handle handle )

Erases the register settings previously stored with BTAwriteCurrentConfigToNvm (May require rebbot for loading default values)

Parameters

handle Handle of the device to be used

Returns: Please refer to bta_status.h

BTA_Status BTAsendReset ( BTA_Handle handle )

Initiates a reset of the device.

Parameters

handle Handle of the device to be used

Returns: Please refer to bta_status.h

BTA_Status BTAserializeFrame	(	BTA_Frame *	frame,
		uint8_t *	frameSerialized,
		uint32_t *	frameSerializedLen
	)

Helper function to convert a BTA_Frame structure into a serialized stream; useful for recording frames to files.

Parameters

frame	The pointer to the frame to be serialized
frameSerialized	Buffer to contain the frame data on return. Must be allocated by the caller
frameSerializedLen	Pointer to length of the buffer frameSerialized allocated by the caller. Pointer to the actual length of the serialized frame on return.

Returns: Please refer to bta_status.h

BTA_Status BTAsetFrameMode	(	BTA_Handle	handle,
		BTA_FrameMode	frameMode
	)

Allows to set a BTA_FrameMode which defines the data delivered by the sensor. The device and/or the SDK is configured depending on the frame mode, so that the desired channels are included in each BTA_Frame.

Parameters

handle	Handle of the device to be used
frameMode	The desired frame-mode

Returns: Please refer to bta_status.h

BTA_Status BTAsetFrameRate	(	BTA_Handle	handle,
		float	frameRate
	)

Facilitates setting the frame rate for the default capture sequence.

Parameters

handle	Handle of the device to be used
frameRate	The desired frame rate in [Hz]

Returns: Please refer to bta_status.h

BTA_Status BTAsetGlobalOffset	(	BTA_Handle	handle,
		float	globalOffset
	)

Function for setting the distance offset being applied to all pixels equally. It is, for all current devices, valid for the currently set modulation frequency. It can only be set for predefined modulation frequencies (see device’s SUM).

Parameters

handle	Handle of the device to be used
globalOffset	offset in [mm]

Returns: Please refer to bta_status.h

BTA_Status BTAsetIntegrationTime	(	BTA_Handle	handle,
		uint32_t	integrationTime
	)

Facilitates setting the integration time for the default capture sequence(s)

Parameters

handle	Handle of the device to be used
integrationTime	The desired integration time in [us]

Returns: Please refer to bta_status.h

BTA_Status BTAsetLibParam	(	BTA_Handle	handle,
		BTA_LibParam	libParam,
		float	value
	)

Function for setting a parameter for the library. Library parameters do not directly affect the camera's configuration.

Parameters

handle	Handle of the device to be used
libParam	Identifier for the parameter (consult the support wiki for a description of its function)
value	The value to be set for the library parameter

Returns: Please refer to bta_status.h

BTA_Status BTAsetModulationFrequency	(	BTA_Handle	handle,
		uint32_t	modulationFrequency
	)

Facilitates setting the modulation frequency for the default capture sequence(s)

Parameters

handle	Handle of the device to be used
modulationFrequency	The desired modulation frequency in [Hz]

Returns: Please refer to bta_status.h

BTA_Status BTAstartDiscovery	(	BTA_DiscoveryConfig *	discoveryConfig,
		FN_BTA_DeviceFound	deviceFound,
		FN_BTA_InfoEvent	infoEvent,
		BTA_Handle *	handle
	)

Starts the discovery of devices. If possible, broadcast messages are transmitted otherwise all possible connections are tested.

Parameters

discoveryConfig	Parameters on how to perform the discovery. The connection interface used defines which parameters have to be set in BTA_DiscoveryConfig.
deviceFound	The callback to be invoked when a device has been discovered
infoEvent	The callback to be invoked when an error occurs
handle	On return it contains the discovery handle which has to be used to stop the background process.

Returns: Please refer to bta_status.h

BTA_Status BTAstartGrabbing	(	BTA_Handle	handle,
		BTA_GrabbingConfig *	config
	)

Issues the library to grab (or stop grabbing) all the frames and store them to the file provided in the config. When connected to USB (P100) the capture thread must be running or the BTAgetFrame must be called frequently in order for the library to grab frames.

Parameters

handle	Handle of the device to be used.
config	Pointer to the config structure specifying parameters for the grabbing process. Pass null in order to stop grabbing.

Returns: Please refer to bta_status.h

BTA_Status BTAstatusToString	(	BTA_Status	status,
		char *	statusString,
		uint16_t	statusStringLen
	)

A convenience function to convert a BTA_Status into a string.

Parameters

status	The BTA_Status to be converted into a string
statusString	A buffer allocated by the caller to contain the result on return
statusStringLen	The length of the preallocated buffer in statusString

Returns: Please refer to bta_status.h

BTA_Status BTAstopDiscovery ( BTA_Handle * handle )

Stops the discovery of devices.

Parameters

handle Pass the handle from startDiscovery in order to identify the ongoing discovery process

Returns: Please refer to bta_status.h

BTA_Status BTAwigglingUpdate	(	BTA_Handle	handle,
		const uint8_t *	filename,
		FN_BTA_ProgressReport	progressReport
	)

Convenience function for doing a firmware update. Uses BTAflashUpdate() internally.

Parameters

handle	Handle of the device to be used
filename	Name of the binary file
progressReport	Callback function for reporting the status and progress during transfer and programming. Can be null

Returns: Please refer to bta_status.h

BTA_Status BTAwriteCurrentConfigToNvm ( BTA_Handle handle )

Writes the current configuration (i.e. register values) to non-volatile memory.

Parameters

handle Handle of the device to be used

Returns: Please refer to bta_status.h

BTA_Status BTAwriteRegister	(	BTA_Handle	handle,
		uint32_t	address,
		uint32_t *	data,
		uint32_t *	registerCount
	)

Writes registers to the device/SDK.

Parameters

handle	Handle of the device to be used
address	The address of the first register to write to
data	Pointer to buffer containing register data to be written. The data in the buffer consists of one or more register values, each 4 bytes wide.
registerCount	Pointer which contains the number of registers to be written. On return, if not null, it contains the number of registers actually written. If null is passed, one register is written.

Returns: Please refer to bta_status.h

typedef int ( 1 * FN_BTA_ProgressReport )

Callback function to report status and progress during transfer and programming.

Parameters

status	Please refer to bta_status.h
percentage	Contains the progress in [%]. 0: File transfer started (can only be reported once per file transfer). 100: File transfer finished (can only be reported once per file transfer).

typedef void ( 1 * FN_BTA_FrameArrivedEx )

Callback function to report on informative events. The implementation of this function in the application must copy the relevant data and return immediately. The parameter 'verbosity' in BTA_Config can be used to turn on/off certain events.

Callback function to report on data frames from the sensor. The implementation of this function in the application must copy the relevant data and return immediately. The BTA_Frame may NOT be altered! Do not call BTAfreeFrame on frame, because it is free'd in the lib.

Parameters

status	The status describing the reason for the infoEvent
msg	A string containing the information for the user
handle	The handle as identification for the device
status	The status describing the reason for the infoEvent
msg	A string containing the information for the user
frame	A pointer to the structure containing the data frame
handle	The handle as identification for the device
frame	A pointer to the structure containing the data frame

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation