### Configure Ranging Profile — VL53L5CX_ConfigProfile

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Selects the ranging profile (resolution and mode), timing budget, output frequency, and enables optional ambient/signal output fields. Must be called before starting ranging.

```c
#include "vl53l5cx.h"

VL53L5CX_ProfileConfig_t Profile = {
    .RangingProfile = VL53L5CX_PROFILE_8x8_CONTINUOUS,  /* 8×8 zone, continuous */
    .TimingBudget   = 10,    /* 10 ms per measurement */
    .Frequency      = 10,    /* 10 Hz */
    .EnableAmbient  = 1,     /* report ambient noise */
    .EnableSignal   = 1,     /* report signal rate */
};

int32_t ret = VL53L5CX_ConfigProfile(&VL53L5CX_Obj, &Profile);
if (ret != VL53L5CX_OK) { Error_Handler(); }
```

```c
/* Alternatively use 4×4 autonomous mode at 30 Hz */
Profile.RangingProfile = VL53L5CX_PROFILE_4x4_AUTONOMOUS;
Profile.Frequency      = 30;
Profile.TimingBudget   = 15;
VL53L5CX_ConfigProfile(&VL53L5CX_Obj, &Profile);
```

--------------------------------

### Start / Stop Ranging — VL53L5CX_Start / VL53L5CX_Stop

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Starts or stops the measurement stream. Four modes control whether the driver blocks waiting for data and whether ranging is continuous or single-shot.

```c
#include "vl53l5cx.h"

/* Start in blocking continuous mode — GetDistance() will wait internally */
int32_t ret = VL53L5CX_Start(&VL53L5CX_Obj, VL53L5CX_MODE_BLOCKING_CONTINUOUS);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* ... perform measurements ... */

ret = VL53L5CX_Stop(&VL53L5CX_Obj);
if (ret != VL53L5CX_OK) { Error_Handler(); }
```

```c
/* Available modes:
 * VL53L5CX_MODE_BLOCKING_CONTINUOUS   — blocks until data ready, loops
 * VL53L5CX_MODE_BLOCKING_ONESHOT      — blocks until single measurement done
 * VL53L5CX_MODE_ASYNC_CONTINUOUS      — non-blocking, continuous, poll manually
 * VL53L5CX_MODE_ASYNC_ONESHOT         — non-blocking, single shot
 */
```

--------------------------------

### Ranging Data Loop: Check and Get Data

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

The standard ranging loop: start ranging, poll for new data, read results, and process each zone. Returns all fields configured in the active output mask.

```c
#include "vl53l5cx_api.h"
#include <stdio.h>

uint8_t status, isReady;
VL53L5CX_ResultsData Results;

status = vl53l5cx_set_resolution(&Dev, VL53L5CX_RESOLUTION_4X4);
status = vl53l5cx_set_ranging_frequency_hz(&Dev, 15);
status = vl53l5cx_start_ranging(&Dev);

for (int sample = 0; sample < 50; sample++) {
    /* Poll until new frame available */
    do {
        status = vl53l5cx_check_data_ready(&Dev, &isReady);
    } while (!isReady);

    status = vl53l5cx_get_ranging_data(&Dev, &Results);
    if (status != VL53L5CX_STATUS_OK) { continue; }

    printf("Silicon temp: %d°C\n", Results.silicon_temp_degc);
    for (int z = 0; z < 16; z++) {   /* 4×4 = 16 zones */
        printf("Zone[%2d]: nb_targets=%u, dist=%d mm, status=%u\n",
            z,
            Results.nb_target_detected[z],
            Results.distance_mm[z],
            Results.target_status[z]);
    }
}

vl53l5cx_stop_ranging(&Dev);
```

--------------------------------

### Configure Ranging Profile

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Selects the ranging profile (resolution and mode), timing budget, output frequency, and enables optional ambient/signal output fields. Must be called before starting ranging.

```APIDOC
## Configure Ranging Profile — `VL53L5CX_ConfigProfile`

Selects the ranging profile (resolution and mode), timing budget, output frequency, and enables optional ambient/signal output fields. Must be called before starting ranging.

```c
#include "vl53l5cx.h"

VL53L5CX_ProfileConfig_t Profile = {
    .RangingProfile = VL53L5CX_PROFILE_8x8_CONTINUOUS,  /* 8×8 zone, continuous */
    .TimingBudget   = 10,    /* 10 ms per measurement */
    .Frequency      = 10,    /* 10 Hz */
    .EnableAmbient  = 1,     /* report ambient noise */
    .EnableSignal   = 1,     /* report signal rate */
};

int32_t ret = VL53L5CX_ConfigProfile(&VL53L5CX_Obj, &Profile);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* Alternatively use 4×4 autonomous mode at 30 Hz */
Profile.RangingProfile = VL53L5CX_PROFILE_4x4_AUTONOMOUS;
Profile.Frequency      = 30;
Profile.TimingBudget   = 15;
VL53L5CX_ConfigProfile(&VL53L5CX_Obj, &Profile);
```
```

--------------------------------

### Start / Stop Ranging

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Starts or stops the measurement stream. Four modes control whether the driver blocks waiting for data and whether ranging is continuous or single-shot.

