vl53l0x_types.h

Go to the documentation of this file.

//   Copyright 2016-2023 Jean-Francois Poilpret
//
//   Licensed under the Apache License, Version 2.0 (the "License");
//   you may not use this file except in compliance with the License.
//   You may obtain a copy of the License at
//
//       http://www.apache.org/licenses/LICENSE-2.0
//
//   Unless required by applicable law or agreed to in writing, software
//   distributed under the License is distributed on an "AS IS" BASIS,
//   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//   See the License for the specific language governing permissions and
//   limitations under the License.
 
 
#ifndef VL53L0X_TYPES_H
#define VL53L0X_TYPES_H
 
#include "../bits.h"
#include "../flash.h"
#include "../ios.h"
#include "../utilities.h"
#include "vl53l0x_registers.h"
 
namespace devices::vl53l0x
{
    class FixPoint9_7
    {
    public:
        static constexpr bool is_valid(float value)
        {
            return ((value >= 0.0) && (value < float(1 << INTEGRAL_BITS)));
        }
 
        static constexpr uint16_t convert(float value)
        {
            return is_valid(value) ? uint16_t(value * (1 << DECIMAL_BITS)) : 0U;
        }
 
        static constexpr float convert(uint16_t value)
        {
            return value / float(1 << DECIMAL_BITS);
        }
 
    private:
        static constexpr uint16_t INTEGRAL_BITS = 9;
        static constexpr uint16_t DECIMAL_BITS = 7;
    };
 
    class TimeoutUtilities
    {
    private:
        static constexpr uint32_t PLL_PERIOD_PS = 1655UL;
        static constexpr uint32_t MACRO_PERIOD_VCLKS = 2304UL;
 
    public:
        // timeout in macro periods must be encoded on 16 bits, as (LSB.2^MSB)+1
        static constexpr uint16_t encode_timeout(uint32_t timeout_macro_clks)
        {
            constexpr uint32_t MSB24_MASK = 0xFF'FF'FF'00UL;
            constexpr uint32_t LSB8_MASK = 0xFFUL;
            
            if (timeout_macro_clks == 0UL) return 0U;
            uint32_t lsb = timeout_macro_clks - 1UL;
            uint16_t msb = 0;
            while (lsb & MSB24_MASK)
            {
                lsb >>= 1;
                ++msb;
            }
            return utils::as_uint16_t(uint8_t(msb), uint8_t(lsb & LSB8_MASK));
        }
 
        // timeout in macro periods is encoded on 16 bits, as (LSB.2^MSB)+1
        static constexpr uint32_t decode_timeout(uint16_t encoded_timeout)
        {
            const uint32_t lsb = utils::low_byte(encoded_timeout);
            const uint32_t msb = utils::high_byte(encoded_timeout);
            return (lsb << msb) + 1UL;
        }
 
        static constexpr uint32_t calculate_macro_period_ps(uint8_t vcsel_period_pclks)
        {
            constexpr uint32_t PS_TO_NS_DIVIDER = 1000UL;
            constexpr uint32_t PS_TO_NS_ROUNDING_ADDITION = 500UL;
            return ((PLL_PERIOD_PS * MACRO_PERIOD_VCLKS * vcsel_period_pclks) + PS_TO_NS_ROUNDING_ADDITION)
                / PS_TO_NS_DIVIDER;
        }
        static constexpr uint32_t calculate_timeout_us(uint16_t timeout_period_mclks, uint8_t vcsel_period_pclks)
        {
            constexpr uint32_t NS_TO_US_DIVIDER = 1000UL;
            constexpr uint32_t NS_TO_US_ROUNDING_ADDITION = 500UL;
            const uint32_t macro_period_ns = calculate_macro_period_ps(vcsel_period_pclks);
            return ((timeout_period_mclks * macro_period_ns) + NS_TO_US_ROUNDING_ADDITION) / NS_TO_US_DIVIDER;
        }
        static constexpr uint32_t calculate_timeout_mclks(uint16_t timeout_period_us, uint8_t vcsel_period_pclks)
        {
            constexpr uint32_t US_TO_NS_MULTIPLIER = 1000UL;
            const uint32_t macro_period_ns = calculate_macro_period_ps(vcsel_period_pclks);
            return ((timeout_period_us * US_TO_NS_MULTIPLIER) + (macro_period_ns / 2)) / macro_period_ns;
        }
    };
 
