ATY_LIB/Doing/VL6180_ATY.h

/**
* @file VL6180_ATY.h
*
* @param Project DEVICE_GENERAL_ATY_LIB
*
* @author ATY
*
* @copyright
*       - Copyright 2017 - 2026 MZ-ATY
*       - This code follows:
*           - MZ-ATY Various Contents Joint Statement -
*               <a href="https://mengze.top/MZ-ATY_VCJS">
*                        https://mengze.top/MZ-ATY_VCJS</a>
*           - CC 4.0 BY-NC-SA -
*               <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/">
*                        https://creativecommons.org/licenses/by-nc-sa/4.0/</a>
*       - Your use will be deemed to have accepted the terms of this statement.
*
* @brief functions of VL6180 proximity and ambient light sensor for all embedded device
*
* @version
*       - 1_00_250101 > ATY
*           -# Initial version, support I2C communication, range and ALS measurement
********************************************************************************
*/

#ifndef __VL6180_ATY_H
#define __VL6180_ATY_H

#include "INCLUDE_ATY.h"

/******************************* For user *************************************/

// VL6180 I2C Default Address
#define VL6180_I2C_ADDR_DEFAULT     0x29

// VL6180 Status Codes
#define VL6180_STATUS_OK            0x00
#define VL6180_STATUS_ERROR         0x01
#define VL6180_STATUS_TIMEOUT       0x02
#define VL6180_STATUS_NO_DEVICE     0x03
#define VL6180_STATUS_NOT_READY     0x04
#define VL6180_STATUS_RANGE_ERROR   0x05
#define VL6180_STATUS_ALS_ERROR     0x06

// VL6180 Register Addresses
#define VL6180_REG_IDENTIFICATION_MODEL_ID              0x000
#define VL6180_REG_IDENTIFICATION_MODEL_REV_MAJOR       0x001
#define VL6180_REG_IDENTIFICATION_MODEL_REV_MINOR       0x002
#define VL6180_REG_IDENTIFICATION_MODULE_REV_MAJOR      0x003
#define VL6180_REG_IDENTIFICATION_MODULE_REV_MINOR      0x004
#define VL6180_REG_IDENTIFICATION_DATE_HI               0x006
#define VL6180_REG_IDENTIFICATION_DATE_LO               0x007
#define VL6180_REG_IDENTIFICATION_TIME                  0x008

#define VL6180_REG_SYSTEM_MODE_GPIO0                    0x010
#define VL6180_REG_SYSTEM_MODE_GPIO1                    0x011
#define VL6180_REG_SYSTEM_HISTORY_CTRL                  0x012
#define VL6180_REG_SYSTEM_INTERRUPT_CONFIG_GPIO         0x014
#define VL6180_REG_SYSTEM_INTERRUPT_CLEAR               0x015
#define VL6180_REG_SYSTEM_FRESH_OUT_OF_RESET            0x016
#define VL6180_REG_SYSTEM_GROUPED_PARAMETER_HOLD        0x017

// Range measurement registers
#define VL6180_REG_SYSRANGE_START                       0x018
#define VL6180_REG_SYSRANGE_THRESH_HIGH                 0x019
#define VL6180_REG_SYSRANGE_THRESH_LOW                  0x01A
#define VL6180_REG_SYSRANGE_INTERMEASUREMENT_PERIOD     0x01B
#define VL6180_REG_SYSRANGE_MAX_CONVERGENCE_TIME        0x01C
#define VL6180_REG_SYSRANGE_CROSSTALK_COMPENSATION_RATE 0x01E
#define VL6180_REG_SYSRANGE_CROSSTALK_VALID_HEIGHT      0x021
#define VL6180_REG_SYSRANGE_EARLY_CONVERGENCE_ESTIMATE  0x022
#define VL6180_REG_SYSRANGE_PART_TO_PART_RANGE_OFFSET   0x024
#define VL6180_REG_SYSRANGE_RANGE_IGNORE_VALID_HEIGHT   0x025
#define VL6180_REG_SYSRANGE_RANGE_IGNORE_THRESHOLD      0x026
#define VL6180_REG_SYSRANGE_MAX_AMBIENT_LEVEL_MULT      0x02C
#define VL6180_REG_SYSRANGE_RANGE_CHECK_ENABLES         0x02D
#define VL6180_REG_SYSRANGE_VHV_RECALIBRATE             0x02E
#define VL6180_REG_SYSRANGE_VHV_REPEAT_RATE             0x031

// ALS measurement registers
#define VL6180_REG_SYSALS_START                         0x038
#define VL6180_REG_SYSALS_THRESH_HIGH                   0x03A
#define VL6180_REG_SYSALS_THRESH_LOW                    0x03C
#define VL6180_REG_SYSALS_INTERMEASUREMENT_PERIOD       0x03E
#define VL6180_REG_SYSALS_ANALOGUE_GAIN                 0x03F
#define VL6180_REG_SYSALS_INTEGRATION_PERIOD            0x040