```APIDOC
## Start / Stop Ranging — `VL53L5CX_Start` / `VL53L5CX_Stop`

Starts or stops the measurement stream. Four modes control whether the driver blocks waiting for data and whether ranging is continuous or single-shot.

```c
#include "vl53l5cx.h"

/* Start in blocking continuous mode — GetDistance() will wait internally */
int32_t ret = VL53L5CX_Start(&VL53L5CX_Obj, VL53L5CX_MODE_BLOCKING_CONTINUOUS);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* ... perform measurements ... */

ret = VL53L5CX_Stop(&VL53L5CX_Obj);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* Available modes:
 * VL53L5CX_MODE_BLOCKING_CONTINUOUS   — blocks until data ready, loops
 * VL53L5CX_MODE_BLOCKING_ONESHOT      — blocks until single measurement done
 * VL53L5CX_MODE_ASYNC_CONTINUOUS      — non-blocking, continuous, poll manually
 * VL53L5CX_MODE_ASYNC_ONESHOT         — non-blocking, single shot
 */
```
```

--------------------------------

### Set Resolution

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Switches the sensor between 4x4 (16 zones) and 8x8 (64 zones) scanning grids. This must be set before starting ranging and before configuring the motion indicator.

```APIDOC
## Set Resolution — `vl53l5cx_set_resolution` / `vl53l5cx_get_resolution`

Switches the sensor between 4x4 (16 zones) and 8x8 (64 zones) scanning grids. Resolution must be set before starting ranging and before configuring the motion indicator.

### Example Usage:
```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t resolution;

/* Switch to 8x8 mode */
status = vl53l5cx_set_resolution(&Dev, VL53L5CX_RESOLUTION_8X8);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Verify */
status = vl53l5cx_get_resolution(&Dev, &resolution);
/* resolution == 64 for 8x8, 16 for 4x4 */
printf("Active resolution: %u zones\n", resolution);
```
```

--------------------------------

### Set Sensor Resolution (4x4 or 8x8)

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Switches the sensor between 4x4 (16 zones) and 8x8 (64 zones) scanning grids. Resolution must be set before starting ranging and before configuring the motion indicator.

```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t resolution;

/* Switch to 8×8 mode */
status = vl53l5cx_set_resolution(&Dev, VL53L5CX_RESOLUTION_8X8);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Verify */
status = vl53l5cx_get_resolution(&Dev, &resolution);
/* resolution == 64 for 8×8, 16 for 4×4 */
printf("Active resolution: %u zones\n", resolution);
```

--------------------------------

### Ranging Data Loop

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

The standard ranging loop involves starting ranging, polling for new data, reading results, and processing each zone. This function returns all fields configured in the active output mask.

```APIDOC
## Ranging Data Loop — `vl53l5cx_check_data_ready` / `vl53l5cx_get_ranging_data`

The standard ranging loop: start ranging, poll for new data, read results, and process each zone. Returns all fields configured in the active output mask.

### Example Usage:
```c
#include "vl53l5cx_api.h"
#include <stdio.h>

uint8_t status, isReady;
VL53L5CX_ResultsData Results;

status = vl53l5cx_set_resolution(&Dev, VL53L5CX_RESOLUTION_4X4);
status = vl53l5cx_set_ranging_frequency_hz(&Dev, 15);
status = vl53l5cx_start_ranging(&Dev);

for (int sample = 0; sample < 50; sample++) {
    /* Poll until new frame available */
    do {
        status = vl53l5cx_check_data_ready(&Dev, &isReady);
    } while (!isReady);

    status = vl53l5cx_get_ranging_data(&Dev, &Results);
    if (status != VL53L5CX_STATUS_OK) { continue; }

    printf("Silicon temp: %d°C\n", Results.silicon_temp_degc);
    for (int z = 0; z < 16; z++) {   /* 4x4 = 16 zones */
        printf("Zone[%2d]: nb_targets=%u, dist=%d mm, status=%u\n",
            z,
            Results.nb_target_detected[z],
            Results.distance_mm[z],
            Results.target_status[z]);
    }
}

vl53l5cx_stop_ranging(&Dev);
```
```

--------------------------------

### Initialize VL53L5CX Sensor with BSP Component

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Register platform I/O callbacks using `VL53L5CX_RegisterBusIO` and then initialize the sensor through the BSP interface with `VL53L5CX_Init`. This approach provides compatibility with STM32Cube BSP board drivers.

```c
#include "vl53l5cx.h"

VL53L5CX_Object_t VL53L5CX_Obj = {0};
VL53L5CX_IO_t     VL53L5CX_IO  = {0};

/* Fill the IO structure with platform-specific callbacks */
VL53L5CX_IO.Init     = BSP_I2C1_Init;      /* returns int32_t */
VL53L5CX_IO.DeInit   = BSP_I2C1_DeInit;
VL53L5CX_IO.WriteReg = BSP_I2C1_WriteReg;  /* (addr, reg, pdata, len) */
VL53L5CX_IO.ReadReg  = BSP_I2C1_ReadReg;
VL53L5CX_IO.GetTick  = BSP_GetTick;
VL53L5CX_IO.Address  = VL53L5CX_DEVICE_ADDRESS;  /* 0x52 */

int32_t ret;
ret = VL53L5CX_RegisterBusIO(&VL53L5CX_Obj, &VL53L5CX_IO);
if (ret != VL53L5CX_OK) { Error_Handler(); }

ret = VL53L5CX_Init(&VL53L5CX_Obj);
if (ret != VL53L5CX_OK) { Error_Handler(); }
/* VL53L5CX_Obj.IsInitialized == 1 */
```