    enum class DeviceError : uint8_t
    {
        NONE                           = 0,
        VCSEL_CONTINUITY_TEST_FAILURE  = 1,
        VCSEL_WATCHDOG_TEST_FAILURE    = 2,
        NO_VHV_VALUE_FOUND             = 3,
        MSRC_NO_TARGET                 = 4,
        SNR_CHECK                      = 5,
        RANGE_PHASE_CHECK              = 6,
        SIGMA_THRESHOLD_CHECK          = 7,
        TCC                            = 8,
        PHASE_CONSISTENCY              = 9,
        MIN_CLIP                       = 10,
        RANGE_COMPLETE                 = 11,
        ALGO_UNDERFLOW                 = 12,
        ALGO_OVERFLOW                  = 13,
        RANGE_IGNORE_THRESHOLD         = 14,
        UNKNOWN                        = 15
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, DeviceError error)
    {
        auto convert = [](DeviceError e)
        {
            switch (e)
            {
                case DeviceError::NONE:
                return F("NONE");
 
                case DeviceError::VCSEL_CONTINUITY_TEST_FAILURE:
                return F("VCSEL_CONTINUITY_TEST_FAILURE");
 
                case DeviceError::VCSEL_WATCHDOG_TEST_FAILURE:
                return F("VCSEL_WATCHDOG_TEST_FAILURE");
 
                case DeviceError::NO_VHV_VALUE_FOUND:
                return F("NO_VHV_VALUE_FOUND");
 
                case DeviceError::MSRC_NO_TARGET:
                return F("MSRC_NO_TARGET");
 
                case DeviceError::SNR_CHECK:
                return F("SNR_CHECK");
 
                case DeviceError::RANGE_PHASE_CHECK:
                return F("RANGE_PHASE_CHECK");
 
                case DeviceError::SIGMA_THRESHOLD_CHECK:
                return F("SIGMA_THRESHOLD_CHECK");
 
                case DeviceError::TCC:
                return F("TCC");
 
                case DeviceError::PHASE_CONSISTENCY:
                return F("PHASE_CONSISTENCY");
 
                case DeviceError::MIN_CLIP:
                return F("MIN_CLIP");
 
                case DeviceError::RANGE_COMPLETE:
                return F("RANGE_COMPLETE");
 
                case DeviceError::ALGO_UNDERFLOW:
                return F("ALGO_UNDERFLOW");
 
                case DeviceError::ALGO_OVERFLOW:
                return F("ALGO_OVERFLOW");
 
                case DeviceError::RANGE_IGNORE_THRESHOLD:
                return F("RANGE_IGNORE_THRESHOLD");
 
                case DeviceError::UNKNOWN:
                return F("UNKNOWN");
 
                default:
                return F("");
            }
        };
        return out << convert(error);
    }
 
    class DeviceStatus
    {
    public:
        DeviceStatus() = default;
 
        DeviceError error() const
        {
            return DeviceError((status_ >> ERROR_SHIFT) & ERROR_MASK);
        }
 
        bool data_ready() const
        {
            return status_ & DATA_READY_MASK;
        }
 
    private:
        uint8_t status_ = 0;
        static constexpr uint8_t DATA_READY_MASK = 0x01;
        static constexpr uint8_t ERROR_SHIFT = 3;
        static constexpr uint8_t ERROR_MASK = 0x0F;
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, DeviceStatus status)
    {
        return out << '(' << status.error() << ',' << status.data_ready() << ')';
    }
 
    enum class PowerMode : uint8_t
    {
        STANDBY = 0,
        IDLE = 1
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, PowerMode mode)
    {
        auto convert = [](PowerMode m)
        {
            switch (m)
            {
                case PowerMode::IDLE:
                return F("IDLE");
 
                case PowerMode::STANDBY:
                return F("STANDBY");
 
                default:
                return F("");
            }
        };
        return out << convert(mode);
    }
 
    enum class GPIOFunction : uint8_t
    {
        DISABLED = 0x00,
        LEVEL_LOW = 0x01,
        LEVEL_HIGH = 0x02,
        OUT_OF_WINDOW = 0x03,
        SAMPLE_READY = 0x04
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, GPIOFunction function)
    {
        auto convert = [](GPIOFunction f)
        {
            switch (f)
            {
                case GPIOFunction::DISABLED: 
                return F("DISABLED");
 
                case GPIOFunction::LEVEL_LOW: 
                return F("LEVEL_LOW");
 
                case GPIOFunction::LEVEL_HIGH: 
                return F("LEVEL_HIGH");
 
                case GPIOFunction::OUT_OF_WINDOW: 
                return F("OUT_OF_WINDOW");
 
                case GPIOFunction::SAMPLE_READY: 
                return F("SAMPLE_READY");
 
                default:
                return F("");
            }
        };
        return out << convert(function);
    }
 
