BltTofApi Matlab SDK

Overview

In order to create a common interface for our products we define the interfaces between a ToF device and an application. The main part of this model is the BltTofApi which is written in C for platform independency. The MATLAB SDK is able to access the BltTofApi interface and will therefore be compatible with any device with existing lib implementing in the BltTofApi.

Software Releases

for Ethernet devices

Version 1.3.0

Release date

2015-02-02

Supported library

Bluetechnix_ToF_Api_Eth_Win_x86_x64_v1.3.0

Release Notes

List of changes:

Category	Description
Bugfix	BTAgetXYZcoordinates correctly returns the modulation frequency and the integration time.
Feature	Calibration files can be passed to the BTAopen function by using the configuration structure.
Feature	Devices with higher resolutions than 160x120 are supported.
Feature	New function: BTAgetPhases
Feature	New function: BTAget2DData
Feature	New function: BTAwriteCurrentConfigToNvm
Feature	New function: BTArestoreDefaultConfig
Feature	New function: BTAsendReset

Version 1.0.0

Release date

2014-09-15

Supported library

Bluetechnix_ToF_Api_Eth_Win_x86_x64_v1.0.0

Release Notes

Initial release

for USB devices

Version 1.3.0

Release date

2015-02-03

Supported library

Bluetechnix_ToF_Api_P100_Win_Lin_ARM_v1.3.0

Release Notes

List of changes:

Category	Description
Bugfix	BTAgetXYZcoordinates correctly returns the modulation frequency and the integration time.
Feature	Calibration files can be passed to the BTAopen function by using the configuration structure.
Feature	Devices with higher resolutions than 160x120 are supported.
Feature	New function: BTAgetPhases
Feature	New function: BTAgetFlags
Feature	New function: BTAwriteCurrentConfigToNvm

Version 1.0.0

Release date

2014-09-15

Supported library

Bluetechnix_ToF_Api_P100_Win_x86_x64_v1.0.0

Release Notes

Initial release

API Reference

API Version

In order to query the version of the API, invoke the function BTAgetVersion.

Calling syntax:

[status, version, buildDateTime, supportedDeviceTypes] = BTAgetVersion;

Input parameter:

none

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
version              - Version number
buildDateTime        - Build date and time
supportedDeviceTypes - Supported device types:
			 0xA9C1 – Sentis-ToF-M100
			 0xB320 – Argos 3D P320
			 0x9BA6 – Argos 3D P310
			 0xA3C4 – Argos 3D P100
                         0x5032 - Argos 3D P510

Initialization

First, the library must be configured via the configuration c-structure. The configuration structure must be initialized with standard values using the function BTAinitConfig. The specific implementation of the library defines which parameters are required and which can be left out. The required parameters must then be set to a valid value before calling BTAopen.

Calling syntax:

[status, configStruct] = BTAinitConfig;

Input parameter:

none

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
configStruct         - Configuration structure

Connection Parameters

A library might define different parameter sets for different connection modes (For example if only TCP configuration interface parameters are set, no data interface connection will be established to the sensor).

Example for Sentis-ToF-M100 lib and connection mode UDP/TCP:

configStruct.udpDataIpAddr = [224, 0, 0, 1];
configStruct.udpDataIpAddrLen = 4;
configStruct.udpDataPort = 10002;
configStruct.tcpDeviceIpAddr = [192, 168, 0, 10];
configStruct.tcpDeviceIpAddrLen = 4;
configStruct.tcpControlPort = 10001;
configStruct.frameQueueMode = 1;
configStruct.frameQueueLength = 5;

Frame Mode Parameter

The frame mode can be configured in order to get the desired data channels from the sensor / library:

configStruct.frameMode = 1;

Possible frame modes:

1 – Distances and amplitudes 
2 – Distance, amplitudes and flags (only supported by USB based devices)
3 - XYZ coordinates 
4 – XYZ coordinates and amplitudes 
5 – Distances, amplitudes and 2D color (only supported by Ethernet based devices)
6 - XYZ coordinates, amplitudes and flags (only supported by USB based devices)
7 – Raw Phases
8 – Intensities (only supported by USB based devices)

Connecting

Now that the configuration structure is filled in, the connection is ready to be opened:

Calling syntax:

[status, deviceHandle] = BTAopen(configStruct);

Input parameter:

configStruct         - Configuration structure

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
deviceHandle         - Handle to the device