--------------------------------

### Initialize VL53L5CX Sensor with ULD API

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Check sensor presence using `vl53l5cx_is_alive` and then initialize the sensor and upload firmware using `vl53l5cx_init`. Ensure the platform structure is correctly populated before calling these functions.

```c
#include "vl53l5cx_api.h"

VL53L5CX_Configuration Dev = {0};
Dev.platform = platform;  /* from previous step */

uint8_t p_is_alive = 0;
uint8_t status;

/* Check sensor presence */
status = vl53l5cx_is_alive(&Dev, &p_is_alive);
if (status != VL53L5CX_STATUS_OK || !p_is_alive) {
    /* Sensor not detected — check wiring or I2C address */
    Error_Handler();
}

/* Initialize sensor and upload firmware */
status = vl53l5cx_init(&Dev);
if (status != VL53L5CX_STATUS_OK) {
    /* Initialization failed */
    Error_Handler();
}
/* Sensor is now ready for configuration */
```

--------------------------------

### Implement Platform I/O Callbacks for VL53L5CX

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Implement the mandatory platform functions for I2C communication and timing. These callbacks abstract hardware interactions, making the driver portable across different STM32 platforms.

```c
#include "platform.h"

/* Example: STM32 HAL-based platform implementation */
static int32_t My_I2C_Write(uint16_t dev_addr, uint16_t reg, uint8_t *data, uint16_t len)
{
    /* Write register address (2 bytes) then data over HAL I2C */
    uint8_t buf[2 + len];
    buf[0] = (reg >> 8) & 0xFF;
    buf[1] = reg & 0xFF;
    memcpy(&buf[2], data, len);
    return (HAL_I2C_Master_Transmit(&hi2c1, dev_addr, buf, 2 + len, 100) == HAL_OK) ? 0 : 1;
}

static int32_t My_I2C_Read(uint16_t dev_addr, uint16_t reg, uint8_t *data, uint16_t len)
{
    uint8_t reg_buf[2] = { (reg >> 8) & 0xFF, reg & 0xFF };
    HAL_I2C_Master_Transmit(&hi2c1, dev_addr, reg_buf, 2, 100);
    return (HAL_I2C_Master_Receive(&hi2c1, dev_addr, data, len, 100) == HAL_OK) ? 0 : 1;
}

static int32_t My_GetTick(void)
{
    return (int32_t)HAL_GetTick();
}

/* Populate platform struct */
VL53L5CX_Platform platform = {
    .address = VL53L5CX_DEFAULT_I2C_ADDRESS,   /* 0x52 */
    .Write   = My_I2C_Write,
    .Read    = My_I2C_Read,
    .GetTick = My_GetTick,
};

/* WaitMs and SwapBuffer are implemented in porting/platform.c and use the above */
```

--------------------------------

### Perform and Apply Xtalk Calibration

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Runs crosstalk calibration, retrieves the calibration data, and applies it to the device. Optionally, the Xtalk margin can be adjusted.

```c
#include "vl53l5cx_plugin_xtalk.h"

uint8_t status;
uint8_t xtalk_data[VL53L5CX_XTALK_BUFFER_SIZE];

/* Run Xtalk calibration:
 * - reflectance_percent = 3  (3% target reflectance, ST recommendation)
 * - nb_samples = 5           (higher = more accurate, range 1–16)
 * - distance_mm = 600        (target at 600 mm, range 600–3000 mm)
 */
status = vl53l5cx_calibrate_xtalk(&Dev, 3, 5, 600);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Extract the calibration buffer to persist in flash/EEPROM */
status = vl53l5cx_get_caldata_xtalk(&Dev, xtalk_data);

/* --- On next power-on, reload from storage instead of re-running calibration --- */
/* vl53l5cx_init(&Dev); */
status = vl53l5cx_set_caldata_xtalk(&Dev, xtalk_data);

/* Optionally adjust Xtalk margin (default: 50 kcps/spads) */
uint32_t margin = 0;
vl53l5cx_get_xtalk_margin(&Dev, &margin);
printf("Current Xtalk margin: %lu kcps/spads\n", margin);

status = vl53l5cx_set_xtalk_margin(&Dev, 100);  /* increase threshold */
```

--------------------------------

### Motion Indicator Plugin

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Initializes and configures the on-sensor motion detection engine. It computes per-zone motion indicators using a temporal aggregation algorithm and allows monitoring motion within a specified distance range. Motion results are available after each ranging call.

```APIDOC
## vl53l5cx_motion_indicator_init / vl53l5cx_motion_indicator_set_distance_motion

### Description
Initializes the on-sensor motion detection engine, which computes per-zone motion indicators using a temporal aggregation algorithm. By default monitors motion between 400 mm and 1500 mm. Motion results appear in `ResultsData.motion_indicator` after each ranging call.

### Initialize motion indicator for 8x8 resolution
```c
status = vl53l5cx_motion_indicator_init(&Dev, &MotionConfig, VL53L5CX_RESOLUTION_8X8);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }
```

### Narrow the monitored distance window to 600 mm – 2000 mm
```c
status = vl53l5cx_motion_indicator_set_distance_motion(&Dev, &MotionConfig, 600, 2000);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }
```

### Retrieve Motion Data
```c
VL53L5CX_ResultsData Results;
vl53l5cx_get_ranging_data(&Dev, &Results);

