Skip to content

Commit

Permalink
drivers: broadcom AFBR update to API 1.5.6
Browse files Browse the repository at this point in the history
  • Loading branch information
@AlexKlimaj @dagar
AlexKlimaj authored and dagar committed Mar 9, 2024
1 parent 57df7e3 commit b81ad88
Show file tree
Hide file tree
Showing 16 changed files with 659 additions and 292 deletions.
109 changes: 97 additions & 12 deletions src/drivers/distance_sensor/broadcom/afbrs50/Inc/api/argus_api.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -160,6 +160,11 @@ status_t Argus_InitMode(argus_hnd_t *hnd, s2pi_slave_t spi_slave, argus_mode_t m
* Also refer to #Argus_ReinitMode, which uses a specified measurement
* mode instead of the currently active measurement mode.
*
* @note If a full re-initialization is not desired, refer to the
* #Argus_RestoreDeviceState function that will only re-write the
* register map to the device to restore its state after an power
* cycle.
*
* @param hnd The API handle; contains all internal states and data.
*
* @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
Expand All @@ -182,6 +187,11 @@ status_t Argus_Reinit(argus_hnd_t *hnd);
* Also refer to #Argus_Reinit, which re-uses the currently active
* measurement mode instead of an user specified measurement mode.
*
* @note If a full re-initialization is not desired, refer to the
* #Argus_RestoreDeviceState function that will only re-write the
* register map to the device to restore its state after an power
* cycle.
*
* @param hnd The API handle; contains all internal states and data.
*
* @param mode The specified measurement mode to be initialized.
Expand Down Expand Up @@ -274,6 +284,69 @@ argus_hnd_t *Argus_CreateHandle(void);
*****************************************************************************/
status_t Argus_DestroyHandle(argus_hnd_t *hnd);

/*!***************************************************************************
* @brief Restores the device state with a re-write of all register values.
*
* @details The function invalidates and restores the device state by executing
* a re-write of the full register map.
*
* The purpose of this function is to recover from known external
* events like power cycles, for example due to sleep / wake-up
* functionality. This can be implemented by cutting off the external
* power supply of the device (e.g. via a MOSFET switch controlled by
* a GPIB pin). By calling this function, the expected state of the
* API is written to the device without the need to fully re-initialize
* the device. Thus, the API can resume where it has stopped as if
* there has never been a power cycle.
*
* The internal state machines like the dynamic configuration adaption
* (DCA) algorithm will not be reseted. The API/sensor will immediately
* resume at the last state that was optimized for the given
* environmental conditions.
*
* The use case of sleep / wake-up can be implemented as follows:
*
* 1. In case of ongoing measurements, stop the measurements via
* the #Argus_StopMeasurementTimer function (if started by the
* #Argus_StartMeasurementTimer function).
*
* 2. Shut down the device by removing the 5V power supply, e.g.
* via a GPIO pin that switches a MOSFET circuit.
*
* 3. After the desired sleep period, power the device by switching
* the 5V power supply on again. Wait until the power-on-reset
* (POR) is finished (approx. 1 ms) or just repeat step 4 until
* it succeeds.
*
* 4. Call the #Argus_RestoreDeviceState function to trigger the
* restoration of the device state in the API. Note that the
* function will return an error code if it fails. One can repeat
* the execution of that function a few times until it succeeds.
*
* 6. Continue with measurements via #Argus_StartMeasurementTimer
* of #Argus_TriggerMeasurement functions as desired.
*
* @note If a complete re-initialization (= soft-reset) is desired, see
* the #Argus_Reinit functionality.
*
* @note Changing a configuration or calibration parameter will always
* invalidate the device state as well as the state machine of the
* dynamic configuration adaption (DCA) algorithm. In that case, the
* device/API needs a few measurements to adopt to the present
* environmental conditions before the first valid measurement result
* can be obtained. This is almost similar to re-initializing the
* device (see #Argus_Reinit) which would also re-read the EEPROM.
* On the other hand, the #Argus_RestoreDeviceState does not reset
* or re-initialize anything. It just makes sure that the device
* register map (which has changed to its reset values after the
* power cycle) is what the API expects upon the next measurement.
*
* @param hnd The device handle object to be invalidated.
*
* @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
*****************************************************************************/
status_t Argus_RestoreDeviceState(argus_hnd_t *hnd);

/*!**************************************************************************
* Generic API
****************************************************************************/
Expand Down Expand Up @@ -726,7 +799,7 @@ status_t Argus_ExecuteXtalkCalibrationSequence(argus_hnd_t *hnd);
* After calibration has finished successfully, the obtained data is
* applied immediately and can be read from the API using the
* #Argus_GetCalibrationPixelRangeOffsets or
* #Argus_GetCalibrationGlobalRangeOffset function.
* #Argus_GetCalibrationGlobalRangeOffsets function.
*
* @param hnd The API handle; contains all internal states and data.
* @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
Expand Down Expand Up @@ -775,7 +848,7 @@ status_t Argus_ExecuteRelativeRangeOffsetCalibrationSequence(argus_hnd_t *hnd);
* After calibration has finished successfully, the obtained data is
* applied immediately and can be read from the API using the
* #Argus_GetCalibrationPixelRangeOffsets or
* #Argus_GetCalibrationGlobalRangeOffset function.
* #Argus_GetCalibrationGlobalRangeOffsets function.
*
* @param hnd The API handle; contains all internal states and data.
* @param targetRange The absolute range between the reference plane and the
Expand Down Expand Up @@ -1043,28 +1116,40 @@ status_t Argus_GetConfigurationUnambiguousRange(argus_hnd_t *hnd,
****************************************************************************/

/*!***************************************************************************
* @brief Sets the global range offset value to a specified device.
* @brief Sets the global range offset values to a specified device.
*
* @details The global range offset is subtracted from the raw range values.
* @details The global range offsets are subtracted from the raw range values.
* There are two distinct values that are applied in low or high
* power stage setting respectively.
*
* @param hnd The API handle; contains all internal states and data.
* @param value The new global range offset in meter and Q0.15 format.
* @param offset_low The new global range offset for the low power stage in
* meter and Q0.15 format.
* @param offset_high The new global range offset for the high power stage in
* meter and Q0.15 format.
* @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
*****************************************************************************/
status_t Argus_SetCalibrationGlobalRangeOffset(argus_hnd_t *hnd,
q0_15_t value);
status_t Argus_SetCalibrationGlobalRangeOffsets(argus_hnd_t *hnd,
q0_15_t offset_low,
q0_15_t offset_high);

/*!***************************************************************************
* @brief Gets the global range offset value from a specified device.
* @brief Gets the global range offset values from a specified device.
*
* @details The global range offset is subtracted from the raw range values.
* @details The global range offsets are subtracted from the raw range values.
* There are two distinct values that are applied in low or high
* power stage setting respectively.
*
* @param hnd The API handle; contains all internal states and data.
* @param value The current global range offset in meter and Q0.15 format.
* @param offset_low The current range offset for the low power stage in
* meter and Q0.15 format.
* @param offset_high The current global range offset for the high power stage
* in meter and Q0.15 format.
* @return Returns the \link #status_t status\endlink (#STATUS_OK on success).
*****************************************************************************/
status_t Argus_GetCalibrationGlobalRangeOffset(argus_hnd_t *hnd,
q0_15_t *value);
status_t Argus_GetCalibrationGlobalRangeOffsets(argus_hnd_t *hnd,
q0_15_t *offset_low,
q0_15_t *offset_high);

/*!***************************************************************************
* @brief Sets the relative pixel offset table to a specified device.
Expand Down
65 changes: 46 additions & 19 deletions src/drivers/distance_sensor/broadcom/afbrs50/Inc/api/argus_dca.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -210,9 +210,13 @@ typedef enum argus_dca_gain_t {
* - [9]: #ARGUS_STATE_LASER_ERROR
* - [10]: #ARGUS_STATE_HAS_DATA
* - [11]: #ARGUS_STATE_HAS_AUX_DATA
* - [12]: #ARGUS_STATE_DCA_MAX
* - [12]: #ARGUS_STATE_SATURATED_PIXELS
* - [13]: DCA Power Stage
* - [14-15]: DCA Gain Stages
* - [16]: #ARGUS_STATE_DCA_MIN
* - [17]: #ARGUS_STATE_DCA_MAX
* - [18]: #ARGUS_STATE_DCA_RESET
* - [18-31]: not used
* .
*****************************************************************************/
typedef enum argus_state_t {
Expand All @@ -229,36 +233,35 @@ typedef enum argus_state_t {
* - 1: Enabled: measurement with detuned frequency. */
ARGUS_STATE_DUAL_FREQ_MODE = 1U << 1U,

/*! 0x0004: Measurement Frequency for Dual Frequency Mode
/*! 0x0004: Measurement Frequency for Dual Frequency Mode \n
* (only if #ARGUS_STATE_DUAL_FREQ_MODE flag is set).
* - 0: A-Frame w/ detuned frequency,
* - 1: B-Frame w/ detuned frequency */
ARGUS_STATE_MEASUREMENT_FREQ = 1U << 2U,

/*! 0x0008: Debug Mode. If set, the range value of erroneous pixels
/*! 0x0008: Debug Mode. \n
* If set, the range value of erroneous pixels
* are not cleared or reset.
* - 0: Disabled (default).
* - 1: Enabled. */
ARGUS_STATE_DEBUG_MODE = 1U << 3U,

/*! 0x0010: Weak Signal Flag.
/*! 0x0010: Weak Signal Flag. \n
* Set whenever the Pixel Binning Algorithm is detecting a
* weak signal, i.e. if the amplitude dies not reach its
* (absolute) threshold. If the Golden Pixel is enabled,
* this also indicates that the Pixel Binning Algorithm
* falls back to the Golden Pixel.
* (absolute) threshold.
* - 0: Normal Signal.
* - 1: Weak Signal or Golden Pixel Mode. */
* - 1: Weak Signal. */
ARGUS_STATE_WEAK_SIGNAL = 1U << 4U,

/*! 0x0020: Background Light Warning Flag.
/*! 0x0020: Background Light Warning Flag. \n
* Set whenever the background light is very high and the
* measurement data might be unreliable.
* - 0: No Warning: Background Light is within valid range.
* - 1: Warning: Background Light is very high. */
ARGUS_STATE_BGL_WARNING = 1U << 5U,

/*! 0x0040: Background Light Error Flag.
/*! 0x0040: Background Light Error Flag. \n
* Set whenever the background light is too high and the
* measurement data is unreliable or invalid.
* - 0: No Error: Background Light is within valid range.
Expand All @@ -270,7 +273,7 @@ typedef enum argus_state_t {
* - 1: PLL locked at start of integration. */
ARGUS_STATE_PLL_LOCKED = 1U << 7U,

/*! 0x0100: Laser Failure Warning Flag.
/*! 0x0100: Laser Failure Warning Flag. \n
* Set whenever the an invalid system condition is detected.
* (i.e. DCA at max state but no amplitude on any (incl. reference)
* pixel, not amplitude but any saturated pixel).
Expand All @@ -279,7 +282,7 @@ typedef enum argus_state_t {
* condition stays, a laser malfunction error is raised. */
ARGUS_STATE_LASER_WARNING = 1U << 8U,

/*! 0x0200: Laser Failure Error Flag.
/*! 0x0200: Laser Failure Error Flag. \n
* Set whenever a laser malfunction error is raised and the
* system is put into a safe state.
* - 0: No Error: Laser is operating properly.
Expand All @@ -297,13 +300,12 @@ typedef enum argus_state_t {
* - 1: Auxiliary data is available and correctly evaluated. */
ARGUS_STATE_HAS_AUX_DATA = 1U << 11U,

/*! 0x1000: DCA Maximum State Flag.
* Set whenever the DCA has extended all its parameters to their
* maximum values and can not increase the integration energy any
* further.
* - 0: DCA has not yet reached its maximum state.
* - 1: DCA has reached its maximum state and can not increase any further. */
ARGUS_STATE_DCA_MAX = 1U << 12U,
/*! 0x0100: Pixel Saturation Flag. \n
* Set whenever any pixel is saturated, i.e. its pixel state is
* #PIXEL_SAT
* - 0: No saturated pixels.
* - 1: Any saturated pixels. */
ARGUS_STATE_SATURATED_PIXELS = 1U << 12U,

/*! 0x2000: DCA is in high Optical Output Power stage. */
ARGUS_STATE_DCA_POWER_HIGH = DCA_POWER_HIGH << ARGUS_STATE_DCA_POWER_SHIFT,
Expand All @@ -320,6 +322,31 @@ typedef enum argus_state_t {
/*! 0xC000: DCA is in high Pixel Input Gain stage. */
ARGUS_STATE_DCA_GAIN_HIGH = DCA_GAIN_HIGH << ARGUS_STATE_DCA_GAIN_SHIFT,

/*! 0x10000: DCA Minimum State Flag. \n
* Set whenever the DCA has reduced all its parameters to their
* minimum values and it can not decrease the integration energy
* any further.
* - 0: DCA has not yet reached its minimum state.
* - 1: DCA has reached its minimum state and can not decrease
* its parameters any further. */
ARGUS_STATE_DCA_MIN = 1U << 16U,

/*! 0x20000: DCA Maximum State Flag. \n
* Set whenever the DCA has extended all its parameters to their
* maximum values and it can not increase the integration energy
* any further.
* - 0: DCA has not yet reached its maximum state.
* - 1: DCA has reached its maximum state and can not increase
* its parameters any further. */
ARGUS_STATE_DCA_MAX = 1U << 17U,

/*! 0x20000: DCA Reset State Flag. \n
* Set whenever the DCA is resetting all its parameters to their
* minimum values because it has detected too many saturated pixels.
* - 0: DCA is operating in normal mode.
* - 1: DCA is performing a reset. */
ARGUS_STATE_DCA_RESET = 1U << 18U,

} argus_state_t;

/*!***************************************************************************
Expand Down
Loading

0 comments on commit b81ad88

Please sign in to comment.