    class GPIOSettings
    {
    public:
        constexpr GPIOSettings() = default;
        constexpr GPIOSettings(GPIOFunction function, bool high_polarity, 
            uint16_t low_threshold = 0, uint16_t high_threshold = 0)
            :   function_{function}, high_polarity_{high_polarity}, 
                low_threshold_{low_threshold}, high_threshold_{high_threshold} {}
 
        static constexpr GPIOSettings sample_ready(bool high_polarity = false)
        {
            return GPIOSettings{GPIOFunction::SAMPLE_READY, high_polarity};
        }
 
        static constexpr GPIOSettings low_threshold(uint16_t threshold, bool high_polarity = false)
        {
            return GPIOSettings{GPIOFunction::LEVEL_LOW, high_polarity, threshold};
        }
 
        static constexpr GPIOSettings high_threshold(uint16_t threshold, bool high_polarity = false)
        {
            return GPIOSettings{GPIOFunction::LEVEL_HIGH, high_polarity, 0, threshold};
        }
 
        static constexpr GPIOSettings out_of_window(
            uint16_t low_threshold, uint16_t high_threshold, bool high_polarity = false)
        {
            return GPIOSettings{GPIOFunction::OUT_OF_WINDOW, high_polarity, low_threshold, high_threshold};
        }
 
        GPIOFunction function() const
        {
            return function_;
        }
        bool high_polarity() const
        {
            return high_polarity_;
        }
        uint16_t low_threshold() const
        {
            return low_threshold_;
        }
        uint16_t high_threshold() const
        {
            return high_threshold_;
        }
 
    private:
        GPIOFunction function_ = GPIOFunction::DISABLED;
        bool high_polarity_ = false;
        uint16_t low_threshold_ = 0;
        uint16_t high_threshold_ = 0;
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, const GPIOSettings& settings)
    {
        out << F("(GPIO function=");
        out.setf(streams::ios::dec, streams::ios::basefield);
        out << settings.function()
            << F(", ") << (settings.high_polarity() ? F("HIGH") : F("LOW")) << F(" polarity")
            << F(", low_threshold=");
        out.setf(streams::ios::hex, streams::ios::basefield);
        out << settings.low_threshold()
            << F(", high_threshold=");
        out.setf(streams::ios::hex, streams::ios::basefield);
        out << settings.high_threshold() << ')';
        return out;
    }
 
    class InterruptStatus
    {
    public:
        InterruptStatus() = default;
        //TODO maybe return more useful info (is each bit mapped to GPIOFunction?)
        explicit operator uint8_t() const
        {
            return status_ & STATUS_MASK;
        }
 
    private:
        uint8_t status_ = 0;
        static constexpr uint8_t STATUS_MASK = 0x07;
    };
 
    class SPADReference
    {
    public:
        static constexpr uint8_t NUM_PADS_BYTES = 6;
        SPADReference() = default;
        explicit SPADReference(const uint8_t spad_refs[NUM_PADS_BYTES])
        {
            memcpy(spad_refs_, spad_refs, NUM_PADS_BYTES);
        }
 
        const uint8_t* spad_refs() const
        {
            return spad_refs_;
        }
 
        uint8_t* spad_refs()
        {
            return spad_refs_;
        }
 
    private:
        uint8_t spad_refs_[NUM_PADS_BYTES];
    };
 
    enum class VcselPeriodType : uint8_t
    {
        PRE_RANGE = uint8_t(vl53l0x::Register::PRE_RANGE_CONFIG_VCSEL_PERIOD),
        FINAL_RANGE = uint8_t(vl53l0x::Register::FINAL_RANGE_CONFIG_VCSEL_PERIOD)
    };
 
