Peter: 1 Version importiert

2023-10-31T08:03:10Z

1 Version importiert

← Nächstältere Version	Version vom 31. Oktober 2023, 10:03 Uhr
(kein Unterschied)

en>Peter: 1 Version importiert

2023-08-22T19:35:53Z

1 Version importiert

Neue Seite

== 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:
:{| class="wikitable"
|-
! 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:
:{| class="wikitable"
|-
! 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#BTAgetVersion|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#BTAinitConfig|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#BTAopen|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#BTAgetDeviceInfo|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#BTAgetFrame|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#BTAfreeFrame|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#BTAgetDistances|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#BTAgetAmplitudes|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#BTAgetXYZcoordinates|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#BTAgetXYZcoordinates|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#BTAclose|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#BTAsetKeepAliveMsgInterval|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#BTAgetFrameRate|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#BTAsetFrameRate|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#BTAgetIntegrationTime|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#BTAgetIntegrationTime|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#BTAgetGlobalOffset|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#BTAsetGlobalOffset|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#BTAsetFrameMode|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#BTAreadRegister|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#BTAwriteRegister|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#BTAwriteRegister|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#BTAwriteRegister|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#BTAwriteRegister|BltTofApi Error Codes]]

BltTofApi Matlab SDK - Versionsgeschichte

Peter: 1 Version importiert

en>Peter: 1 Version importiert