printf("Global motion indicator 1: %lu\n", Results.motion_indicator.global_indicator_1);
printf("Global motion indicator 2: %lu\n", Results.motion_indicator.global_indicator_2);
printf("Motion status: %u\n",              Results.motion_indicator.status);
printf("Detected aggregates: %u / %u\n",
    Results.motion_indicator.nb_of_detected_aggregates,
    Results.motion_indicator.nb_of_aggregates);

for (int i = 0; i < 32; i++) {
    printf("motion[%2d] = %lu\n", i, Results.motion_indicator.motion[i]);
}
```
```

--------------------------------

### Initialize and Configure Motion Indicator

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Initializes the on-sensor motion detection engine and sets a custom distance window for monitoring. Motion results are available after each ranging call.

```c
#include "vl53l5cx_plugin_motion_indicator.h"

VL53L5CX_Motion_Configuration MotionConfig = {0};
uint8_t status;

/* Initialize motion indicator for 8×8 resolution */
status = vl53l5cx_motion_indicator_init(&Dev, &MotionConfig, VL53L5CX_RESOLUTION_8X8);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Narrow the monitored distance window to 600 mm – 2000 mm */
status = vl53l5cx_motion_indicator_set_distance_motion(&Dev, &MotionConfig, 600, 2000);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* After ranging: */
VL53L5CX_ResultsData Results;
vl53l5cx_get_ranging_data(&Dev, &Results);

printf("Global motion indicator 1: %lu\n", Results.motion_indicator.global_indicator_1);
printf("Global motion indicator 2: %lu\n", Results.motion_indicator.global_indicator_2);
printf("Motion status: %u\n",              Results.motion_indicator.status);
printf("Detected aggregates: %u / %u\n",
    Results.motion_indicator.nb_of_detected_aggregates,
    Results.motion_indicator.nb_of_aggregates);

for (int i = 0; i < 32; i++) {
    printf("motion[%2d] = %lu\n", i, Results.motion_indicator.motion[i]);
}
```

--------------------------------

### Configure and Enable Detection Thresholds

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Programs hardware-based detection checkers for interrupt generation based on measurement values per zone. The array must be terminated with VL53L5CX_LAST_THRESHOLD. Thresholds can be enabled or disabled, and their status can be verified.

```c
#include "vl53l5cx_plugin_detection_thresholds.h"

VL53L5CX_DetectionThresholds thresholds[VL53L5CX_NB_THRESHOLDS] = {0};
uint8_t status;

/* Checker 0: trigger if zone 0 distance is below 300 mm */
thresholds[0].measurement          = VL53L5CX_DISTANCE_MM;
thresholds[0].type                 = VL53L5CX_LESS_THAN_EQUAL_MIN_CHECKER;
thresholds[0].param_low_thresh     = 300;
thresholds[0].param_high_thresh    = 300;
thresholds[0].zone_num             = 0;
thresholds[0].mathematic_operation = VL53L5CX_OPERATION_OR;

/* Checker 1: AND — zone 0 signal must also be > 2000 kcps/spad */
thresholds[1].measurement          = VL53L5CX_SIGNAL_PER_SPAD_KCPS;
thresholds[1].type                 = VL53L5CX_GREATER_THAN_MAX_CHECKER;
thresholds[1].param_low_thresh     = 2000;
thresholds[1].param_high_thresh    = 2000;
thresholds[1].zone_num             = 0 | VL53L5CX_LAST_THRESHOLD;  /* last entry */
thresholds[1].mathematic_operation = VL53L5CX_OPERATION_AND;

status = vl53l5cx_set_detection_thresholds(&Dev, thresholds);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Enable threshold-based interrupt filtering */
status = vl53l5cx_set_detection_thresholds_enable(&Dev, 1);

/* Verify */
uint8_t enabled = 0;
vl53l5cx_get_detection_thresholds_enable(&Dev, &enabled);
printf("Thresholds enabled: %u\n", enabled);
```

--------------------------------

### Xtalk Calibration Plugin

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Performs or applies a crosstalk (Xtalk) calibration to compensate for light reflected off a coverglass. Calibration data can be saved and reloaded, and the Xtalk margin can be adjusted.

```APIDOC
## vl53l5cx_calibrate_xtalk / vl53l5cx_get_caldata_xtalk / vl53l5cx_set_caldata_xtalk

### Description
Performs or applies a crosstalk (Xtalk) calibration to compensate for light reflected off a coverglass mounted over the sensor. Calibration data can be saved to non-volatile storage and reloaded at startup. The Xtalk margin adjusts the calibration threshold.

### Run Xtalk calibration
```c
/* Parameters:
 * - reflectance_percent = 3  (3% target reflectance, ST recommendation)
 * - nb_samples = 5           (higher = more accurate, range 1–16)
 * - distance_mm = 600        (target at 600 mm, range 600–3000 mm)
 */