    class SequenceSteps
    {
    private:
        static constexpr uint8_t FORCED_BITS = bits::BV8(5);
        // TCC Target Center Check
        static constexpr uint8_t TCC = bits::BV8(4);
        // DSS Dynamic Spad Selection
        static constexpr uint8_t DSS = bits::BV8(3);
        // MSRC Minimum Signal Rate Check
        static constexpr uint8_t MSRC = bits::BV8(2);
        // PRE_RANGE Pre-Range Check
        static constexpr uint8_t PRE_RANGE = bits::BV8(6);
        // FINAL_RANGE Final-Range Check
        static constexpr uint8_t FINAL_RANGE = bits::BV8(7);
 
    public:
        static constexpr SequenceSteps create()
        {
            return SequenceSteps{};
        }
        static constexpr SequenceSteps all()
        {
            return SequenceSteps{TCC | DSS | MSRC | PRE_RANGE | FINAL_RANGE};
        }
 
        constexpr SequenceSteps() = default;
 
        constexpr SequenceSteps tcc() const
        {
            return SequenceSteps{uint8_t(steps_ | TCC)};
        }
 
        constexpr SequenceSteps dss() const
        {
            return SequenceSteps{uint8_t(steps_ | DSS)};
        }
 
        constexpr SequenceSteps msrc() const
        {
            return SequenceSteps{uint8_t(steps_ | MSRC)};
        }
 
        constexpr SequenceSteps pre_range() const
        {
            return SequenceSteps{uint8_t(steps_ | PRE_RANGE)};
        }
 
        constexpr SequenceSteps final_range() const
        {
            return SequenceSteps{uint8_t(steps_ | FINAL_RANGE)};
        }
 
        constexpr SequenceSteps no_tcc() const
        {
            return SequenceSteps{uint8_t(steps_ & bits::COMPL(TCC))};
        }
 
        constexpr SequenceSteps no_dss() const
        {
            return SequenceSteps{uint8_t(steps_ & bits::COMPL(DSS))};
        }
 
        constexpr SequenceSteps no_msrc() const
        {
            return SequenceSteps{uint8_t(steps_ & bits::COMPL(MSRC))};
        }
 
        constexpr SequenceSteps no_pre_range() const
        {
            return SequenceSteps{uint8_t(steps_ & bits::COMPL(PRE_RANGE))};
        }
 
        constexpr SequenceSteps no_final_range() const
        {
            return SequenceSteps{uint8_t(steps_ & bits::COMPL(FINAL_RANGE))};
        }
 
        uint8_t value() const
        {
            return steps_;
        }
 
        bool is_tcc() const
        {
            return steps_ & TCC;
        }
 
        bool is_dss() const
        {
            return steps_ & DSS;
        }
 
        bool is_msrc() const
        {
            return steps_ & MSRC;
        }
 
        bool is_pre_range() const
        {
            return steps_ & PRE_RANGE;
        }
 
        bool is_final_range() const
        {
            return steps_ & FINAL_RANGE;
        }
 
    private:
        explicit constexpr SequenceSteps(uint8_t steps) : steps_{uint8_t(steps | FORCED_BITS)} {}
 
        uint8_t steps_ = FORCED_BITS;
 
        template<typename MANAGER> friend class VL53L0X;
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, SequenceSteps steps)
    {
        auto with_without = [](OSTREAM& o, bool with, const flash::FlashStorage* label)
        {
            if (!with)
                o << F("no ");
            o << label;
        };
        out << '(';
        with_without(out, steps.is_tcc(), F("TCC"));
        out << ',';
        with_without(out, steps.is_dss(), F("DSS"));
        out << ',';
        with_without(out, steps.is_msrc(), F("MSRC"));
        out << ',';
        with_without(out, steps.is_pre_range(), F("PRE_RANGE"));
        out << ',';
        with_without(out, steps.is_final_range(), F("FINAL_RANGE"));
        out << ')';
        return out;
    }
 
    class SequenceStepsTimeout
    {
    public:
        SequenceStepsTimeout() = default;
 
        uint8_t pre_range_vcsel_period_pclks() const
        {
            return pre_range_vcsel_period_pclks_;
        }
 
        uint8_t final_range_vcsel_period_pclks() const
        {
            return final_range_vcsel_period_pclks_;
        }
 
        uint16_t msrc_dss_tcc_mclks() const
        {
            return msrc_dss_tcc_mclks_ + 1;
        }
 
        uint16_t pre_range_mclks() const
        {
            return TimeoutUtilities::decode_timeout(pre_range_mclks_);
        }
 
