hmc5883l.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 HMC5883L_H
#define HMC5883L_H
 
#include <math.h>
#include "common_magneto.h"
#include "../bits.h"
#include "../functors.h"
#include "../i2c_device.h"
#include "../i2c_device_utilities.h"
#include "../utilities.h"
 
namespace devices::magneto
{
    inline float magnetic_heading(int16_t x, int16_t y)
    {
        float theta = atan2(y, x);
        return theta;
    }
 
    enum class SamplesAveraged : uint8_t
    {
        ONE_SAMPLE = 0 << 5,
        TWO_SAMPLES = 1 << 5,
        FOUR_SAMPLES = 2 << 5,
        EIGHT_SAMPLES = 3 << 5
    };
 
    enum class DataOutput : uint8_t
    {
        RATE_0_75HZ = 0 << 2,
        RATE_1_5HZ = 1 << 2,
        RATE_3HZ = 2 << 2,
        RATE_7_5HZ = 3 << 2,
        RATE_15HZ = 4 << 2,
        RATE_30HZ = 5 << 2,
        RATE_75HZ = 6 << 2
    };
 
    enum class MeasurementMode : uint8_t
    {
        NORMAL = 0,
        POSITIVE_BIAS = 1,
        NEGATIVE_BIAS = 2
    };
 
    enum class OperatingMode : uint8_t
    {
        CONTINUOUS = 0,
        SINGLE = 1,
        IDLE = 2
    };
 
    enum class Gain : uint8_t
    {
        GAIN_0_88GA = 0 << 5,
        GAIN_1_3GA = 1 << 5,
        GAIN_1_9GA = 2 << 5,
        GAIN_2_5GA = 3 << 5,
        GAIN_4_0GA = 4 << 5,
        GAIN_4_7GA = 5 << 5,
        GAIN_5_6GA = 6 << 5,
        GAIN_8_1GA = 7 << 5
    };
 
    class Status
    {
    public:
        Status() = default;
 
        bool ready() const
        {
            return data_ & READY;
        }
 
        bool lock() const
        {
            return data_ & LOCK;
        }
 
    private:
        static constexpr uint8_t READY = bits::BV8(0);
        static constexpr uint8_t LOCK = bits::BV8(1);
 
        uint8_t data_ = 0;
    };
 
    template<typename MANAGER>
    class HMC5883L : public i2c::I2CDevice<MANAGER>
    {
    private:
        using PARENT = i2c::I2CDevice<MANAGER>;
        template<typename OUT, typename IN> using FUTURE = typename PARENT::template FUTURE<OUT, IN>;
 
        // Forward declarations needed by compiler
        template<uint8_t REGISTER, typename T = uint8_t, typename FUNCTOR = functor::Identity<T>>
        using TReadRegisterFuture = i2c::TReadRegisterFuture<MANAGER, REGISTER, T, FUNCTOR>;
        template<uint8_t REGISTER, typename T = uint8_t, typename FUNCTOR = functor::Identity<T>>
        using TWriteRegisterFuture = i2c::TWriteRegisterFuture<MANAGER, REGISTER, T, FUNCTOR>;
        template<typename T, uint8_t... REGISTERS>
        using TWriteMultiRegisterFuture = i2c::TWriteMultiRegisterFuture<MANAGER, T, REGISTERS...>;
 
        static constexpr const uint8_t DEVICE_ADDRESS = 0x1E << 1;
 
        static constexpr const uint8_t CONFIG_REG_A = 0;
        static constexpr const uint8_t CONFIG_REG_B = 1;
        static constexpr const uint8_t MODE_REG = 2;
        static constexpr const uint8_t OUTPUT_REG_1 = 3;
        static constexpr const uint8_t STATUS_REG = 9;
        static constexpr const uint8_t IDENT_REG_A = 10;
        static constexpr const uint8_t IDENT_REG_B = 11;
        static constexpr const uint8_t IDENT_REG_C = 12;
 
        // Transformer functor for Sensor3D inverted fields
        class Sensor3DSwitcher
        {
        public:
            using ARG_TYPE = Sensor3D;
            using RES_TYPE = Sensor3D;
            Sensor3D operator()(const Sensor3D& value) const
            {
                Sensor3D result = value;
                // HMC5883L registers are in order X,Z,Y while Sensor3D is X,Y,Z
                int16_t temp = result.y;
                result.y = result.z;
                result.z = temp;
                return result;
            }
        };
 