status = vl53l5cx_calibrate_xtalk(&Dev, 3, 5, 600);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }
```

### Extract calibration buffer
```c
status = vl53l5cx_get_caldata_xtalk(&Dev, xtalk_data);
```

### Apply calibration buffer (e.g., after power-on)
```c
status = vl53l5cx_set_caldata_xtalk(&Dev, xtalk_data);
```

### Adjust Xtalk margin
```c
uint32_t margin = 0;
vl53l5cx_get_xtalk_margin(&Dev, &margin);
printf("Current Xtalk margin: %lu kcps/spads\n", margin);

status = vl53l5cx_set_xtalk_margin(&Dev, 100);  /* increase threshold */
```
```

--------------------------------

### Set Target Order (Closest or Strongest)

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Controls how multiple targets per zone are sorted in the results: by closest distance or by strongest signal return.

```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t target_order;

/* Report closest target first */
status = vl53l5cx_set_target_order(&Dev, VL53L5CX_TARGET_ORDER_CLOSEST);
if (status == VL53L5CX_STATUS_INVALID_PARAM) {
    /* Unknown order value */
}

vl53l5cx_get_target_order(&Dev, &target_order);
/* target_order == VL53L5CX_TARGET_ORDER_CLOSEST (1) or
 *                 VL53L5CX_TARGET_ORDER_STRONGEST (2) */
```

--------------------------------

### Change Sensor I2C Address and Power Mode

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Demonstrates changing the sensor's I2C address and controlling its power state (sleep/wakeup) using BSP wrapper functions.

```c
#include "vl53l5cx.h"

int32_t ret;
uint32_t address;

/* Change address from 0x52 to 0x54 for multi-sensor bus sharing */
ret = VL53L5CX_SetAddress(&VL53L5CX_Obj, 0x54);
if (ret != VL53L5CX_OK) { Error_Handler(); }

ret = VL53L5CX_GetAddress(&VL53L5CX_Obj, &address);
printf("New address: 0x%02lX\n", address);  /* 0x54 */

/* Enter low-power sleep */
uint32_t powerMode;
ret = VL53L5CX_SetPowerMode(&VL53L5CX_Obj, VL53L5CX_POWER_MODE_SLEEP);
ret = VL53L5CX_GetPowerMode(&VL53L5CX_Obj, &powerMode);
printf("Power mode: %lu\n", powerMode);  /* 0 = sleep */

/* Wake up */
ret = VL53L5CX_SetPowerMode(&VL53L5CX_Obj, VL53L5CX_POWER_MODE_WAKEUP);
```

--------------------------------

### vl53l5cx_set_detection_thresholds / vl53l5cx_set_detection_thresholds_enable

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Programs up to 64 hardware-based detection checkers that gate interrupt generation based on measurement values. The array must be terminated with `VL53L5CX_LAST_THRESHOLD` in the `zone_num` field of the last entry.

```APIDOC
## vl53l5cx_set_detection_thresholds / vl53l5cx_set_detection_thresholds_enable

### Description
Programs up to 64 hardware-based detection checkers that gate interrupt generation based on measurement values (distance, signal, ambient, target status, etc.) per zone. The array must be terminated with `VL53L5CX_LAST_THRESHOLD` in the `zone_num` field of the last entry.

### Function Signatures
```c
uint8_t vl53l5cx_set_detection_thresholds(VL53L5CX_Configuration *Dev, VL53L5CX_DetectionThresholds *thresholds)
uint8_t vl53l5cx_set_detection_thresholds_enable(VL53L5CX_Configuration *Dev, uint8_t enable)
```

### Parameters
- **Dev** (*VL53L5CX_Configuration*): Pointer to the VL53L5CX configuration structure.
- **thresholds** (*VL53L5CX_DetectionThresholds*): Pointer to an array of `VL53L5CX_DetectionThresholds` structures defining the detection criteria.
- **enable** (*uint8_t*): A value of 1 to enable threshold-based interrupt filtering, 0 to disable.

### Return Value
- *uint8_t*: Status code indicating success or failure (e.g., VL53L5CX_STATUS_OK).

### Example
```c
#include "vl53l5cx_plugin_detection_thresholds.h"

VL53L5CX_DetectionThresholds thresholds[VL53L5CX_NB_THRESHOLDS] = {0};
uint8_t status;

/* Checker 0: trigger if zone 0 distance is below 300 mm */
thresholds[0].measurement          = VL53L5CX_DISTANCE_MM;
thresholds[0].type                 = VL53L5CX_LESS_THAN_EQUAL_MIN_CHECKER;
thresholds[0].param_low_thresh     = 300;
thresholds[0].param_high_thresh    = 300;
thresholds[0].zone_num             = 0;
thresholds[0].mathematic_operation = VL53L5CX_OPERATION_OR;

/* Checker 1: AND — zone 0 signal must also be > 2000 kcps/spad */
thresholds[1].measurement          = VL53L5CX_SIGNAL_PER_SPAD_KCPS;
thresholds[1].type                 = VL53L5CX_GREATER_THAN_MAX_CHECKER;
thresholds[1].param_low_thresh     = 2000;
thresholds[1].param_high_thresh    = 2000;
thresholds[1].zone_num             = 0 | VL53L5CX_LAST_THRESHOLD;  /* last entry */
thresholds[1].mathematic_operation = VL53L5CX_OPERATION_AND;

