unit_VL53L1X.hpp

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2024 M5Stack Technology CO LTD
 *
 * SPDX-License-Identifier: MIT
 */
#ifndef M5_UNIT_TOF_UNIT_VL53L1X_HPP
#define M5_UNIT_TOF_UNIT_VL53L1X_HPP
 
#include <M5UnitComponent.hpp>
#include <m5_utility/container/circular_buffer.hpp>
#include <m5_utility/types.hpp>
#include <array>
#include <limits>  // NaN
 
namespace m5 {
namespace unit {
 
namespace vl53l1x {
 
enum class Operating : uint8_t {
    ConditionStandard,  
    Condition2V8        
};
 
enum class Distance : int8_t {
    Unknown = -1,
    Short,  
    Long,   
};
 
enum class Timing : int8_t {
    BudgetUnknown = -1,
    Budget15ms,   
    Budget20ms,   
    Budget33ms,   
    Budget50ms,   
    Budget100ms,  
    Budget200ms,  
    Budget500ms,  
};
 
enum class RangeStatus : uint8_t {
    OK,
    SigmaFailure,
    SignalFailure,
    RangeValidMinRangeClipped,
    OutOfBounds,
    HardwareFailure,
    Unknown6,
    Wraparound,
    Unknown8,
    XtalkSignalFailure,
    SynchronizationInt,
    Unknown11,
    Unknown12,
    MinRangeFailure,
    Unknown255 = 255,
};
 
enum class Window : uint8_t {
    Below,           
    Beyond,          
    Out,             
    In,              
    Regular = 0x20,  
};
 
struct Data {
    std::array<uint8_t, 17> raw{};  
    RangeStatus range_status() const;
    inline bool valid() const
    {
        return raw[0] == 9;
    }
    inline int16_t range() const
    {
        return valid() ? m5::types::big_uint16_t(raw[13], raw[14]).get() : -1;
    }
};
 
}  // namespace vl53l1x
 
class UnitVL53L1X : public Component, public PeriodicMeasurementAdapter<UnitVL53L1X, vl53l1x::Data> {
    M5_UNIT_COMPONENT_HPP_BUILDER(UnitVL53L1X, 0x29);
 
public:
    struct config_t {
        vl53l1x::Operating operating{vl53l1x::Operating::Condition2V8};
        vl53l1x::Distance distance{vl53l1x::Distance::Long};
        vl53l1x::Timing timing_budget{vl53l1x::Timing::Budget100ms};
        bool start_periodic{true};
        bool calibrate_offset{false};
        bool calibrate_xtalk{false};
    };
 
    explicit UnitVL53L1X(const uint8_t addr = DEFAULT_ADDRESS)
        : Component(addr), _data{new m5::container::CircularBuffer<vl53l1x::Data>(1)}
    {
        auto ccfg  = component_config();
        ccfg.clock = 400 * 1000U;
        component_config(ccfg);
    }
    virtual ~UnitVL53L1X()
    {
    }
 
    virtual bool begin() override;
    virtual void update(const bool force = false) override;
 
 
    inline config_t config() const
    {
        return _cfg;
    }
    inline void config(const config_t& cfg)
    {
        _cfg = cfg;
    }
 
 
    inline int16_t range() const
    {
        return !empty() ? oldest().range() : -1;
    }
    inline bool valid() const
    {
        return !empty() && oldest().valid();
    }
    inline vl53l1x::RangeStatus range_status() const
    {
        return !empty() ? oldest().range_status() : vl53l1x::RangeStatus::Unknown255;
    }
 
 
    inline vl53l1x::Distance distanceMode() const
    {
        return _distance;
    }
    inline vl53l1x::Timing timingBudget() const
    {
        return _tb;
    }
 
 
    inline bool startPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitVL53L1X, vl53l1x::Data>::startPeriodicMeasurement();
    }
    inline bool startPeriodicMeasurement(const vl53l1x::Distance dist,
                                         const vl53l1x::Timing tb = vl53l1x::Timing::Budget50ms)
    {
        return PeriodicMeasurementAdapter<UnitVL53L1X, vl53l1x::Data>::startPeriodicMeasurement(dist, tb);
    }
    inline bool stopPeriodicMeasurement()
    {
        return PeriodicMeasurementAdapter<UnitVL53L1X, vl53l1x::Data>::stopPeriodicMeasurement();
    }
 
 
    bool measureSingleshot(vl53l1x::Data& d);
 
    bool readDistanceMode(vl53l1x::Distance& d);
    bool writeDistanceMode(const vl53l1x::Distance d);
 