        using Sensor3DTransformer = 
            functor::Compose<Sensor3DSwitcher, functor::ChangeEndianness<Sensor3D, int16_t>>;
 
    public:
        explicit HMC5883L(MANAGER& manager) : PARENT{manager, DEVICE_ADDRESS, i2c::I2C_FAST, false} {}
 
        // Asynchronous API
        //==================
        class BeginFuture : public TWriteMultiRegisterFuture<uint8_t, CONFIG_REG_A, CONFIG_REG_B, MODE_REG>
        {
            using PARENT = TWriteMultiRegisterFuture<uint8_t, CONFIG_REG_A, CONFIG_REG_B, MODE_REG>;
        public:
            explicit BeginFuture(   OperatingMode mode = OperatingMode::SINGLE,
                                    Gain gain = Gain::GAIN_1_3GA,
                                    DataOutput rate = DataOutput::RATE_15HZ, 
                                    SamplesAveraged samples = SamplesAveraged::ONE_SAMPLE,
                                    MeasurementMode measurement = MeasurementMode::NORMAL)
                :   PARENT{ bits::OR8(uint8_t(measurement), uint8_t(rate), uint8_t(samples)),
                            uint8_t(gain), uint8_t(mode)} {}
 
            Gain gain() const
            {
                return static_cast<Gain>(this->get_input().value(1));
            }
        };
 
        int begin(BeginFuture& future)
        {
            gain_ = GAIN(future.gain());
            return this->async_multi_write(future);
        }
 
        using EndFuture = 
            TWriteRegisterFuture<MODE_REG, uint8_t, functor::Constant<uint8_t, uint8_t(OperatingMode::IDLE)>>;
 
        int end(EndFuture& future) INLINE
        {
            return this->async_write(future);
        }
 
        using StatusFuture = TReadRegisterFuture<STATUS_REG, Status>;
 
        int status(StatusFuture& future) INLINE
        {
            return this->async_read(future);
        }
 
        using MagneticFieldsFuture = 
            TReadRegisterFuture<OUTPUT_REG_1, Sensor3D, Sensor3DTransformer>;
 
        int magnetic_fields(MagneticFieldsFuture& future)
        {
            return this->async_read(future);
        }
 
        // Synchronous API
        //=================
        bool begin(OperatingMode mode = OperatingMode::SINGLE, Gain gain = Gain::GAIN_1_3GA,
                   DataOutput rate = DataOutput::RATE_15HZ, SamplesAveraged samples = SamplesAveraged::ONE_SAMPLE,
                   MeasurementMode measurement = MeasurementMode::NORMAL)
        {
            BeginFuture future{mode, gain, rate, samples, measurement};
            if (begin(future) != 0) return false;
            return (future.await() == future::FutureStatus::READY);
        }
 
        bool end() INLINE
        {
            return this->template sync_write<EndFuture>();
        }
 
        Status status() INLINE
        {
            Status status;
            if (this->template sync_read<StatusFuture>(status))
                return status;
            else
                return Status{};
        }
 
        bool magnetic_fields(Sensor3D& fields)
        {
            return this->template sync_read<MagneticFieldsFuture>(fields);
        }
 
        void convert_fields_to_mGA(Sensor3D& fields)
        {
            convert_field_to_mGa(fields.x);
            convert_field_to_mGa(fields.y);
            convert_field_to_mGa(fields.z);
        }
 
    private:
        void convert_field_to_mGa(int16_t& value)
        {
            value = value * 1000L / gain_;
        }
 
        static constexpr uint16_t GAIN(Gain gain)
        {
            if (gain == Gain::GAIN_0_88GA) return 1370;
            if (gain == Gain::GAIN_1_3GA) return 1090;
            if (gain == Gain::GAIN_1_9GA) return 820;
            if (gain == Gain::GAIN_2_5GA) return 660;
            if (gain == Gain::GAIN_4_0GA) return 440;
            if (gain == Gain::GAIN_4_7GA) return 390; 
            if (gain == Gain::GAIN_5_6GA) return 330;
            return 230;
        }
 
        uint16_t gain_;
    };
}
 
#endif /* HMC5883L_H */