status = vl53l5cx_set_detection_thresholds(&Dev, thresholds);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Enable threshold-based interrupt filtering */
status = vl53l5cx_set_detection_thresholds_enable(&Dev, 1);

/* Verify */
uint8_t enabled = 0;
vl53l5cx_get_detection_thresholds_enable(&Dev, &enabled);
printf("Thresholds enabled: %u\n", enabled);
```
```

--------------------------------

### Read Device ID and Capabilities

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Reads the hardware device ID and queries the sensor's capabilities, including zone count, max targets, and feature availability.

```c
#include "vl53l5cx.h"
#include <stdio.h>

uint32_t device_id = 0;
VL53L5CX_Capabilities_t cap = {0};

int32_t ret = VL53L5CX_ReadID(&VL53L5CX_Obj, &device_id);
printf("Device ID: 0x%04lX\n", device_id);  /* Expected: 0xF002 */

ret = VL53L5CX_GetCapabilities(&VL53L5CX_Obj, &cap);
printf("Number of zones:          %lu\n", cap.NumberOfZones);           /* 64 */
printf("Max targets per zone:     %lu\n", cap.MaxNumberOfTargetsPerZone);
printf("Custom ROI available:     %lu\n", cap.CustomROI);               /* 1 */
printf("Threshold detection avail:%lu\n", cap.ThresholdDetection);      /* 1 */
```

--------------------------------

### BSP Layer: Device Identification

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Reads the hardware device ID and queries the sensor's capabilities, including zone count, maximum targets per zone, and support for custom ROI and threshold detection.

```APIDOC
## VL53L5CX_ReadID / VL53L5CX_GetCapabilities

### Description
Reads the hardware device ID and queries the sensor capabilities (zone count, max targets per zone, custom ROI support, and threshold detection availability).

### Read Device ID
```c
ret = VL53L5CX_ReadID(&VL53L5CX_Obj, &device_id);
printf("Device ID: 0x%04lX\n", device_id);  /* Expected: 0xF002 */
```

### Get Sensor Capabilities
```c
ret = VL53L5CX_GetCapabilities(&VL53L5CX_Obj, &cap);
printf("Number of zones:          %lu\n", cap.NumberOfZones);           /* 64 */
printf("Max targets per zone:     %lu\n", cap.MaxNumberOfTargetsPerZone);
printf("Custom ROI available:     %lu\n", cap.CustomROI);               /* 1 */
printf("Threshold detection avail:%lu\n", cap.ThresholdDetection);      /* 1 */
```
```

--------------------------------

### Set Integration Time (ms)

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Controls the sensor integration (exposure) time in autonomous ranging mode. Must be less than the ranging period (1000 / frequency_hz). Has no effect in continuous mode.

```c
#include "vl53l5cx_api.h"

uint8_t status;
uint32_t integration_ms;

/* Autonomous mode at 5 Hz → period = 200 ms. Set integration to 50 ms */
status = vl53l5cx_set_ranging_mode(&Dev, VL53L5CX_RANGING_MODE_AUTONOMOUS);
status = vl53l5cx_set_ranging_frequency_hz(&Dev, 5);
status = vl53l5cx_set_integration_time_ms(&Dev, 50);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

vl53l5cx_get_integration_time_ms(&Dev, &integration_ms);
printf("Integration time: %lu ms\n", integration_ms);
```

--------------------------------

### Configure Region of Interest — VL53L5CX_ConfigROI

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Restricts active measurement to a rectangular sub-region of the sensor's field of view, defined by top-left and bottom-right corner coordinates within the 8×8 zone grid (0–7 for each axis).

```c
#include "vl53l5cx.h"

/* Focus on a 4×4 region in the center of the 8×8 grid */
VL53L5CX_ROIConfig_t ROI = {
    .TopLeftX  = 2,
    .TopLeftY  = 2,
    .BotRightX = 5,
    .BotRightY = 5,
};

int32_t ret = VL53L5CX_ConfigROI(&VL53L5CX_Obj, &ROI);
if (ret != VL53L5CX_OK) { Error_Handler(); }
```

--------------------------------

### Configure Interrupt Thresholds — VL53L5CX_ConfigIT

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Programs interrupt generation criteria so the sensor raises an interrupt only when a measured distance satisfies the configured window condition, avoiding polling overhead.

```c
#include "vl53l5cx.h"

/* Trigger interrupt when any zone detects a target below 500 mm */
VL53L5CX_ITConfig_t ITConfig = {
    .Criteria      = VL53L5CX_IT_BELOW_LOW,  /* distance <= LowThreshold */
    .LowThreshold  = 500,   /* mm */
    .HighThreshold = 1000,  /* mm (not used for BELOW_LOW, but must be set) */
};

int32_t ret = VL53L5CX_ConfigIT(&VL53L5CX_Obj, &ITConfig);
if (ret != VL53L5CX_OK) { Error_Handler(); }
```