Querying Device Information

The following example shows, how general information on the device can be retrieved. The resulting struct may be only partly filled depending on the device’s capabilities.

Calling syntax:

[status, deviceType, productOrderNumber, serialNumber, firmwareVersion] = BTAgetDeviceInfo(deviceHandle);

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
deviceType           - Device type
			 0xA9C1 – Sentis-ToF-M100
			 0xB320 – Argos 3D P320
			 0x9BA6 – Argos 3D P310
			 0xA3C4 – Argos 3D P100
productOrderNumber   - Product order number of the device
serialNumber         - Serial number of the device
firmwareVersion      - Firmware version

Frame Retrieval

A frame can be actively requested from the library. The function BTAgetFrame is blocking, so a timeout can be specified. A timeout of 0 results in endless waiting for a frame.

Calling syntax:

[status, frameHandle, frameCounter, timeStamp] = BTAgetFrame(deviceHandle, timeout);

Input parameter:

deviceHandle         - Device handle
timeout              - Timeout to wait if no frame is yet available in [ms]. If timeout = 0 the function waits endlessly for a frame.

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
frameHandle          - Frame handle (needs to be free’d with BTAfreeFrame)

Frame Cleanup

A successful call to getFrame always demands for a call to BTAfreeFrame.

Calling syntax:

