/**
* @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 -
*
* https://mengze.top/MZ-ATY_VCJS
* - CC 4.0 BY-NC-SA -
*
* https://creativecommons.org/licenses/by-nc-sa/4.0/
* - 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 *********************************/