1 /*************************************************************************//** 2 * @file 3 * @brief This file is part of the AFBR-S50 API. 4 * @details This file provides generic functionality belonging to all 5 * devices from the AFBR-S50 product family. 6 * 7 * @copyright 8 * 9 * Copyright (c) 2023, Broadcom Inc. 10 * All rights reserved. 11 * 12 * Redistribution and use in source and binary forms, with or without 13 * modification, are permitted provided that the following conditions are met: 14 * 15 * 1. Redistributions of source code must retain the above copyright notice, this 16 * list of conditions and the following disclaimer. 17 * 18 * 2. Redistributions in binary form must reproduce the above copyright notice, 19 * this list of conditions and the following disclaimer in the documentation 20 * and/or other materials provided with the distribution. 21 * 22 * 3. Neither the name of the copyright holder nor the names of its 23 * contributors may be used to endorse or promote products derived from 24 * this software without specific prior written permission. 25 * 26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 27 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 29 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 30 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 32 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 33 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 34 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 35 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36 *****************************************************************************/ 37 38 #ifndef ARGUS_API_H 39 #define ARGUS_API_H 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /*!*************************************************************************** 45 * @defgroup argus_api AFBR-S50 API 46 * @ingroup argus 47 * 48 * @brief The main module of the API from the AFBR-S50 SDK. 49 * 50 * @details General API for the AFBR-S50 time-of-flight sensor device family.\n 51 * See the \ref getting_started Guide for a detailed description 52 * on how to use the module/API. 53 * 54 * @addtogroup argus_api 55 * @{ 56 *****************************************************************************/ 57 58 #include "argus_def.h" 59 #include "argus_res.h" 60 #include "argus_pba.h" 61 #include "argus_dfm.h" 62 #include "argus_snm.h" 63 #include "argus_xtalk.h" 64 #include "argus_offset.h" 65 66 /*! The S2PI slave identifier. */ 67 typedef int32_t s2pi_slave_t; 68 69 /*!*************************************************************************** 70 * @brief Initializes the device with default measurement mode. 71 * 72 * @details The function that needs to be called once after power up to 73 * initialize the modules state (i.e. the corresponding handle) and the 74 * dedicated Time-of-Flight device. In order to obtain a handle, 75 * reference the #Argus_CreateHandle method. 76 * 77 * Prior to calling the function, the required peripherals (i.e. S2PI, 78 * GPIO w/ IRQ and Timers) must be initialized and ready to use. 79 * 80 * The function executes the following tasks: 81 * - Initialization of the internal state represented by the handle 82 * object. 83 * - Setup the device such that an safe configuration is present in 84 * the registers. 85 * - Initialize sub modules such as calibration or measurement modules. 86 * . 87 * 88 * The modules configuration is initialized with reasonable default 89 * values. Note that the default measurement mode depends on the 90 * given device. 91 * 92 * Also refer to #Argus_InitMode, which uses an specified measurement 93 * mode instead of the dedicated default measurement mode. 94 * 95 * @param hnd The API handle; contains all internal states and data. 96 * 97 * @param spi_slave The SPI hardware slave, i.e. the specified CS and IRQ 98 * lines. This is actually just a number that is passed 99 * to the SPI interface to distinct for multiple SPI slave 100 * devices. Note that the slave must be not equal to 0, 101 * since is reserved for error handling. 102 * 103 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 104 *****************************************************************************/ 105 status_t Argus_Init(argus_hnd_t * hnd, s2pi_slave_t spi_slave); 106 107 /*!*************************************************************************** 108 * @brief Initializes the device with specified measurement mode. 109 * 110 * @details The function that needs to be called once after power up to 111 * initialize the modules state (i.e. the corresponding handle) and the 112 * dedicated Time-of-Flight device. In order to obtain a handle, 113 * reference the #Argus_CreateHandle method. 114 * 115 * Prior to calling the function, the required peripherals (i.e. S2PI, 116 * GPIO w/ IRQ and Timers) must be initialized and ready to use. 117 * 118 * The function executes the following tasks: 119 * - Initialization of the internal state represented by the handle 120 * object. 121 * - Setup the device such that an safe configuration is present in 122 * the registers. 123 * - Initialize sub modules such as calibration or measurement modules. 124 * . 125 * 126 * The modules configuration is initialized with reasonable default values. 127 * 128 * Also refer to #Argus_Init, which uses the dedicated default measurement 129 * mode instead of an user specified measurement mode. 130 * 131 * @param hnd The API handle; contains all internal states and data. 132 * 133 * @param spi_slave The SPI hardware slave, i.e. the specified CS and IRQ 134 * lines. This is actually just a number that is passed 135 * to the SPI interface to distinct for multiple SPI slave 136 * devices. Note that the slave must be not equal to 0, 137 * since is reserved for error handling. 138 * 139 * @param mode The specified measurement mode to be initialized. 140 * Pass 0 as special value to select default measurement mode 141 * (see #Argus_Init). 142 * 143 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 144 *****************************************************************************/ 145 status_t Argus_InitMode(argus_hnd_t * hnd, s2pi_slave_t spi_slave, argus_mode_t mode); 146 147 /*!*************************************************************************** 148 * @brief Reinitializes the device with the current measurement mode. 149 * 150 * @details The function reinitializes the device with the currently active 151 * measurement mode. 152 * 153 * This can be used as a soft reset for the device and API. 154 * See #Argus_Init for more information on the initialization. 155 * 156 * Note that the #Argus_Init or #Argus_InitMode function must be called 157 * first! Otherwise, the function will return an error if it is called 158 * for an yet uninitialized device/handle. 159 * 160 * Also refer to #Argus_ReinitMode, which uses a specified measurement 161 * mode instead of the currently active measurement mode. 162 * 163 * @note If a full re-initialization is not desired, refer to the 164 * #Argus_RestoreDeviceState function that will only re-write the 165 * register map to the device to restore its state after an power 166 * cycle. 167 * 168 * @param hnd The API handle; contains all internal states and data. 169 * 170 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 171 *****************************************************************************/ 172 status_t Argus_Reinit(argus_hnd_t * hnd); 173 174 /*!*************************************************************************** 175 * @brief Reinitializes the device with a specified measurement mode. 176 * 177 * @details The function reinitializes the device with a specified (/p mode) 178 * measurement mode. 179 * 180 * This can be used as a soft reset for the device and API. 181 * See #Argus_InitMode for more information on the initialization. 182 * 183 * Note that the #Argus_Init or #Argus_InitMode function must be called 184 * first! Otherwise, the function will return an error if it is called 185 * for an yet uninitialized device/handle. 186 * 187 * Also refer to #Argus_Reinit, which re-uses the currently active 188 * measurement mode instead of an user specified measurement mode. 189 * 190 * @note If a full re-initialization is not desired, refer to the 191 * #Argus_RestoreDeviceState function that will only re-write the 192 * register map to the device to restore its state after an power 193 * cycle. 194 * 195 * @param hnd The API handle; contains all internal states and data. 196 * 197 * @param mode The specified measurement mode to be initialized. 198 * Pass 0 as special value to select the current measurement mode 199 * (see #Argus_Init). 200 * 201 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 202 *****************************************************************************/ 203 status_t Argus_ReinitMode(argus_hnd_t * hnd, argus_mode_t mode); 204 205 /*!*************************************************************************** 206 * @brief Deinitializes the API modules and the device. 207 * 208 * @details The function deinitializes the device and clear all internal states. 209 * Can be used to cleanup before releasing the memory. The device 210 * can not be used any more and must be initialized again prior to next 211 * usage. 212 * 213 * Note that the #Argus_Init function must be called first! Otherwise, 214 * the function will return an error if it is called for an yet 215 * uninitialized device/handle. 216 * 217 * @param hnd The API handle; contains all internal states and data. 218 * 219 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 220 *****************************************************************************/ 221 status_t Argus_Deinit(argus_hnd_t * hnd); 222 223 /*!*************************************************************************** 224 * @brief Creates a new device data handle object to store all internal states. 225 * 226 * @details The function must be called to obtain a new device handle object. 227 * The handle is basically an abstract object in memory that contains 228 * all the internal states and settings of the API module. The handle 229 * is passed to all the API methods in order to address the specified 230 * device. This allows to use the API with more than a single measurement 231 * device. 232 * 233 * The handler is created by calling the memory allocation method from 234 * the standard library: @code void * malloc(size_t size) @endcode 235 * In order to implement an individual memory allocation method, 236 * define and implement the following weakly binded method and return 237 * a pointer to the newly allocated memory. * 238 * 239 * @code void * Argus_Malloc (size_t size) @endcode 240 * 241 * Also see the #Argus_DestroyHandle method for the corresponding 242 * deallocation of the allocated memory. 243 * 244 * @note Although the method is using memory allocated on the heap, it 245 * is eventually no dynamic memory allocation, since the block of 246 * memory is kept all the time and no memory blocks are dynamically 247 * freed and re-allocated. If the usage of heap must be avoided, one 248 * can always implement its own version of the `Argus_Malloc` function 249 * to create the memory elsewhere. 250 * 251 * @return Returns a pointer to the newly allocated device handler object. 252 * Returns a null pointer if the allocation failed! 253 *****************************************************************************/ 254 argus_hnd_t * Argus_CreateHandle(void); 255 256 /*!*************************************************************************** 257 * @brief Destroys a given device data handle object. 258 * 259 * @details The function can be called to free the previously created device 260 * data handle object in order to save memory when the device is not 261 * used any more. 262 * 263 * Note that the handle must be deinitialized before it can be 264 * destroyed. The function returns #ERROR_FAIL if the handle is not 265 * yet deinitialized. 266 * 267 * Please refer to the #Argus_CreateHandle method for the corresponding 268 * allocation of the memory. 269 * 270 * The handler is destroyed by freeing the corresponding memory with the 271 * method from the standard library, @code void free(void * ptr) @endcode. 272 * In order to implement an individual memory deallocation method, define 273 * and implement the following weakly binded method and free the memory 274 * object passed to the method by a pointer. 275 * 276 * @code void Argus_Free (void * ptr) @endcode 277 * 278 * Also see the #Argus_CreateHandle method for the corresponding 279 * allocation of the required memory. 280 * 281 * @param hnd The device handle object to be deallocated. 282 * 283 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 284 *****************************************************************************/ 285 status_t Argus_DestroyHandle(argus_hnd_t * hnd); 286 287 /*!*************************************************************************** 288 * @brief Restores the device state with a re-write of all register values. 289 * 290 * @details The function invalidates and restores the device state by executing 291 * a re-write of the full register map. 292 * 293 * The purpose of this function is to recover from known external 294 * events like power cycles, for example due to sleep / wake-up 295 * functionality. This can be implemented by cutting off the external 296 * power supply of the device (e.g. via a MOSFET switch controlled by 297 * a GPIB pin). By calling this function, the expected state of the 298 * API is written to the device without the need to fully re-initialize 299 * the device. Thus, the API can resume where it has stopped as if 300 * there has never been a power cycle. 301 * 302 * The internal state machines like the dynamic configuration adaption 303 * (DCA) algorithm will not be reseted. The API/sensor will immediately 304 * resume at the last state that was optimized for the given 305 * environmental conditions. 306 * 307 * The use case of sleep / wake-up can be implemented as follows: 308 * 309 * 1. In case of ongoing measurements, stop the measurements via 310 * the #Argus_StopMeasurementTimer function (if started by the 311 * #Argus_StartMeasurementTimer function). 312 * 313 * 2. Shut down the device by removing the 5V power supply, e.g. 314 * via a GPIO pin that switches a MOSFET circuit. 315 * 316 * 3. After the desired sleep period, power the device by switching 317 * the 5V power supply on again. Wait until the power-on-reset 318 * (POR) is finished (approx. 1 ms) or just repeat step 4 until 319 * it succeeds. 320 * 321 * 4. Call the #Argus_RestoreDeviceState function to trigger the 322 * restoration of the device state in the API. Note that the 323 * function will return an error code if it fails. One can repeat 324 * the execution of that function a few times until it succeeds. 325 * 326 * 6. Continue with measurements via #Argus_StartMeasurementTimer 327 * of #Argus_TriggerMeasurement functions as desired. 328 * 329 * @note If a complete re-initialization (= soft-reset) is desired, see 330 * the #Argus_Reinit functionality. 331 * 332 * @note Changing a configuration or calibration parameter will always 333 * invalidate the device state as well as the state machine of the 334 * dynamic configuration adaption (DCA) algorithm. In that case, the 335 * device/API needs a few measurements to adopt to the present 336 * environmental conditions before the first valid measurement result 337 * can be obtained. This is almost similar to re-initializing the 338 * device (see #Argus_Reinit) which would also re-read the EEPROM. 339 * On the other hand, the #Argus_RestoreDeviceState does not reset 340 * or re-initialize anything. It just makes sure that the device 341 * register map (which has changed to its reset values after the 342 * power cycle) is what the API expects upon the next measurement. 343 * 344 * @param hnd The device handle object to be invalidated. 345 * 346 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 347 *****************************************************************************/ 348 status_t Argus_RestoreDeviceState(argus_hnd_t * hnd); 349 350 /*!************************************************************************** 351 * Generic API 352 ****************************************************************************/ 353 354 /*!*************************************************************************** 355 * @brief Gets the version number of the current API library. 356 * 357 * @details The version is compiled of a major (a), minor (b) and bugfix (c) 358 * number: a.b.c. 359 * 360 * The values are encoded into a 32-bit value: 361 * 362 * - [ 31 .. 24 ] - Major Version Number 363 * - [ 23 .. 16 ] - Minor Version Number 364 * - [ 15 .. 0 ] - Bugfix Version Number 365 * . 366 * 367 * To obtain the parts from the returned uin32_t value: 368 * 369 * @code 370 * uint32_t value = Argus_GetAPIVersion(); 371 * uint8_t a = (value >> 24) & 0xFFU; 372 * uint8_t b = (value >> 16) & 0xFFU; 373 * uint8_t c = value & 0xFFFFU; 374 * @endcode 375 * 376 * @return Returns the current version number. 377 *****************************************************************************/ 378 uint32_t Argus_GetAPIVersion(void); 379 380 /*!*************************************************************************** 381 * @brief Gets the build number of the current API library. 382 * 383 * @return Returns the current build number as a C-string. 384 *****************************************************************************/ 385 char const * Argus_GetBuildNumber(void); 386 387 /*!*************************************************************************** 388 * @brief Gets the version/variant of the module. 389 * 390 * @param hnd The API handle; contains all internal states and data. 391 * @return Returns the current module number. 392 *****************************************************************************/ 393 argus_module_version_t Argus_GetModuleVersion(argus_hnd_t * hnd); 394 395 /*!*************************************************************************** 396 * @brief Gets the name string of the module. 397 * 398 * @param hnd The API handle; contains all internal states and data. 399 * @return Returns the current module name. 400 *****************************************************************************/ 401 char const * Argus_GetModuleName(argus_hnd_t * hnd); 402 403 /*!*************************************************************************** 404 * @brief Gets the version number of the chip. 405 * 406 * @param hnd The API handle; contains all internal states and data. 407 * @return Returns the current version number. 408 *****************************************************************************/ 409 argus_chip_version_t Argus_GetChipVersion(argus_hnd_t * hnd); 410 411 /*!*************************************************************************** 412 * @brief Gets the type number of the device laser. 413 * 414 * @param hnd The API handle; contains all internal states and data. 415 * @return Returns the current device laser type number. 416 *****************************************************************************/ 417 argus_laser_type_t Argus_GetLaserType(argus_hnd_t * hnd); 418 419 /*!*************************************************************************** 420 * @brief Gets the unique identification number of the chip. 421 * 422 * @param hnd The API handle; contains all internal states and data. 423 * @return Returns the unique identification number. 424 *****************************************************************************/ 425 uint32_t Argus_GetChipID(argus_hnd_t * hnd); 426 427 /*!*************************************************************************** 428 * @brief Gets the SPI hardware slave identifier. 429 * 430 * @param hnd The API handle; contains all internal states and data. 431 * @return The SPI hardware slave identifier. 432 *****************************************************************************/ 433 s2pi_slave_t Argus_GetSPISlave(argus_hnd_t * hnd); 434 435 /*!*************************************************************************** 436 * @brief Gets the API handle for the specified SPI hardware slave. 437 * 438 * @param spi_slave The SPI hardware slave identifier. 439 * @return The API handle; contains all internal states and data. 440 *****************************************************************************/ 441 argus_hnd_t *Argus_GetHandle(s2pi_slave_t spi_slave); 442 443 /*! @} */ 444 445 /*!************************************************************************** 446 * Measurement/Device Operation 447 **************************************************************************** 448 * @addtogroup argus_meas 449 * @{ 450 ****************************************************************************/ 451 452 /*!*************************************************************************** 453 * @brief Starts the timer based measurement cycle asynchronously. 454 * 455 * @details This function starts a timer based measurement cycle asynchronously 456 * in the background. A periodic timer interrupt triggers the measurement 457 * frames on the ASIC and the data readout afterwards. 458 * 459 * When the measurement has finished, a callback (which is passed as 460 * a parameter to the function) is invoked in order to inform the 461 * main thread to call the \link #Argus_EvaluateData data evaluation 462 * method\endlink. This call is mandatory to release the data buffer 463 * for the next measurement and it must not be invoked directly from 464 * the callback since it is currently within an interrupt service 465 * routine. Rather a flag should inform the main thread or task 466 * scheduler to invoke the evaluation as soon as possible in order 467 * to not introduce any unwanted delays to the next measurement frame. 468 * 469 * The next measurement frame will be started as soon as the pre- 470 * conditions are meet. These are: 471 * 1. timer flag set (i.e. a certain time has passed since the last 472 * measurement in order to fulfill eye-safety), 473 * 2. device idle (i.e. no measurement currently ongoing) and 474 * 3. data buffer ready (i.e. the previous data has been evaluated). 475 * 476 * Usually, the device idle and data buffer ready conditions are met 477 * before the timer tick occurs and thus the timer dictates the frame 478 * rate. 479 * 480 * The callback function pointer will be invoked when the measurement 481 * frame has finished successfully or whenever an error, that cannot 482 * be handled internally, occurs. 483 * 484 * The periodic timer interrupts are used to check the measurement status 485 * for timeouts. An error is invoked when a measurement cycle have not 486 * finished within the specified time. 487 * 488 * Use #Argus_StopMeasurementTimer to stop the measurements. 489 * 490 * @note In order to use this function, the periodic interrupt timer module 491 * (see @ref argus_timer) must be implemented! 492 * 493 * @param hnd The API handle; contains all internal states and data. 494 * 495 * @param cb Callback function that will be invoked when the measurement 496 * is completed. Its parameters are the \link #status_t status 497 * \endlink of the finished measurement cycle and the pointer to 498 * the calling \link #argus_hnd_t API handle\endlink, i.e. the 499 * /p hnd value. The latter must be passed to the 500 * #Argus_EvaluateData function. 501 * If an error occurred, the status differs from #STATUS_OK. 502 * 503 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 504 *****************************************************************************/ 505 status_t Argus_StartMeasurementTimer(argus_hnd_t * hnd, 506 argus_measurement_ready_callback_t cb); 507 508 /*!*************************************************************************** 509 * @brief Stops the timer based measurement cycle. 510 * 511 * @details This function stops the ongoing timer based measurement cycles 512 * that have been started using the #Argus_StartMeasurementTimer 513 * function. 514 * 515 * Note that the function blocks until the current measurements are 516 * finished before returning. This guarantees that the callback was 517 * invoked and the #Argus_EvaluateData function may need to be called 518 * in order to release the data buffer. 519 * 520 * @param hnd The API handle; contains all internal states and data. 521 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 522 *****************************************************************************/ 523 status_t Argus_StopMeasurementTimer(argus_hnd_t * hnd); 524 525 /*!*************************************************************************** 526 * @brief Triggers a single measurement frame asynchronously. 527 * 528 * @details This function immediately triggers a single measurement frame 529 * asynchronously if all the pre-conditions are met. Otherwise it 530 * returns with a corresponding status (e.g. #STATUS_BUSY or 531 * #STATUS_ARGUS_POWERLIMIT). 532 * 533 * When the measurement has finished, a callback (which is passed as 534 * a parameter to the function) is invoked in order to inform the 535 * main thread to call the \link #Argus_EvaluateData data evaluation 536 * method\endlink. This call is mandatory to release the data buffer 537 * for the next measurement and it must not be invoked directly from 538 * the callback since it is currently within an interrupt service 539 * routine. Rather a flag should inform the main thread or task 540 * scheduler to invoke the evaluation task. 541 * 542 * The pre-conditions for starting a measurement frame are: 543 * 1. timer flag set (i.e. a certain time has passed since the last 544 * measurement in order to fulfill eye-safety), 545 * 2. device idle (i.e. no measurement currently ongoing) and 546 * 3. data buffer ready (i.e. the previous data has been evaluated). 547 * 548 * The callback function pointer will be invoked when the measurement 549 * frame has finished successfully or whenever an error, that cannot 550 * be handled internally, occurs. 551 * 552 * The successful finishing of the measurement frame is not checked 553 * for timeouts! Instead, the user can call the #Argus_GetStatus() 554 * function on a regular function to do so. 555 * 556 * @note Despite this function triggers a new measurement cycle upon its 557 * invocation, the frame time parameter is still active for this 558 * measurement mode. Basically, the first pre-condition mentioned 559 * above is controlled via the frame time parameter. This means 560 * that measurements cannot be triggered faster than the frame 561 * timer parameters specifies. The maximum integration time (i.e. 562 * exposure time) is also determined by the frame time such that 563 * new measurements are finished with the specified frame time and 564 * the device is ready to trigger a new measurement after the 565 * frame time has elapse. 566 * See #Argus_SetConfigurationFrameTime function for more information 567 * on the frame time. 568 * 569 * @param hnd The API handle; contains all internal states and data. 570 * 571 * @param cb Callback function that will be invoked when the measurement 572 * is completed. Its parameters are the \link #status_t status 573 * \endlink of the finished measurement cycle and the pointer to 574 * the calling \link #argus_hnd_t API handle\endlink, i.e. the 575 * /p hnd value. The latter must be passed to the 576 * #Argus_EvaluateData function. 577 * If an error occurred, the status differs from #STATUS_OK. 578 * 579 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 580 *****************************************************************************/ 581 status_t Argus_TriggerMeasurement(argus_hnd_t * hnd, 582 argus_measurement_ready_callback_t cb); 583 584 585 /*!**************************************************************************** 586 * @brief Starts the teach-in measurement mode. 587 * 588 * @details This function starts the teach-in measurement mode which maximizes 589 * the laser output (within the limits of eye-safety) for better 590 * visibility. This can be useful when aligning the sensor to a target 591 * where the laser spot needs to be visible. This is mostly helpful 592 * for the device variants with visible (red) lasers. 593 * 594 * The teach-in measurement mode can (and should) be stopped using the 595 * #Argus_StopTeachInMode function. 596 * 597 * @param hnd The API handle; contains all internal states and data. 598 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 599 *****************************************************************************/ 600 status_t Argus_StartTeachInMode(argus_hnd_t *hnd); 601 602 /*!**************************************************************************** 603 * @brief Stops the teach-in measurement mode. 604 * 605 * @details This function stops the teach-in measurement mode which maximizes 606 * the laser output (within the limits of eye-safety) for better 607 * visibility. 608 * 609 * The teach-in measurement mode can be started using the 610 * #Argus_StartTeachInMode function. 611 * 612 * @param hnd The API handle; contains all internal states and data. 613 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 614 *****************************************************************************/ 615 status_t Argus_StopTeachInMode(argus_hnd_t *hnd); 616 617 /*!*************************************************************************** 618 * @brief Determines whether a data evaluation is pending. 619 * 620 * @details If the function returns true, a raw buffer is required to be 621 * evaluated to the #Argus_EvaluateData function. The raw data buffer 622 * is filled with raw data from the measurement tasks which need to 623 * be evaluated and the buffer must be freed in order to restart a 624 * new measurement task. 625 * 626 * Note that no configuration parameters can be update until all raw 627 * buffers are evaluated. 628 * 629 * @note See also the #Argus_GetStatus function to obtain the current device 630 * status and error code if any. 631 * 632 * @param hnd The API handle; contains all internal states and data. 633 * @return True if any raw buffer is filled with data that must be evaluated. 634 *****************************************************************************/ 635 bool Argus_IsDataEvaluationPending(argus_hnd_t * hnd); 636 637 /*!*************************************************************************** 638 * @brief Determines if the device if active with timer based measurements. 639 * @details If the function returns true, the device is active with timer 640 * scheduled measurements that have been started via the 641 * #Argus_StartMeasurementTimer. 642 * 643 * Note that the active state is independent of the busy state that 644 * is set when the device is actually busy. The active state is also 645 * true if the device is currently idle but waits for the next timer 646 * event to trigger a new measurement cycle. 647 * 648 * @note See also the #Argus_GetStatus function to obtain the current device 649 * status and error code if any. 650 * 651 * @param hnd The API handle; contains all internal states and data. 652 * @return True if the device is operating in timer triggered measurement mode. 653 *****************************************************************************/ 654 bool Argus_IsTimerMeasurementActive(argus_hnd_t * hnd); 655 656 /*!*************************************************************************** 657 * @brief Stops the currently ongoing measurements and SPI activity immediately. 658 * 659 * @param hnd The API handle; contains all internal states and data. 660 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 661 *****************************************************************************/ 662 status_t Argus_Abort(argus_hnd_t * hnd); 663 664 /*!*************************************************************************** 665 * @brief Checks the state of the device/driver. 666 * 667 * @details Returns the current module status or error if any. 668 * 669 * See the following for a list of errors: 670 * 671 * Status: 672 * - Idle/OK: Device and SPI interface are idle (== #STATUS_IDLE). 673 * - Busy: Device or SPI interface are busy (== #STATUS_BUSY). 674 * - Initializing: The modules and devices are currently initializing 675 * (== #STATUS_INITIALIZING). 676 * . 677 * 678 * Error: 679 * - Not Initialized: The modules (or any submodule) has not been 680 * initialized yet (== #ERROR_NOT_INITIALIZED). 681 * - Not Connected: No device has been connected (or connection errors 682 * have occurred) (== #ERROR_ARGUS_NOT_CONNECTED). 683 * - Timeout: A previous frame measurement has not finished within a 684 * specified time (== #ERROR_TIMEOUT). 685 * . 686 * 687 * @note Note that this function returns the actual busy state. This means 688 * that it will return #STATUS_IDLE during the pause between two 689 * consecutive measurement frames. If the device is active with timer 690 * based measurements (i.e. started via the #Argus_StartMeasurementTimer 691 * function), the return state switches from idle to busy and back 692 * periodically. Use the #Argus_IsTimerMeasurementActive function in 693 * order to determine if the device is active with timer based 694 * measurements. 695 * 696 * @note Note also that the device might reject configuration parameter 697 * update despite the status is #STATUS_IDLE. This is due to the fact 698 * that the internal raw data buffers are still busy and require to 699 * be freed by passing them to the #Argus_EvaluateData function. Use 700 * the #Argus_IsDataEvaluationPending function to see whether any of 701 * the raw data buffers is busy or the configuration can be changed. 702 * 703 * @param hnd The API handle; contains all internal states and data. 704 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 705 *****************************************************************************/ 706 status_t Argus_GetStatus(argus_hnd_t * hnd); 707 708 /*!***************************************************************************** 709 * @brief Tests the connection to the device by sending a ping message. 710 * 711 * @details A ping is transferred to the device in order to check the device and 712 * SPI connection status. Returns #STATUS_OK on success and 713 * #ERROR_ARGUS_NOT_CONNECTED else-wise. 714 * 715 * @param hnd The API handle; contains all internal states and data. 716 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 717 ******************************************************************************/ 718 status_t Argus_Ping(argus_hnd_t * hnd); 719 720 /*!*************************************************************************** 721 * @brief Evaluates measurement data from the raw sensor readout data. 722 * 723 * @details This function must be called after each completion of a measurement 724 * cycle. The completion of a measurement cycle is communicated by the 725 * API via the invocation of the measurement data ready callback. The 726 * callback is installed in the API when new measurements are started 727 * either via the #Argus_TriggerMeasurement or via the 728 * #Argus_StartMeasurementTimer functions. 729 * 730 * This function evaluates measurement values like distances, amplitudes 731 * states and auxiliary values like temperature or voltage values from 732 * the raw sensor readout data obtained from the device during the 733 * measurement cycle. A pointer to a #argus_results_t data structure 734 * must be passed where all the evaluated values will be written to. 735 * The structure must persist during the whole execution of the 736 * #Argus_EvaluateData function. 737 * 738 * In addition to the evaluation of measurement data, the function 739 * feeds back the obtained information to the device in order to 740 * optimize its performance with respect to the ambient conditions, 741 * utilizing the so called Dynamic Configuration Adaption (DCA) 742 * feature. 743 * 744 * Furthermore, several calibration algorithm are applied to the data. 745 * 746 * If the function is called without any data ready to be evaluated 747 * from the measurement module, the error code #ERROR_ARGUS_BUFFER_EMPTY 748 * is returned and not data is written to the passed #argus_results_t 749 * data structure. 750 * 751 * @note The call to this function is mandatory for each finished measurement 752 * cycle, i.e. for each call to the measurement data ready callback. 753 * If the function is not called, the data is not evaluated and the 754 * internal raw data buffers are not freed. In that case, they can not 755 * be reused for the next measurement and the API can not start new 756 * measurements. 757 * There are up to two internal buffers available, the to callback 758 * is called twice before the API must wait for the data evaluation 759 * to finish. 760 * 761 * @param hnd The API handle; contains all internal states and data. 762 * @param res A pointer to the results structure that will be populated 763 * with evaluated data. 764 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 765 *****************************************************************************/ 766 status_t Argus_EvaluateData(argus_hnd_t * hnd, argus_results_t * res); 767 768 /*!*************************************************************************** 769 * @brief Evaluates measurement data from the raw sensor readout data. 770 * 771 * @details This function enhances the #Argus_EvaluateData by adding additional 772 * debug data into a specified debug data structure (\p dbg). If the 773 * \p dbg is null, the function is eqivalent to the #Argus_EvaluateData 774 * function. This, see #Argus_EvaluateData for reference. 775 * 776 * @param hnd The API handle; contains all internal states and data. 777 * @param res A pointer to the results structure that will be populated 778 * with evaluated data. 779 * @param dbg An optional pointer (can be null) to the debug data structure. 780 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 781 *****************************************************************************/ 782 status_t Argus_EvaluateDataDebug(argus_hnd_t * hnd, argus_results_t * res, 783 argus_results_debug_t * dbg); 784 785 /*!*************************************************************************** 786 * @brief Executes a crosstalk calibration measurement. 787 * 788 * @details This function immediately triggers a crosstalk vector calibration 789 * measurement sequence. The ordinary measurement activity is suspended 790 * while the calibration is ongoing. 791 * 792 * In order to perform a crosstalk calibration, the reflection of the 793 * transmitted signal must be kept from the receiver side, by either 794 * covering the TX completely (or RX respectively) or by setting up 795 * an absorbing target at far distance. 796 * 797 * After calibration has finished successfully, the obtained data is 798 * applied immediately and can be read from the API using the 799 * #Argus_GetCalibrationCrosstalkVectorTable function. 800 * 801 * @param hnd The API handle; contains all internal states and data. 802 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 803 *****************************************************************************/ 804 status_t Argus_ExecuteXtalkCalibrationSequence(argus_hnd_t * hnd); 805 806 /*!*************************************************************************** 807 * @brief Executes a relative range offset calibration measurement. 808 * 809 * @details This function immediately triggers a relative range offset calibration 810 * measurement sequence. The ordinary measurement activity is suspended 811 * while the calibration is ongoing. 812 * 813 * In order to perform a relative range offset calibration, a flat 814 * calibration target must be setup perpendicular to the sensors 815 * field-of-view. 816 * 817 * \code 818 * AFBR-S50 ToF Sensor 819 * #| 820 * #| | 821 * #|-----+ | 822 * #| RX | | 823 * Reference #|----++ | Calibration 824 * Plane #| TX | | Target 825 * #|----+ | 826 * #| | 827 * #| <------- targetRange -----------------> | 828 * \endcode 829 * 830 * There are two options to run the offset calibration: relative and 831 * absolute. 832 * 833 * - Relative (#Argus_ExecuteRelativeRangeOffsetCalibrationSequence): 834 * when the absolute distance is not essential or the distance to 835 * the calibration target is not known, the relative method can be 836 * used to compensate the relative pixel range offset w.r.t. the 837 * average range. The absolute or global range offset is not changed. 838 * - Absolute (#Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence): 839 * when the absolute distance is essential and the distance to the 840 * calibration target is known, the absolute method can be used to 841 * calibrate the absolute measured distance. Additionally, the 842 * relative pixel offset w.r.t. the average range is also compensated. 843 * . 844 * 845 * After calibration has finished successfully, the obtained data is 846 * applied immediately and can be read from the API using the 847 * #Argus_GetCalibrationPixelRangeOffsets or 848 * #Argus_GetCalibrationGlobalRangeOffsets function. 849 * 850 * @param hnd The API handle; contains all internal states and data. 851 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 852 *****************************************************************************/ 853 status_t Argus_ExecuteRelativeRangeOffsetCalibrationSequence(argus_hnd_t * hnd); 854 855 /*!*************************************************************************** 856 * @brief Executes an absolute range offset calibration measurement. 857 * 858 * @details This function immediately triggers an absolute range offset calibration 859 * measurement sequence. The ordinary measurement activity is suspended 860 * while the calibration is ongoing. 861 * 862 * In order to perform a relative range offset calibration, a flat 863 * calibration target must be setup perpendicular to the sensors 864 * field-of-view. 865 * 866 * \code 867 * AFBR-S50 ToF Sensor 868 * #| 869 * #| | 870 * #|-----+ | 871 * #| RX | | 872 * Reference #|----++ | Calibration 873 * Plane #| TX | | Target 874 * #|----+ | 875 * #| | 876 * #| <------- targetRange -----------------> | 877 * \endcode 878 * 879 * There are two options to run the offset calibration: relative and 880 * absolute. 881 * 882 * - Relative (#Argus_ExecuteRelativeRangeOffsetCalibrationSequence): 883 * when the absolute distance is not essential or the distance to 884 * the calibration target is not known, the relative method can be 885 * used to compensate the relative pixel range offset w.r.t. the 886 * average range. The absolute or global range offset is not changed. 887 * - Absolute (#Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence): 888 * when the absolute distance is essential and the distance to the 889 * calibration target is known, the absolute method can be used to 890 * calibrate the absolute measured distance. Additionally, the 891 * relative pixel offset w.r.t. the average range is also compensated. 892 * . 893 * 894 * After calibration has finished successfully, the obtained data is 895 * applied immediately and can be read from the API using the 896 * #Argus_GetCalibrationPixelRangeOffsets or 897 * #Argus_GetCalibrationGlobalRangeOffsets function. 898 * 899 * @param hnd The API handle; contains all internal states and data. 900 * @param targetRange The absolute range between the reference plane and the 901 * calibration target in meter an Q9.22 format. 902 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 903 *****************************************************************************/ 904 status_t Argus_ExecuteAbsoluteRangeOffsetCalibrationSequence(argus_hnd_t * hnd, 905 q9_22_t targetRange); 906 907 /*! @} */ 908 909 /*!************************************************************************** 910 * Configuration API 911 **************************************************************************** 912 * @addtogroup argus_cfg 913 * @{ 914 ****************************************************************************/ 915 916 /*!*************************************************************************** 917 * @brief Gets the default measurement mode for a specified module type. 918 * 919 * @param module The specified module type. 920 * @return Returns the default measurement mode for the specified module type. 921 *****************************************************************************/ 922 argus_mode_t Argus_GetDefaultMeasurementMode(argus_module_version_t module); 923 924 /*!*************************************************************************** 925 * @brief Sets the measurement mode to a specified device. 926 * 927 * @details This generates a new default configuration and calibration for the 928 * specified measurement mode and applies it to the device. 929 * 930 * See #argus_mode_t for a list of all available measurement modes. 931 * 932 * @warning The function overwrites all made changes to the configuration or 933 * calibration parameters with the default values. So this function 934 * must be called before any other changes to the configuration or 935 * calibration parameters are made! 936 * 937 * @param hnd The API handle; contains all internal states and data. 938 * @param mode The new measurement mode. 939 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 940 *****************************************************************************/ 941 status_t Argus_SetMeasurementMode(argus_hnd_t * hnd, argus_mode_t mode); 942 943 /*!*************************************************************************** 944 * @brief Resets the measurement mode to a specified device. 945 * 946 * @details This generates a new default configuration and calibration for the 947 * current measurement mode and applies it to the device. 948 * 949 * @warning The function overwrites all made changes to the configuration or 950 * calibration parameters with the default values. So this function 951 * must be called before any other changes to the configuration or 952 * calibration parameters are made! 953 * 954 * @param hnd The API handle; contains all internal states and data. 955 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 956 *****************************************************************************/ 957 status_t Argus_ResetMeasurementMode(argus_hnd_t * hnd); 958 959 /*!*************************************************************************** 960 * @brief Gets the measurement mode from a specified device. 961 * 962 * @param hnd The API handle; contains all internal states and data. 963 * @param mode The current measurement mode. 964 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 965 *****************************************************************************/ 966 status_t Argus_GetMeasurementMode(argus_hnd_t * hnd, argus_mode_t * mode); 967 968 /*!*************************************************************************** 969 * @brief Sets the frame time to a specified device. 970 * 971 * @details The frame time determines the measurement rate of the device. 972 * Usually, this controller the periodicity of measurements to be 973 * triggered via the timer based measurement mode that can be started 974 * via the #Argus_StartMeasurementTimer function. But also the 975 * behavior of the #Argus_TriggerMeasurement function is influenced 976 * by the frame rate parameter. 977 * 978 * The frame time parameter handles the maximum frame rate by limiting 979 * the trigger of a new measurement frame to the specified value. 980 * On the other hand, the accuracy of measurement results it also 981 * influenced since the frame time specifies the maximum integration 982 * depth (i.e. exposure time) along with the laser safety limitations. 983 * This means, the measurement speed can be increased by decreasing 984 * the frame time parameter and the accuracy can be improved by 985 * increasing the frame time parameter. 986 * 987 * Note the additional factor will limit the maximum frame rate on the 988 * one hand and the accuracy on the other hand: 989 * - High CPU load (or slow CPU in general) will lead to delays due 990 * to long data evaluation task (#Argus_EvaluateData) or long user 991 * application code. Reduce CPU load or increase CPU power to 992 * increase maximum frame rate. 993 * - The dual frequency mode (DFM, see #Argus_SetConfigurationDFMMode) 994 * will additionally limit the maximum frame rate to approximately 995 * 100 frames per second. Disable the DFM to increase maximum frame 996 * rates. 997 * - The smart power save (SPS, see 998 * #Argus_SetConfigurationSmartPowerSaveEnabled) mode will decrease 999 * the maximum possible frame rate slightly. Disable it to increase 1000 * the maximum frame rate. 1001 * - The dynamic configuration adaption with its specific power saving 1002 * ratio parameter (see #Argus_SetConfigurationDynamicAdaption) 1003 * will limit the maximum integration depth along with the laser 1004 * safety limitations. Increase the power saving ratio to increase 1005 * accuracy. Note that laser safety limitations might already limit 1006 * the maximum integration depth such that the power saving ratio 1007 * is ineffective. 1008 * . 1009 * 1010 * @param hnd The API handle; contains all internal states and data. 1011 * @param value The measurement frame time in microseconds. 1012 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1013 *****************************************************************************/ 1014 status_t Argus_SetConfigurationFrameTime(argus_hnd_t * hnd, uint32_t value); 1015 1016 /*!*************************************************************************** 1017 * @brief Gets the frame time from a specified device. 1018 * 1019 * @param hnd The API handle; contains all internal states and data. 1020 * @param value The current frame time in microseconds. 1021 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1022 *****************************************************************************/ 1023 status_t Argus_GetConfigurationFrameTime(argus_hnd_t * hnd, uint32_t * value); 1024 1025 /*!*************************************************************************** 1026 * @brief Sets the smart power save enabled flag to a specified device. 1027 * 1028 * @param hnd The API handle; contains all internal states and data. 1029 * @param value The new smart power save enabled flag. 1030 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1031 *****************************************************************************/ 1032 status_t Argus_SetConfigurationSmartPowerSaveEnabled(argus_hnd_t * hnd, 1033 bool value); 1034 1035 /*!*************************************************************************** 1036 * @brief Gets the smart power save enabled flag from a specified device. 1037 * 1038 * @param hnd The API handle; contains all internal states and data. 1039 * @param value The current smart power save enabled flag. 1040 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1041 *****************************************************************************/ 1042 status_t Argus_GetConfigurationSmartPowerSaveEnabled(argus_hnd_t * hnd, 1043 bool * value); 1044 1045 /*!*************************************************************************** 1046 * @brief Sets the Dual Frequency Mode (DFM) to a specified device. 1047 * 1048 * @param hnd The API handle; contains all internal states and data. 1049 * @param value The new DFM mode value. 1050 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1051 *****************************************************************************/ 1052 status_t Argus_SetConfigurationDFMMode(argus_hnd_t * hnd, 1053 argus_dfm_mode_t value); 1054 1055 1056 /*!*************************************************************************** 1057 * @brief Gets the Dual Frequency Mode (DFM) from a specified device. 1058 * 1059 * @param hnd The API handle; contains all internal states and data. 1060 * @param value The current DFM mode value. 1061 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1062 *****************************************************************************/ 1063 status_t Argus_GetConfigurationDFMMode(argus_hnd_t * hnd, 1064 argus_dfm_mode_t * value); 1065 1066 /*!*************************************************************************** 1067 * @brief Sets the Shot Noise Monitor (SNM) mode to a specified device. 1068 * 1069 * @param hnd The API handle; contains all internal states and data. 1070 * @param value The new SNM mode value. 1071 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1072 *****************************************************************************/ 1073 status_t Argus_SetConfigurationShotNoiseMonitorMode(argus_hnd_t * hnd, 1074 argus_snm_mode_t value); 1075 1076 /*!*************************************************************************** 1077 * @brief Gets the Shot Noise Monitor (SNM) mode from a specified device. 1078 * 1079 * @param hnd The API handle; contains all internal states and data. 1080 * @param value The current SNM mode value. 1081 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1082 *****************************************************************************/ 1083 status_t Argus_GetConfigurationShotNoiseMonitorMode(argus_hnd_t * hnd, 1084 argus_snm_mode_t * value); 1085 1086 /*!*************************************************************************** 1087 * @brief Sets the Crosstalk Monitor (XTM) mode to a specified device. 1088 * 1089 * @param hnd The API handle; contains all internal states and data. 1090 * @param value The new XTM mode value (true: enabled; false: disabled). 1091 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1092 *****************************************************************************/ 1093 status_t Argus_SetConfigurationCrosstalkMonitorMode(argus_hnd_t * hnd, 1094 bool value); 1095 1096 /*!*************************************************************************** 1097 * @brief Gets the Crosstalk Monitor (XTM) mode from a specified device. 1098 * 1099 * @param hnd The API handle; contains all internal states and data. 1100 * @param value The current XTM mode value (true: enabled; false: disabled). 1101 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1102 *****************************************************************************/ 1103 status_t Argus_GetConfigurationCrosstalkMonitorMode(argus_hnd_t * hnd, 1104 bool * value); 1105 1106 /*!*************************************************************************** 1107 * @brief Sets the full DCA module configuration to a specified device. 1108 * 1109 * @param hnd The API handle; contains all internal states and data. 1110 * @param value The new DCA configuration set. 1111 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1112 *****************************************************************************/ 1113 status_t Argus_SetConfigurationDynamicAdaption(argus_hnd_t * hnd, 1114 argus_cfg_dca_t const * value); 1115 1116 /*!*************************************************************************** 1117 * @brief Gets the # from a specified device. 1118 * 1119 * @param hnd The API handle; contains all internal states and data. 1120 * @param value The current DCA configuration set value. 1121 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1122 *****************************************************************************/ 1123 status_t Argus_GetConfigurationDynamicAdaption(argus_hnd_t * hnd, 1124 argus_cfg_dca_t * value); 1125 /*!*************************************************************************** 1126 * @brief Sets the pixel binning configuration parameters to a specified device. 1127 * 1128 * @param hnd The API handle; contains all internal states and data. 1129 * @param value The new pixel binning configuration parameters. 1130 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1131 *****************************************************************************/ 1132 status_t Argus_SetConfigurationPixelBinning(argus_hnd_t * hnd, 1133 argus_cfg_pba_t const * value); 1134 1135 /*!*************************************************************************** 1136 * @brief Gets the pixel binning configuration parameters from a specified device. 1137 * 1138 * @param hnd The API handle; contains all internal states and data. 1139 * @param value The current pixel binning configuration parameters. 1140 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1141 *****************************************************************************/ 1142 status_t Argus_GetConfigurationPixelBinning(argus_hnd_t * hnd, 1143 argus_cfg_pba_t * value); 1144 1145 /*!*************************************************************************** 1146 * @brief Gets the current unambiguous range in mm. 1147 * 1148 * @param hnd The API handle; contains all internal states and data. 1149 * @param range_mm The returned range in mm. 1150 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1151 *****************************************************************************/ 1152 status_t Argus_GetConfigurationUnambiguousRange(argus_hnd_t * hnd, 1153 uint32_t * range_mm); 1154 1155 /*! @} */ 1156 1157 /*!************************************************************************** 1158 * Calibration API 1159 **************************************************************************** 1160 * @addtogroup argus_cal 1161 * @{ 1162 ****************************************************************************/ 1163 1164 /*!*************************************************************************** 1165 * @brief Sets the global range offset values to a specified device. 1166 * 1167 * @details The global range offsets are subtracted from the raw range values. 1168 * There are two distinct values that are applied in low or high 1169 * power stage setting respectively. 1170 * 1171 * @param hnd The API handle; contains all internal states and data. 1172 * @param offset_low The new global range offset for the low power stage in 1173 * meter and Q0.15 format. 1174 * @param offset_high The new global range offset for the high power stage in 1175 * meter and Q0.15 format. 1176 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1177 *****************************************************************************/ 1178 status_t Argus_SetCalibrationGlobalRangeOffsets(argus_hnd_t * hnd, 1179 q0_15_t offset_low, 1180 q0_15_t offset_high); 1181 1182 /*!*************************************************************************** 1183 * @brief Gets the global range offset values from a specified device. 1184 * 1185 * @details The global range offsets are subtracted from the raw range values. 1186 * There are two distinct values that are applied in low or high 1187 * power stage setting respectively. 1188 * 1189 * @param hnd The API handle; contains all internal states and data. 1190 * @param offset_low The current range offset for the low power stage in 1191 * meter and Q0.15 format. 1192 * @param offset_high The current global range offset for the high power stage 1193 * in meter and Q0.15 format. 1194 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1195 *****************************************************************************/ 1196 status_t Argus_GetCalibrationGlobalRangeOffsets(argus_hnd_t * hnd, 1197 q0_15_t * offset_low, 1198 q0_15_t * offset_high); 1199 1200 /*!*************************************************************************** 1201 * @brief Sets the relative pixel offset table to a specified device. 1202 * 1203 * @details The relative pixel offset values are subtracted from the raw range 1204 * values for each individual pixel. Note that a global range offset 1205 * is applied additionally. The relative pixel offset values are meant 1206 * to be with respect to the average range of all pixels, i.e. the 1207 * average of all relative offsets should be 0! 1208 * 1209 * The crosstalk vector table is a two dimensional array of type 1210 * #q0_15_t, wrapped within the #argus_cal_offset_table_t structure. 1211 * 1212 * The dimensions are: 1213 * - size(0) = #ARGUS_PIXELS_X (Pixel count in x-direction) 1214 * - size(1) = #ARGUS_PIXELS_Y (Pixel count in y-direction) 1215 * . 1216 * 1217 * Its recommended to use the built-in pixel offset calibration 1218 * sequence (see #Argus_ExecuteRelativeRangeOffsetCalibrationSequence) 1219 * to determine the offset table for the current device. 1220 * 1221 * If a constant offset table for all device needs to be incorporated 1222 * into the sources, the #Argus_GetPixelRangeOffsets_Callback 1223 * should be used. 1224 * 1225 * @param hnd The API handle; contains all internal states and data. 1226 * @param value The new relative range offset in meter and Q0.15 format. 1227 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1228 *****************************************************************************/ 1229 status_t Argus_SetCalibrationPixelRangeOffsets(argus_hnd_t * hnd, 1230 argus_cal_offset_table_t const * value); 1231 1232 1233 /*!*************************************************************************** 1234 * @brief Gets the relative pixel offset table from a specified device. 1235 * 1236 * @details The relative pixel offset values are subtracted from the raw range 1237 * values for each individual pixel. Note that a global range offset 1238 * is applied additionally. The relative pixel offset values are meant 1239 * to be with respect to the average range of all pixels, i.e. the 1240 * average of all relative offsets should be 0! 1241 * 1242 * The crosstalk vector table is a two dimensional array of type 1243 * #q0_15_t, wrapped within the #argus_cal_offset_table_t structure. 1244 * 1245 * The dimensions are: 1246 * - size(0) = #ARGUS_PIXELS_X (Pixel count in x-direction) 1247 * - size(1) = #ARGUS_PIXELS_Y (Pixel count in y-direction) 1248 * . 1249 * 1250 * @param hnd The API handle; contains all internal states and data. 1251 * @param value The current relative range offset in meter and Q0.15 format. 1252 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1253 *****************************************************************************/ 1254 status_t Argus_GetCalibrationPixelRangeOffsets(argus_hnd_t * hnd, 1255 argus_cal_offset_table_t * value); 1256 1257 1258 /*!*************************************************************************** 1259 * @brief Resets the relative pixel offset values for the specified device to 1260 * the factory calibrated default values. 1261 * 1262 * @details The relative pixel offset values are subtracted from the raw range 1263 * values for each individual pixel. Note that a global range offset 1264 * is applied additionally. 1265 * 1266 * The factory defaults are device specific values. 1267 * 1268 * @param hnd The API handle; contains all internal states and data. 1269 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1270 *****************************************************************************/ 1271 status_t Argus_ResetCalibrationPixelRangeOffsets(argus_hnd_t * hnd); 1272 1273 /*!*************************************************************************** 1274 * @brief A callback that returns the external pixel range offsets. 1275 * 1276 * @details The function needs to be implemented by the host application in 1277 * order to set the external pixel range offsets values upon system 1278 * initialization. If not defined in user code, the default 1279 * implementation will return an all zero offset table, assuming there 1280 * is no (additional) external pixel range offset values. 1281 * 1282 * If defined in user code, the function must fill all offset values 1283 * in the provided \par offsets parameter with external range offset 1284 * values. 1285 * The values can be obtained by the calibration routine. 1286 * 1287 * Example usage: 1288 * 1289 * @code 1290 * status_t Argus_GetPixelRangeOffsets_Callback(argus_cal_offset_table_t offsets) 1291 * { 1292 * memset(offsets, 0, sizeof(argus_cal_offset_t)); 1293 * 1294 * // Set offset values in meter and Q0.15 format. 1295 * offsets.Table[0][0] = -3542; 1296 * offsets.Table[0][1] = -4385; 1297 * offsets.Table[0][2] = 2953; 1298 * // etc. 1299 * } 1300 * @endcode 1301 * 1302 * @param offsets The pixel range offsets in meter and Q0.15 format; to be 1303 * filled with data. 1304 * @param mode The current measurement mode. 1305 *****************************************************************************/ 1306 void Argus_GetPixelRangeOffsets_Callback(argus_cal_offset_table_t * offsets, 1307 argus_mode_t const mode); 1308 1309 /*!*************************************************************************** 1310 * @brief Sets the sample time for the range offset calibration sequence. 1311 * 1312 * @details Gets the measurement sample acquisition time for executing the 1313 * range offset calibration sequence and generate the offset data.\n 1314 * Units: msec. 1315 * 1316 * @note Since the range offset calibration is executed twice (once for 1317 * low and once for high laser power stages), the actual calibration 1318 * time will be twice as long as set by the sample time parameter. 1319 * 1320 * @param hnd The API handle; contains all internal states and data. 1321 * @param value The new range offset calibration sequence sample time. 1322 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1323 *****************************************************************************/ 1324 status_t Argus_SetCalibrationRangeOffsetSequenceSampleTime(argus_hnd_t * hnd, uint16_t value); 1325 1326 /*!*************************************************************************** 1327 * @brief Gets the sample time for the range offset calibration sequence. 1328 * 1329 * @details Gets the measurement sample acquisition time for executing the 1330 * range offset calibration sequence and generate the offset data.\n 1331 * Units: msec. 1332 * 1333 * @note Since the range offset calibration is executed twice (once for 1334 * low and once for high laser power stages), the actual calibration 1335 * time will be twice as long as set by the sample time parameter. 1336 * 1337 * @param hnd The API handle; contains all internal states and data. 1338 * @param value The current range offset calibration sequence sample time. 1339 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1340 *****************************************************************************/ 1341 status_t Argus_GetCalibrationRangeOffsetSequenceSampleTime(argus_hnd_t * hnd, uint16_t * value); 1342 1343 /*!*************************************************************************** 1344 * @brief Sets the pixel-to-pixel crosstalk compensation parameters to a specified device. 1345 * 1346 * @param hnd The API handle; contains all internal states and data. 1347 * @param value The new pixel-to-pixel crosstalk compensation parameters. 1348 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1349 *****************************************************************************/ 1350 status_t Argus_SetCalibrationCrosstalkPixel2Pixel(argus_hnd_t * hnd, 1351 argus_cal_p2pxtalk_t const * value); 1352 1353 /*!*************************************************************************** 1354 * @brief Gets the pixel-to-pixel crosstalk compensation parameters from a specified device. 1355 * 1356 * @param hnd The API handle; contains all internal states and data. 1357 * @param value The current pixel-to-pixel crosstalk compensation parameters. 1358 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1359 *****************************************************************************/ 1360 status_t Argus_GetCalibrationCrosstalkPixel2Pixel(argus_hnd_t * hnd, 1361 argus_cal_p2pxtalk_t * value); 1362 1363 1364 /*!*************************************************************************** 1365 * @brief Sets the custom crosstalk vector table to a specified device. 1366 * 1367 * @details The crosstalk vectors are subtracted from the raw sampling data 1368 * in the data evaluation phase. 1369 * 1370 * The crosstalk vector table is a three dimensional array of type 1371 * #xtalk_t. The #argus_cal_xtalk_table_t is the corresponding 1372 * typedef for the required data. 1373 * 1374 * The dimensions are: 1375 * - size(0) = #ARGUS_DFM_FRAME_COUNT (Dual-frequency mode A- or B-frame) 1376 * - size(1) = #ARGUS_PIXELS_X (Pixel count in x-direction) 1377 * - size(2) = #ARGUS_PIXELS_Y (Pixel count in y-direction) 1378 * . 1379 * 1380 * Its recommended to use the built-in crosstalk calibration sequence 1381 * (see #Argus_ExecuteXtalkCalibrationSequence) to determine the 1382 * crosstalk vector table. 1383 * 1384 * If a constant table for all device needs to be incorporated into 1385 * the sources, the #Argus_GetCrosstalkVectorTable_Callback 1386 * should be used. 1387 * 1388 * @param hnd The API handle; contains all internal states and data. 1389 * @param value The new crosstalk vector table. 1390 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1391 *****************************************************************************/ 1392 status_t Argus_SetCalibrationCrosstalkVectorTable(argus_hnd_t * hnd, 1393 argus_cal_xtalk_table_t const * value); 1394 1395 /*!*************************************************************************** 1396 * @brief Gets the custom crosstalk vector table from a specified device. 1397 * 1398 * @details The crosstalk vectors are subtracted from the raw sampling data 1399 * in the data evaluation phase. 1400 * 1401 * The crosstalk vector table is a three dimensional array of type 1402 * #xtalk_t. The #argus_cal_xtalk_table_t is the corresponding 1403 * typedef for the required data. 1404 * 1405 * The dimensions are: 1406 * - size(0) = #ARGUS_DFM_FRAME_COUNT (Dual-frequency mode A- or B-frame) 1407 * - size(1) = #ARGUS_PIXELS_X (Pixel count in x-direction) 1408 * - size(2) = #ARGUS_PIXELS_Y (Pixel count in y-direction) 1409 * . 1410 * 1411 * @param hnd The API handle; contains all internal states and data. 1412 * @param value The current crosstalk vector table. 1413 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1414 *****************************************************************************/ 1415 status_t Argus_GetCalibrationCrosstalkVectorTable(argus_hnd_t * hnd, 1416 argus_cal_xtalk_table_t * value); 1417 1418 /*!*************************************************************************** 1419 * @brief Resets the crosstalk vector table for the specified device to the 1420 * factory calibrated default values. 1421 * 1422 * @details The crosstalk vectors are subtracted from the raw sampling data 1423 * in the data evaluation phase. 1424 * * 1425 * The factory defaults are device specific calibrated values. 1426 * 1427 * @param hnd The API handle; contains all internal states and data. 1428 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1429 *****************************************************************************/ 1430 status_t Argus_ResetCalibrationCrosstalkVectorTable(argus_hnd_t * hnd); 1431 1432 /*!*************************************************************************** 1433 * @brief Sets the sample time for the crosstalk calibration sequence. 1434 * 1435 * @details Sets the measurement sample acquisition time for executing the 1436 * crosstalk calibration sequence and generate the crosstalk data.\n 1437 * Units: msec. 1438 * 1439 * @param hnd The API handle; contains all internal states and data. 1440 * @param value The new crosstalk calibration sequence sample time. 1441 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1442 *****************************************************************************/ 1443 status_t Argus_SetCalibrationCrosstalkSequenceSampleTime(argus_hnd_t * hnd, 1444 uint16_t value); 1445 1446 /*!*************************************************************************** 1447 * @brief Gets the sample time for the crosstalk calibration sequence. 1448 * 1449 * @details Gets the measurement sample acquisition time for executing the 1450 * crosstalk calibration sequence and generate the crosstalk data.\n 1451 * Units: msec. 1452 * 1453 * @param hnd The API handle; contains all internal states and data. 1454 * @param value The current crosstalk calibration sequence sample time. 1455 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1456 *****************************************************************************/ 1457 status_t Argus_GetCalibrationCrosstalkSequenceSampleTime(argus_hnd_t * hnd, 1458 uint16_t * value); 1459 1460 /*!*************************************************************************** 1461 * @brief Sets the max. amplitude threshold for the crosstalk calibration sequence. 1462 * 1463 * @details The maximum amplitude threshold defines a maximum crosstalk vector 1464 * amplitude before causing an error message. If the crosstalk is 1465 * too high, there is usually an issue with the measurement setup, i.e. 1466 * there is still a measurement signal detected. 1467 * 1468 * @param hnd The API handle; contains all internal states and data. 1469 * @param value The new crosstalk calibration sequence maximum amplitude 1470 * threshold value in UQ12.4 format. 1471 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1472 *****************************************************************************/ 1473 status_t Argus_SetCalibrationCrosstalkSequenceAmplitudeThreshold(argus_hnd_t * hnd, 1474 uq12_4_t value); 1475 1476 /*!*************************************************************************** 1477 * @brief Gets the max. amplitude threshold for the crosstalk calibration sequence. 1478 * 1479 * @details The maximum amplitude threshold defines a maximum crosstalk vector 1480 * amplitude before causing an error message. If the crosstalk is 1481 * too high, there is usually an issue with the measurement setup, i.e. 1482 * there is still a measurement signal detected. 1483 * 1484 * @param hnd The API handle; contains all internal states and data. 1485 * @param value The current max. amplitude threshold value in UQ12.4 format. 1486 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1487 *****************************************************************************/ 1488 status_t Argus_GetCalibrationCrosstalkSequenceAmplitudeThreshold(argus_hnd_t * hnd, 1489 uq12_4_t * value); 1490 1491 1492 /*!*************************************************************************** 1493 * @brief Clears all user calibration values from NVM for the specified device. 1494 * 1495 * @details The user calibration values are stored in the non-volatile memory 1496 * (NVM) if corresponding \link #argus_nvm NVM hardware layer\endlink 1497 * is implemented. This method clears the user calibration data from 1498 * the non-volatile memory. 1499 * 1500 * @warning This does not reset the currently set calibration values to 1501 * factory defaults! 1502 * 1503 * @param hnd The API handle; contains all internal states and data. 1504 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1505 *****************************************************************************/ 1506 status_t Argus_ClearUserCalibration(argus_hnd_t * hnd); 1507 1508 1509 /*!*************************************************************************** 1510 * @brief A callback that returns the external crosstalk vector table. 1511 * 1512 * @details The function needs to be implemented by the host application in 1513 * order to set the external crosstalk vector table upon system 1514 * initialization. If not defined in user code, the default 1515 * implementation will return an all zero vector table, assuming there 1516 * is no (additional) external crosstalk. 1517 * 1518 * If defined in user code, the function must fill all vector values 1519 * in the provided \par crosstalk parameter with external crosstalk 1520 * values. The values can be obtained by the calibration routine. 1521 * 1522 * Example usage: 1523 * 1524 * @code 1525 * status_t Argus_GetCrosstalkVectorTable_Callback( 1526 * argus_cal_xtalk_table_t * xtalk) 1527 * { 1528 * memset(xtalk, 0, sizeof(argus_cal_xtalk_table_t)); 1529 * 1530 * // Set crosstalk vectors in Q11.4 format. 1531 * // Note on dual-frequency frame index: 0 = A-Frame; 1 = B-Frame 1532 * xtalk.FrameA[0][0].dS = -9; xtalk.FrameB[0][0].dC = -11; 1533 * xtalk.FrameA[0][1].dS = -13; xtalk.FrameB[0][1].dC = -16; 1534 * xtalk.FrameA[0][2].dS = 6; xtalk.FrameB[0][2].dC = -18; 1535 * // etc. 1536 * } 1537 * @endcode 1538 * 1539 * @param xtalk The crosstalk vector array; to be filled with data. 1540 * @param mode The current measurement mode. 1541 *****************************************************************************/ 1542 void Argus_GetCrosstalkVectorTable_Callback(argus_cal_xtalk_table_t * xtalk, 1543 argus_mode_t const mode); 1544 1545 1546 /*!*************************************************************************** 1547 * @brief Gets the currently calibrated Golden Pixel coordinates. 1548 * 1549 * @details The Golden Pixel is the pixel that is located at the center of the 1550 * receiving light beam. Thus it it the one that receives the most 1551 * signal and plays a central role in 1D measurement systems. 1552 * 1553 * The function fills the provided \p x and \p y parameters with 1554 * the Golden Pixel coordinates. Typical values are x = 5 and y = 1 1555 * or 2. But the actual values depend on the specific sensor. 1556 * 1557 * Please also note the utility functions provided in the \ref argus_map 1558 * module to convert between pixel coordinates and channel numbers or 1559 * shift pixel maps by a position offset (#ShiftSelectedPixels) or 1560 * generate pixel masks centered around the Golden Pixel 1561 * (#FillPixelMask). 1562 * 1563 * @param hnd The API handle; contains all internal states and data. 1564 * @param x The Golden Pixel x-coordinate. 1565 * @param y The Golden Pixel y-coordinate. 1566 * @return Returns the \link #status_t status\endlink (#STATUS_OK on success). 1567 *****************************************************************************/ 1568 status_t Argus_GetCalibrationGoldenPixel(argus_hnd_t const * hnd, uint8_t * x, uint8_t * y); 1569 1570 /*! @} */ 1571 #ifdef __cplusplus 1572 } // extern "C" 1573 #endif 1574 #endif /* ARGUS_API_H */ 1575