[status] = BTAfreeFrame(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Get Distances

BTAgetDistances extracts distances from a provided frame. If there is no channel with distances data present in the frame, an error is returned.

Calling syntax:

[status, distData, integrationTime, modulationFrequency, unit] = BTAgetDistances(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
distData             - Array which contains the distances data.
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get Amplitudes

BTAgetAmplitudes extracts amplitudes from a provided frame. If there is no channel with amplitudes data present in the frame, an error is returned.

Calling syntax:

[status, ampData, integrationTime, modulationFrequency, unit] = BTAgetAmplitudes(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
ampData              - Array which contains the amplitudes data.
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get XYZ Coordinates

BTAgetAmplitudes extracts 3D-Coordinates from a provided frame. If there is no channel with 3D-coordinates present in the frame, an error is returned.

Calling syntax:

[status, xData, yData, zData, integrationTime, modulationFrequency, unit] =  BTAgetXYZcoordinates(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
xData                - Array which contains the cartesian x coordinates.
yData                - Array which contains the cartesian y coordinates.
zData                - Array which contains the cartesian z coordinates.
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get Phases

BTAgetDistances extracts the phases from a provided frame. If there is no channel which contains phases, an error is returned.

Calling syntax:

[status, phase0, phase90, phase180, phase270, integrationTime, modulationFrequency, unit] = BTAgetPhases(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               -	  0 	Success
			  -15	The given frame does not contain phase data
			  -1	The given handle is not valid	
phase0               - Array which contains the phase0.
phase90              - Array which contains the phase90.
phase180             - Array which contains the phase180.
phase270             - Array which contains the phase270.
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get Flags

BTAgetFlags extracts the flags from a provided frame. If there is no channel which contains flags, an error is returned.

NOTE: This function is supported only by USB based devices.

Calling syntax:

[status, flags, integrationTime, modulationFrequency, unit] = BTAgetFlags(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
flags                - Array which contains the flags
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get Color Sensor Data

BTAget2DData extracts the color sensor data from a provided frame. If there is no channel which contains color sensor data, an error is returned.

NOTE: This function is supported only by Ethernet based devices.

Calling syntax:

[status, colorData2D, integrationTime, modulationFrequency, unit] = BTAget2DData(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               -	  0 	Success
 	                  -15	The given frame does not contain phase data
                          1     The frame mode is selected correctly but the given frame doesn't contain 2D color data. 
                               The reason for this are different frame rates of the ToF and the 2D sensor.

-1 The given handle is not valid

colorData2D          - Array which contains the 2D color data
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Get Intensities

BTAgetIntensities extracts the intensities from a provided frame. If there is no channel which intensity data, an error is returned.

NOTE: This function is supported only by USB based devices.

Calling syntax:

[status, intensities, integrationTime, modulationFrequency, unit] = BTAgetIntensities(frameHandle);

Input parameter:

frameHandle          - Frame handle

Output parameter:

status               -	  0 	Success
			  -15	The given frame does not contain phase data
			  -1	The given handle is not valid	
intensities          - Array which contains intensities
integrationTime      - Integration time
modulationFrequency  - Modulation frequency
unit                 - Unit of the data.
			 0 – unitless
			 1 – meter
			 2 - centimeter
			 3 - millimeter

Disconnecting

In order to disconnect the sensor and stop the service, simply call BTAclose.

Calling syntax:

status = BTAclose(deviceHandle);

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Keep Alive Massages Interval

The interval of the keepalive massages can be set with BTAsetKeepAliveMsgInterval.

Calling syntax:

status = BTAsetKeepAliveMsgInterval(deviceHandle, interval);

Input parameter:

deviceHandle         - Device handle
interval             - The interval in seconds for keep-alive-massages to be sent.

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Get Frame Rate

BTAgetFrameRate returns the current theoretical frame rate of the default capture sequence.

Calling syntax:

[status, frameRate] = BTAgetFrameRate(deviceHandle); 

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
frameRate            - Frame rate

Set Frame Rate

The frame rate can be changed with BTAsetFrameRate.

Calling syntax:

status = BTAsetFrameRate(deviceHandle, frameRate);

Input parameter:

deviceHandle         - Device handle
frameRate            - Frame rate

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Get Integration Time

BTAgetIntegrationTime returns the current integration time of the default capture sequence.

Calling syntax:

[status, integrationTime] = BTAgetIntegrationTime (deviceHandle); 

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
integrationTime      - Integration time

Set Integration Time

The integration time can be changed with BTAsetIntegrationTime.

Calling syntax:

status = BTAsetIntegrationTime (deviceHandle, integrationTime);

Input parameter:

deviceHandle         - Device handle
integrationTime      - Integration time

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Get Global Offset

BTAgetGlobalOffset returns the distance offset being applied to all pixels equally.

Calling syntax:

[status, globalOffset] = BTAgetGlobalOffset(deviceHandle); 

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
globalOffset         - Global offset in [mm]

Set Global Offset

The distance offset being applied to all pixels equally can be changed with BTAsetGlobalOffset.

Calling syntax:

status = BTAsetGlobalOffset (deviceHandle, globalOffset);

Input parameter:

deviceHandle         - Device handle
globalOffset         - Global offset in [mm]

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Set Frame Mode

BTAsetGlobalOffset allows specifying which channels will be included in a BTA_Frame, see the BLT_FrameMode in bta_frame.h for possible options.

Calling syntax:

status = BTAsetFrameMode(deviceHandle, frameMode);

Input parameter:

deviceHandle         - Device handle
frameMode            - The desired frame mode
                        1 – Distances and amplitudes 
                        2 – Distance, amplitudes and flags	(only supported by USB based devices)
                        3 - XYZ coordinates 
                        4 – XYZ coordinates and amplitudes 
                        5 – Distances, amplitudes and 2D color (only supported by Ethernet based devices)
                        6 - XYZ coordinates, amplitudes and flags (only supported by USB based devices)
                        7 – Raw Phases
                        8 – Intensities (only supported by USB based devices)

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Read Register

BTAreadRegister reads out the data of one register.

Calling syntax:

[status, data] = BTAreadRegister(deviceHandle, address);

Input parameter:

deviceHandle         - Device handle
address              - The address in the register map to read from

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes
data                 - Register data

Write Register

BTAwriteRegister writes a value into the specified register address.

Calling syntax:

[status] = BTAwriteRegister(deviceHandle, adress, data);

Input parameter:

deviceHandle         - Device handle
address              - The address in the register map to read from
data                 - Data to write

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Save current configuration

BTAwriteCurrentConfigToNvm writes the current configuration (i.e. register settings) to non-volatile memory.

Calling syntax:

[status] = BTAwriteCurrentConfigToNvm(deviceHandle);

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Restore default configuration

BTArestoreDefaultConfig restores the default configuration (but does not save it).

NOTE: This function is supported only by Ethernet based devices.

Calling syntax:

[status] = BTAwriteCurrentConfigToNvm(deviceHandle);

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes

Reset Device

BTAsendReset initiates a reset of the device.

NOTE: This function is supported only by Ethernet based devices.

Calling syntax:

[status] = BTAsendReset(deviceHandle);

Input parameter:

deviceHandle         - Device handle

Output parameter:

status               - Error code for error handling. Refer to BltTofApi Error Codes