```c
/* Available criteria:
 * VL53L5CX_IT_DEFAULT      — interrupt on every new measurement
 * VL53L5CX_IT_IN_WINDOW    — distance > HighThreshold
 * VL53L5CX_IT_OUT_OF_WINDOW — distance < Low OR > High
 * VL53L5CX_IT_BELOW_LOW    — distance <= Low
 * VL53L5CX_IT_ABOVE_HIGH   — distance > High
 * VL53L5CX_IT_EQUAL_LOW    — distance == Low
 * VL53L5CX_IT_NOT_EQUAL_LOW — distance != Low
 */
```

--------------------------------

### Set Power Mode (Wakeup or Sleep)

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Switches the sensor between wakeup (normal operation) and sleep (low power) states. The firmware and configuration are retained in sleep mode. Ranging must be stopped before entering sleep.

```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t power_mode;

/* Enter low-power sleep */
status = vl53l5cx_stop_ranging(&Dev);
status = vl53l5cx_set_power_mode(&Dev, VL53L5CX_POWER_MODE_SLEEP);
if (status == VL53L5CX_STATUS_INVALID_PARAM) { Error_Handler(); }

/* ... wait ... */

/* Wake up and resume */
status = vl53l5cx_set_power_mode(&Dev, VL53L5CX_POWER_MODE_WAKEUP);
status = vl53l5cx_start_ranging(&Dev);

vl53l5cx_get_power_mode(&Dev, &power_mode);
/* power_mode == VL53L5CX_POWER_MODE_WAKEUP (1) */
```

--------------------------------

### BSP Layer: Address and Power Mode

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

BSP wrapper functions for changing the sensor I2C address and controlling the sensor's sleep/wakeup state.

```APIDOC
## VL53L5CX_SetAddress / VL53L5CX_SetPowerMode

### Description
BSP wrapper functions for changing the sensor I2C address and controlling sleep/wakeup state through the standardized `RANGING_SENSOR` interface.

### Change I2C address
```c
/* Change address from 0x52 to 0x54 for multi-sensor bus sharing */
ret = VL53L5CX_SetAddress(&VL53L5CX_Obj, 0x54);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* Get current address */
VL53L5CX_GetAddress(&VL53L5CX_Obj, &address);
printf("New address: 0x%02lX\n", address);  /* 0x54 */
```

### Control Power Mode
```c
/* Enter low-power sleep */
VL53L5CX_SetPowerMode(&VL53L5CX_Obj, VL53L5CX_POWER_MODE_SLEEP);

/* Get current power mode */
VL53L5CX_GetPowerMode(&VL53L5CX_Obj, &powerMode);
printf("Power mode: %lu\n", powerMode);  /* 0 = sleep */

/* Wake up */
VL53L5CX_SetPowerMode(&VL53L5CX_Obj, VL53L5CX_POWER_MODE_WAKEUP);
```
```

--------------------------------

### Set Target Order

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Controls how multiple targets per zone are sorted in the results: by closest distance or by strongest signal return.

```APIDOC
## Set Target Order — `vl53l5cx_set_target_order`

Controls how multiple targets per zone are sorted in the results: by closest distance or by strongest signal return.

### Example Usage:
```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t target_order;

/* Report closest target first */
status = vl53l5cx_set_target_order(&Dev, VL53L5CX_TARGET_ORDER_CLOSEST);
if (status == VL53L5CX_STATUS_INVALID_PARAM) {
    /* Unknown order value */
}

vl53l5cx_get_target_order(&Dev, &target_order);
/* target_order == VL53L5CX_TARGET_ORDER_CLOSEST (1) or
 *                 VL53L5CX_TARGET_ORDER_STRONGEST (2) */
```
```

--------------------------------

### Configure Interrupt Thresholds

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Programs interrupt generation criteria so the sensor raises an interrupt only when a measured distance satisfies the configured window condition, avoiding polling overhead.

```APIDOC
## Configure Interrupt Thresholds — `VL53L5CX_ConfigIT`

Programs interrupt generation criteria so the sensor raises an interrupt only when a measured distance satisfies the configured window condition, avoiding polling overhead.

```c
#include "vl53l5cx.h"

/* Trigger interrupt when any zone detects a target below 500 mm */
VL53L5CX_ITConfig_t ITConfig = {
    .Criteria      = VL53L5CX_IT_BELOW_LOW,  /* distance <= LowThreshold */
    .LowThreshold  = 500,   /* mm */
    .HighThreshold = 1000,  /* mm (not used for BELOW_LOW, but must be set) */
};

int32_t ret = VL53L5CX_ConfigIT(&VL53L5CX_Obj, &ITConfig);
if (ret != VL53L5CX_OK) { Error_Handler(); }

/* Available criteria:
 * VL53L5CX_IT_DEFAULT      — interrupt on every new measurement
 * VL53L5CX_IT_IN_WINDOW    — distance > HighThreshold
 * VL53L5CX_IT_OUT_OF_WINDOW — distance < Low OR > High
 * VL53L5CX_IT_BELOW_LOW    — distance <= Low
 * VL53L5CX_IT_ABOVE_HIGH   — distance > High
 * VL53L5CX_IT_EQUAL_LOW    — distance == Low
 * VL53L5CX_IT_NOT_EQUAL_LOW — distance != Low
 */
```
```

--------------------------------

### Read, Write, and Patch DCI Memory

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Provides low-level access to the sensor's Device Configuration Interface (DCI) memory for reading, writing, or patching arbitrary fields by index. Useful for tuning firmware parameters not exposed via higher-level APIs.