// Result registers
#define VL6180_REG_RESULT_RANGE_STATUS                  0x04D
#define VL6180_REG_RESULT_ALS_STATUS                    0x04E
#define VL6180_REG_RESULT_INTERRUPT_STATUS_GPIO         0x04F
#define VL6180_REG_RESULT_ALS_VAL                       0x050
#define VL6180_REG_RESULT_HISTORY_BUFFER_0              0x052
#define VL6180_REG_RESULT_HISTORY_BUFFER_1              0x054
#define VL6180_REG_RESULT_HISTORY_BUFFER_2              0x056
#define VL6180_REG_RESULT_HISTORY_BUFFER_3              0x058
#define VL6180_REG_RESULT_HISTORY_BUFFER_4              0x05A
#define VL6180_REG_RESULT_HISTORY_BUFFER_5              0x05C
#define VL6180_REG_RESULT_HISTORY_BUFFER_6              0x05E
#define VL6180_REG_RESULT_HISTORY_BUFFER_7              0x060
#define VL6180_REG_RESULT_RANGE_VAL                     0x062
#define VL6180_REG_RESULT_RANGE_RAW                     0x064
#define VL6180_REG_RESULT_RANGE_RETURN_RATE             0x066
#define VL6180_REG_RESULT_RANGE_REFERENCE_RATE          0x068
#define VL6180_REG_RESULT_RANGE_RETURN_SIGNAL_COUNT     0x06C
#define VL6180_REG_RESULT_RANGE_REFERENCE_SIGNAL_COUNT  0x070
#define VL6180_REG_RESULT_RANGE_RETURN_AMB_COUNT        0x074
#define VL6180_REG_RESULT_RANGE_REFERENCE_AMB_COUNT     0x078
#define VL6180_REG_RESULT_RANGE_RETURN_CONV_TIME        0x07C
#define VL6180_REG_RESULT_RANGE_REFERENCE_CONV_TIME     0x080

// Readout averaging sample period
#define VL6180_REG_READOUT_AVERAGING_SAMPLE_PERIOD      0x10A

// Firmware result scaler
#define VL6180_REG_FIRMWARE_BOOTUP                      0x119
#define VL6180_REG_FIRMWARE_RESULT_SCALER               0x120

// I2C Slave Device Address
#define VL6180_REG_I2C_SLAVE_DEVICE_ADDRESS             0x212

// Interleaved mode
#define VL6180_REG_INTERLEAVED_MODE_ENABLE              0x2A3

// VL6180 Commands
#define VL6180_MODE_RANGE_SINGLE_SHOT                   0x01
#define VL6180_MODE_RANGE_CONTINUOUS                    0x02
#define VL6180_MODE_ALS_SINGLE_SHOT                     0x01
#define VL6180_MODE_ALS_CONTINUOUS                      0x02

// VL6180 ALS Gain Settings
#define VL6180_ALS_GAIN_20                              0x00    // Actual ALS Gain of 20
#define VL6180_ALS_GAIN_10                              0x01    // Actual ALS Gain of 10.32
#define VL6180_ALS_GAIN_5                               0x02    // Actual ALS Gain of 5.21
#define VL6180_ALS_GAIN_2_5                             0x03    // Actual ALS Gain of 2.60
#define VL6180_ALS_GAIN_1_67                            0x04    // Actual ALS Gain of 1.72
#define VL6180_ALS_GAIN_1_25                            0x05    // Actual ALS Gain of 1.28
#define VL6180_ALS_GAIN_1                               0x06    // Actual ALS Gain of 1.01
#define VL6180_ALS_GAIN_40                              0x07    // Actual ALS Gain of 40

// VL6180 Error Codes
#define VL6180_ERROR_NONE                               0x00
#define VL6180_ERROR_SYSERR_1                           0x01
#define VL6180_ERROR_SYSERR_5                           0x05
#define VL6180_ERROR_ECEFAIL                            0x06
#define VL6180_ERROR_NOCONVERGE                         0x07
#define VL6180_ERROR_RANGEIGNORE                        0x08
#define VL6180_ERROR_SNR                                0x0B
#define VL6180_ERROR_RAWUFLOW                           0x0C
#define VL6180_ERROR_RAWOFLOW                           0x0D
#define VL6180_ERROR_RANGEUFLOW                         0x0E
#define VL6180_ERROR_RANGEOFLOW                         0x0F

/******************************************************************************/

struct VL6180_ATY_Dev
{
    // I2C communication functions
    uint8_t (*i2cStart)(void);              // I2C start condition
    uint8_t (*i2cStop)(void);               // I2C stop condition
    uint8_t (*i2cWriteByte)(uint8_t data);  // I2C write byte
    uint8_t (*i2cReadByte)(uint8_t ack);    // I2C read byte
    uint8_t i2cAddress;                     // I2C device address
    
    // Delay function
    void (*delayMs)(uint32_t ms);           // Millisecond delay function
    