        uint16_t final_range_mclks(bool is_pre_range) const
        {
            uint16_t temp_final_range_mclks = TimeoutUtilities::decode_timeout(final_range_mclks_);
            return (is_pre_range ? (temp_final_range_mclks - pre_range_mclks()) : temp_final_range_mclks);
        }
 
        // Following values are calculated from others
 
        uint32_t msrc_dss_tcc_us() const
        {
            return TimeoutUtilities::calculate_timeout_us(msrc_dss_tcc_mclks(), pre_range_vcsel_period_pclks());
        }
 
        uint32_t pre_range_us() const
        {
            return TimeoutUtilities::calculate_timeout_us(pre_range_mclks(), pre_range_vcsel_period_pclks());
        }
 
        uint32_t final_range_us(bool is_pre_range) const
        {
            return TimeoutUtilities::calculate_timeout_us(
                final_range_mclks(is_pre_range), final_range_vcsel_period_pclks());
        }
 
    private:
        SequenceStepsTimeout(uint8_t pre_range_vcsel_period_pclks, uint8_t final_range_vcsel_period_pclks,
            uint8_t msrc_dss_tcc_mclks, uint16_t pre_range_mclks, uint16_t final_range_mclks)
            :   pre_range_vcsel_period_pclks_{pre_range_vcsel_period_pclks},
                final_range_vcsel_period_pclks_{final_range_vcsel_period_pclks},
                msrc_dss_tcc_mclks_{msrc_dss_tcc_mclks},
                pre_range_mclks_{pre_range_mclks},
                final_range_mclks_{final_range_mclks} {}
 
        uint8_t pre_range_vcsel_period_pclks_ = 0;
        uint8_t final_range_vcsel_period_pclks_ = 0;
 
        uint8_t msrc_dss_tcc_mclks_ = 0;
        uint16_t pre_range_mclks_ = 0;
        uint16_t final_range_mclks_ = 0;
 
        template<typename MANAGER> friend class VL53L0X;
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, const SequenceStepsTimeout& timeouts)
    {
        out << F("(pre_range_vcsel_period_pclks=");
        out.setf(streams::ios::dec, streams::ios::basefield);
        out << timeouts.pre_range_vcsel_period_pclks()
            << F(", final_range_vcsel_period_pclks=")
            << timeouts.final_range_vcsel_period_pclks()
            << F(", msrc_dss_tcc_mclks=")
            << timeouts.msrc_dss_tcc_mclks()
            << F(", pre_range_mclks=")
            << timeouts.pre_range_mclks()
            << F(", final_range_mclks(with pre-range)=")
            << timeouts.final_range_mclks(true) << ')'
            << F(", final_range_mclks(no pre-range)=")
            << timeouts.final_range_mclks(false) << ')'
            << F(", msrc_dss_tcc_us()=")
            << timeouts.msrc_dss_tcc_us() << F("us,")
            << F(", pre_range_us()=")
            << timeouts.pre_range_us() << F("us,")
            << F(", final_range_us(with pre-range)=")
            << timeouts.final_range_us(true) << F("us,")
            << F(", final_range_us(no pre-range)=")
            << timeouts.final_range_us(false) << F("us)");
        return out;
    }
 
    class SPADInfo
    {
    private:
        static constexpr uint8_t APERTURE = bits::BV8(7);
        static constexpr uint8_t COUNT = bits::CBV8(7);
 
    public:
        SPADInfo() = default;
        explicit SPADInfo(uint8_t info) : info_{info} {}
 
        bool is_aperture() const
        {
            return info_ & APERTURE;
        }
 
        uint8_t count() const
        {
            return info_ & COUNT;
        }
 
    private:
        uint8_t info_ = 0;
    };
 
    template<typename OSTREAM> OSTREAM& operator<<(OSTREAM& out, SPADInfo info)
    {
        out << F("(aperture=") << info.is_aperture()
            << F(", count=");
        out.setf(streams::ios::dec, streams::ios::basefield);
        out << info.count() << ')';
        return out;
    }
 
    enum class Profile : uint8_t
    {
        STANDARD = 0x00,
        LONG_RANGE = 0x01,
        STANDARD_ACCURATE = 0x02,
        LONG_RANGE_ACCURATE = 0x03,
        STANDARD_FAST = 0x04,
        LONG_RANGE_FAST = 0x05,
    };
}
 
#endif /* VL53L0X_TYPES_H */