    bool softReset();
 
 
    bool calibrateOffset(int16_t& offset, const uint16_t targetmm = 100);
    bool readOffset(int16_t& offset);
    bool writeOffset(const int16_t offset);
 
 
    bool calibrateXtalk(uint16_t& xtalk, const uint16_t targetmm = 100);
    bool readXtalk(uint16_t& xtalk);
    bool writeXtalk(const uint16_t xtalk);
 
 
    bool readTimingBudget(vl53l1x::Timing& tb);
    inline bool writeTimingBudget(const vl53l1x::Timing tb)
    {
        return write_timing_budget(tb, distanceMode());
    }
    bool readInterMeasurementPeriod(uint16_t& ms);
    bool writeInterMeasurementPeriod(const uint16_t ms);
 
 
    bool readDistanceThresholdWindow(vl53l1x::Window& window);
    bool readDistanceThresholdLow(uint16_t& mm);
    bool readDistanceThresholdHigh(uint16_t& mm);
    bool writeDistanceThreshold(const vl53l1x::Window window, const uint16_t low, const uint16_t high);
    inline bool clearDistanceThreshold()
    {
        return writeDistanceThreshold(vl53l1x::Window::Regular, 0, 0);
    }
 
 
    bool readROI(uint8_t& wid, uint8_t& hgt);
    bool readROICenter(uint8_t& center);
    bool writeROI(const uint8_t wid, const uint8_t hgt);
    bool writeROICenter(const uint8_t center);
 
 
    bool readI2CAddress(uint8_t& i2c_address);
    bool changeI2CAddress(const uint8_t i2c_address);
 
protected:
    bool start_periodic_measurement();
    bool start_periodic_measurement(const vl53l1x::Distance dist, const vl53l1x::Timing tb);
    bool stop_periodic_measurement();
 
    bool write_operating_condition(const vl53l1x::Operating oc);
    bool write_timing_budget(const vl53l1x::Timing tb, const vl53l1x::Distance distance);
 
    bool read_data_ready_status();
    bool read_measurement(vl53l1x::Data& d);
 
    bool soft_reset();
    bool write_default_values();
    bool wait_booted();
 
    M5_UNIT_COMPONENT_PERIODIC_MEASUREMENT_ADAPTER_HPP_BUILDER(UnitVL53L1X, vl53l1x::Data);
 
protected:
    vl53l1x::Distance _distance{vl53l1x::Distance::Unknown};
    vl53l1x::Timing _tb{vl53l1x::Timing::BudgetUnknown};
 