```c
#include "vl53l5cx_api.h"

uint8_t status;
uint8_t pipe_ctrl[4];

/* Read DCI_PIPE_CONTROL register */
status = vl53l5cx_dci_read_data(&Dev,
    pipe_ctrl,
    VL53L5CX_DCI_PIPE_CONTROL,   /* 0xDB80 */
    sizeof(pipe_ctrl));

printf("Pipe control: %02X %02X %02X %02X\n",
    pipe_ctrl[0], pipe_ctrl[1], pipe_ctrl[2], pipe_ctrl[3]);

/* Patch a single byte at offset 0 within the buffer */
uint8_t new_val = 0x01;
status = vl53l5cx_dci_replace_data(&Dev,
    pipe_ctrl,
    VL53L5CX_DCI_PIPE_CONTROL,
    sizeof(pipe_ctrl),
    &new_val,
    sizeof(new_val),
    0);   /* position within the buffer */
```

--------------------------------

### vl53l5cx_dci_read_data / vl53l5cx_dci_write_data / vl53l5cx_dci_replace_data

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Low-level functions to read, write, or patch arbitrary fields in the sensor's Device Configuration Interface (DCI) memory by index. These are used to tune firmware parameters not exposed through higher-level API calls.

```APIDOC
## vl53l5cx_dci_read_data / vl53l5cx_dci_write_data / vl53l5cx_dci_replace_data

### Description
Low-level functions to read, write, or patch arbitrary fields in the sensor's Device Configuration Interface (DCI) memory by index. Used to tune firmware parameters not exposed through higher-level API calls.

### Function Signatures
```c
uint8_t vl53l5cx_dci_read_data(VL53L5CX_Configuration *Dev, uint8_t *buffer, uint32_t index, uint32_t data_size)
uint8_t vl53l5cx_dci_write_data(VL53L5CX_Configuration *Dev, uint8_t *buffer, uint32_t index, uint32_t data_size)
uint8_t vl53l5cx_dci_replace_data(VL53L5CX_Configuration *Dev, uint8_t *buffer, uint32_t index, uint32_t buffer_size, uint8_t *replace_buffer, uint32_t replace_size, uint32_t position)
```

### Parameters
- **Dev** (*VL53L5CX_Configuration*): Pointer to the VL53L5CX configuration structure.
- **buffer** (*uint8_t*): Buffer to store read data or to write data from.
- **index** (*uint32_t*): The DCI memory index to read from or write to.
- **data_size** (*uint32_t*): The number of bytes to read or write.
- **buffer_size** (*uint32_t*): The size of the buffer for `vl53l5cx_dci_replace_data`.
- **replace_buffer** (*uint8_t*): Buffer containing the data to replace.
- **replace_size** (*uint32_t*): The number of bytes to replace.
- **position** (*uint32_t*): The position within the buffer to start the replacement.

### Return Value
- *uint8_t*: Status code indicating success or failure (e.g., VL53L5CX_STATUS_OK).

### Example
```c
uint8_t status;
uint8_t pipe_ctrl[4];

/* Read DCI_PIPE_CONTROL register */
status = vl53l5cx_dci_read_data(&Dev,
    pipe_ctrl,
    VL53L5CX_DCI_PIPE_CONTROL,   /* 0xDB80 */
    sizeof(pipe_ctrl));

printf("Pipe control: %02X %02X %02X %02X\n",
    pipe_ctrl[0], pipe_ctrl[1], pipe_ctrl[2], pipe_ctrl[3]);

/* Patch a single byte at offset 0 within the buffer */
uint8_t new_val = 0x01;
status = vl53l5cx_dci_replace_data(&Dev,
    pipe_ctrl,
    VL53L5CX_DCI_PIPE_CONTROL,
    sizeof(pipe_ctrl),
    &new_val,
    sizeof(new_val),
    0);   /* position within the buffer */
```
```

--------------------------------

### vl53l5cx_disable_internal_cp / vl53l5cx_enable_internal_cp

Source: https://context7.com/stmicroelectronics/stm32-vl53l5cx/llms.txt

Disables or re-enables the VCSEL internal charge pump to reduce power consumption. This is only applicable when AVDD is supplied at 3.3 V.

```APIDOC
## vl53l5cx_disable_internal_cp / vl53l5cx_enable_internal_cp

### Description
Disables or re-enables the VCSEL internal charge pump to reduce power consumption. Only applicable when AVDD is supplied at 3.3 V.

### Function Signatures
```c
uint8_t vl53l5cx_disable_internal_cp(VL53L5CX_Configuration *Dev)
uint8_t vl53l5cx_enable_internal_cp(VL53L5CX_Configuration *Dev)
```

### Parameters
- **Dev** (*VL53L5CX_Configuration*): Pointer to the VL53L5CX configuration structure.

### Return Value
- *uint8_t*: Status code indicating success or failure (e.g., VL53L5CX_STATUS_OK).

### Example
```c
/* Disable charge pump (AVDD = 3.3V) to reduce power */
uint8_t status = vl53l5cx_disable_internal_cp(&Dev);
if (status != VL53L5CX_STATUS_OK) { Error_Handler(); }

/* Re-enable if needed */
status = vl53l5cx_enable_internal_cp(&Dev);
```
```