    // Device identification
    uint8_t modelId;                        // Model ID
    uint8_t modelRevMajor;                  // Model revision major
    uint8_t modelRevMinor;                  // Model revision minor
    uint8_t moduleRevMajor;                 // Module revision major
    uint8_t moduleRevMinor;                 // Module revision minor
    
    // Range measurement data
    uint8_t rangeValue;                     // Range measurement result (mm)
    uint8_t rangeStatus;                    // Range measurement status
    uint16_t rangeRate;                     // Range return rate
    uint16_t rangeRaw;                      // Raw range measurement
    uint32_t rangeSignalCount;              // Range signal count
    uint32_t rangeAmbientCount;             // Range ambient count
    uint16_t rangeConvergenceTime;          // Range convergence time
    
    // ALS measurement data
    uint16_t alsValue;                      // ALS measurement result (lux)
    uint8_t alsStatus;                      // ALS measurement status
    uint8_t alsGain;                        // ALS gain setting
    uint16_t alsIntegrationPeriod;          // ALS integration period
    
    // Configuration parameters
    uint8_t rangeMaxConvergenceTime;        // Range max convergence time
    uint16_t rangeIntermeasurementPeriod;   // Range intermeasurement period
    uint16_t alsIntermeasurementPeriod;     // ALS intermeasurement period
    uint8_t rangeThresholdHigh;             // Range high threshold
    uint8_t rangeThresholdLow;              // Range low threshold
    uint16_t alsThresholdHigh;              // ALS high threshold
    uint16_t alsThresholdLow;               // ALS low threshold
    
    // Calibration data
    int8_t rangeOffset;                     // Range offset calibration
    uint16_t crosstalkCompensationRate;     // Crosstalk compensation rate
    
    // Status and control
    uint8_t devicePresent;                  // Device presence flag
    uint8_t lastStatus;                     // Last operation status
    uint8_t initialized;                    // Initialization flag
    uint8_t freshOutOfReset;                // Fresh out of reset flag
    
    // Debug and logging
    uint8_t lock;
    uint8_t debugEnable;
    void (*LOG)(const char*, ...);
};

// Function prototypes
uint8_t VL6180_Init(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_Reset(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_ReadDeviceID(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_LoadDefaultSettings(struct VL6180_ATY_Dev *dev);

// Range measurement functions
uint8_t VL6180_StartRangeMeasurement(struct VL6180_ATY_Dev *dev, uint8_t mode);
uint8_t VL6180_ReadRangeResult(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_GetRangeValue(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_IsRangeReady(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_ClearRangeInterrupt(struct VL6180_ATY_Dev *dev);

// ALS measurement functions
uint8_t VL6180_StartALSMeasurement(struct VL6180_ATY_Dev *dev, uint8_t mode);
uint8_t VL6180_ReadALSResult(struct VL6180_ATY_Dev *dev);
uint16_t VL6180_GetALSValue(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_IsALSReady(struct VL6180_ATY_Dev *dev);
uint8_t VL6180_ClearALSInterrupt(struct VL6180_ATY_Dev *dev);

// Configuration functions
uint8_t VL6180_SetRangeThresholds(struct VL6180_ATY_Dev *dev, uint8_t low, uint8_t high);
uint8_t VL6180_SetALSThresholds(struct VL6180_ATY_Dev *dev, uint16_t low, uint16_t high);
uint8_t VL6180_SetALSGain(struct VL6180_ATY_Dev *dev, uint8_t gain);
uint8_t VL6180_SetALSIntegrationPeriod(struct VL6180_ATY_Dev *dev, uint16_t period);
uint8_t VL6180_SetRangeOffset(struct VL6180_ATY_Dev *dev, int8_t offset);
uint8_t VL6180_SetCrosstalkCompensation(struct VL6180_ATY_Dev *dev, uint16_t rate);

// I2C register access functions
uint8_t VL6180_WriteRegister8(struct VL6180_ATY_Dev *dev, uint16_t reg, uint8_t data);
uint8_t VL6180_WriteRegister16(struct VL6180_ATY_Dev *dev, uint16_t reg, uint16_t data);
uint8_t VL6180_WriteRegister32(struct VL6180_ATY_Dev *dev, uint16_t reg, uint32_t data);
uint8_t VL6180_ReadRegister8(struct VL6180_ATY_Dev *dev, uint16_t reg, uint8_t *data);
uint8_t VL6180_ReadRegister16(struct VL6180_ATY_Dev *dev, uint16_t reg, uint16_t *data);
uint8_t VL6180_ReadRegister32(struct VL6180_ATY_Dev *dev, uint16_t reg, uint32_t *data);

// Utility functions
uint8_t VL6180_GetDeviceStatus(struct VL6180_ATY_Dev *dev);
void VL6180_SetI2CAddress(struct VL6180_ATY_Dev *dev, uint8_t address);
float VL6180_ConvertALSToLux(struct VL6180_ATY_Dev *dev, uint16_t alsValue);
const char* VL6180_GetErrorString(uint8_t errorCode);

#endif /* __VL6180_ATY_H */

/******************************** End Of File *********************************/