    std::unique_ptr<m5::container::CircularBuffer<vl53l1x::Data>> _data{};
    config_t _cfg{};
};
 
namespace vl53l1x {
namespace command {
// clang-format off
constexpr uint16_t SOFT_RESET                                                   {0x0000};
constexpr uint16_t I2C_SLAVE_DEVICE_ADDRESS                                     {0x0001};
constexpr uint16_t OSC_MEASURED_FAST_OSC_FREQUENCY                              {0x0006};
constexpr uint16_t VHV_CONFIG_TIMEOUT_MACROP_LOOP_BOUND                         {0x0008};
constexpr uint16_t VHV_CONFIG_INIT                                              {0x000B};
constexpr uint16_t ALGO_CROSSTALK_COMPENSATION_PLANE_OFFSET_KCPS                {0x0016};// [15:0] fixed point 7.9)
constexpr uint16_t ALGO_CROSSTALK_COMPENSATION_X_PLANE_GRADIENT_KCPS            {0x0018};
constexpr uint16_t ALGO_CROSSTALK_COMPENSATION_Y_PLANE_GRADIENT_KCPS            {0x001A};
constexpr uint16_t ALGO_PART_TO_PART_RANGE_OFFSET_MM                            {0x001E};// [12:0] fixed point 11.2
constexpr uint16_t MM_CONFIG_INNER_OFFSET_MM                                    {0x0020};
constexpr uint16_t MM_CONFIG_OUTER_OFFSET_MM                                    {0x0022};
constexpr uint16_t DSS_CONFIG_TARGET_TOTAL_RATE_MCPS                            {0x0024};
constexpr uint16_t EXTSUP_CONFIG                                                {0x002E};
constexpr uint16_t GPIO_HV_MUX_CTRL                                             {0x0030};
constexpr uint16_t GPIO_TIO_HV_STATUS                                           {0x0031};
constexpr uint16_t SIGMA_ESTIMATOR_EFFECTIVE_PULSE_WIDTH_NS                     {0x0036};
constexpr uint16_t SIGMA_ESTIMATOR_EFFECTIVE_AMBIENT_WIDTH_NS                   {0x0037};
constexpr uint16_t ALGO_CROSSTALK_COMPENSATION_VALID_HEIGHT_MM                  {0x0039};
constexpr uint16_t ALGO_RANGE_IGNORE_VALID_HEIGHT_MM                            {0x003E};
constexpr uint16_t ALGO_RANGE_MIN_CLIP                                          {0x003F};
constexpr uint16_t ALGO_CONSISTENCY_CHECK_TOLERANCE                             {0x0040};
constexpr uint16_t SYSTEM_INTERRUPT_CONFIG_GPIO                                 {0x0046};
constexpr uint16_t CAL_CONFIG_VCSEL_START                                       {0x0047};
constexpr uint16_t PHASECAL_CONFIG_TIMEOUT_MACROP                               {0x004B};
constexpr uint16_t PHASECAL_CONFIG_OVERRIDE                                     {0x004D};
constexpr uint16_t DSS_CONFIG_ROI_MODE_CONTROL                                  {0x004F};
constexpr uint16_t SYSTEM_THRESH_RATE_HIGH                                      {0x0050};
constexpr uint16_t SYSTEM_THRESH_RATE_LOW                                       {0x0052};
constexpr uint16_t DSS_CONFIG_MANUAL_EFFECTIVE_SPADS_SELECT                     {0x0054};
constexpr uint16_t DSS_CONFIG_APERTURE_ATTENUATION                              {0x0057};
constexpr uint16_t MM_CONFIG_TIMEOUT_MACROP_A                                   {0x005A};
constexpr uint16_t MM_CONFIG_TIMEOUT_MACROP_B                                   {0x005C};
constexpr uint16_t RANGE_CONFIG_TIMEOUT_MACROP_A                                {0x005E};
constexpr uint16_t RANGE_CONFIG_TIMEOUT_MACROP_A_HI                             {0x005E};
constexpr uint16_t RANGE_CONFIG_VCSEL_PERIOD_A                                  {0x0060};
constexpr uint16_t RANGE_CONFIG_TIMEOUT_MACROP_B                                {0x0061};
constexpr uint16_t RANGE_CONFIG_TIMEOUT_MACROP_B_HI                             {0x0061};
constexpr uint16_t RANGE_CONFIG_VCSEL_PERIOD_B                                  {0x0063};
constexpr uint16_t RANGE_CONFIG_SIGMA_THRESH                                    {0x0064};
constexpr uint16_t RANGE_CONFIG_MIN_COUNT_RATE_RTN_LIMIT_MCPS                   {0x0066};
constexpr uint16_t RANGE_CONFIG_VALID_PHASE_HIGH                                {0x0069};
constexpr uint16_t SYSTEM_INTERMEASUREMENT_PERIOD                               {0x006C};
constexpr uint16_t SYSTEM_GROUPED_PARAMETER_HOLD_0                              {0x0071};
constexpr uint16_t SYSTEM_THRESH_HIGH                                           {0x0072};
constexpr uint16_t SYSTEM_THRESH_LOW                                            {0x0074};
constexpr uint16_t SYSTEM_SEED_CONFIG                                           {0x0077};
constexpr uint16_t SD_CONFIG_WOI_SD0                                            {0x0078};
constexpr uint16_t SD_CONFIG_WOI_SD1                                            {0x0079};
constexpr uint16_t SD_CONFIG_INITIAL_PHASE_SD0                                  {0x007A};
constexpr uint16_t SD_CONFIG_INITIAL_PHASE_SD1                                  {0x007B};
constexpr uint16_t SYSTEM_GROUPED_PARAMETER_HOLD_1                              {0x007C};
constexpr uint16_t SD_CONFIG_QUANTIFIER                                         {0x007E};
constexpr uint16_t ROI_CONFIG_USER_ROI_CENTRE_SPAD                              {0x007F};
constexpr uint16_t ROI_CONFIG_USER_ROI_REQUESTED_GLOBAL_XY_SIZE                 {0x0080};
constexpr uint16_t SYSTEM_SEQUENCE_CONFIG                                       {0x0081};
constexpr uint16_t SYSTEM_GROUPED_PARAMETER_HOLD                                {0x0082};
constexpr uint16_t SYSTEM_INTERRUPT_CLEAR                                       {0x0086};
constexpr uint16_t SYSTEM_MODE_START                                            {0x0087};
constexpr uint16_t RESULT_RANGE_STATUS                                          {0x0089}; // result size is 17bytes
constexpr uint16_t RESULT_DSS_ACTUAL_EFFECTIVE_SPADS_SD0                        {0x008C};
constexpr uint16_t RESULT_FINAL_CROSSTALK_CORRECTED_RANGE_MM_SD0                {0x0096};
constexpr uint16_t RESULT_PEAK_SIGNAL_COUNT_RATE_CROSSTALK_CORRECTED_MCPS_SD0   {0x0098};
constexpr uint16_t PHASECAL_RESULT_VCSEL_START                                  {0x00D8};
constexpr uint16_t RESULT_OSC_CALIBRATE_VAL                                     {0x00DE};
constexpr uint16_t FIRMWARE_SYSTEM_STATUS                                       {0x00E5};
//
constexpr uint16_t MODEL_ID                                                     {0x010F};
constexpr uint16_t MODULE_TYPE                                                  {0x0110};
constexpr uint16_t MASK_REVISION                                                {0x0111};
// clang-format on
}  // namespace command
}  // namespace vl53l1x
 
}  // namespace unit
}  // namespace m5
#endif