From 4f65089b2213fd8c29abd4f58e3ee40ad0651347 Mon Sep 17 00:00:00 2001 From: anschrammh Date: Sat, 17 Dec 2022 20:41:41 +0100 Subject: [PATCH] Commented the driver API and added a way to calibrate the temperature reading --- .../app/drivers/i2c/QMC5883L.c | 14 ++- .../app/drivers/i2c/QMC5883L.h | 95 ++++++++++++++++++- 2 files changed, 98 insertions(+), 11 deletions(-) diff --git a/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.c b/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.c index 07ab202..e1727f8 100644 --- a/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.c +++ b/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.c @@ -2,10 +2,6 @@ #include "i2c.h" #include "QMC5883L.h" -#ifndef PI -#define PI 3.14159265358979f -#endif - typedef struct { int16_t x_min; @@ -14,6 +10,7 @@ typedef struct int16_t y_max; int16_t z_min; int16_t z_max; + float temperature_offset; } _QMC5883L_calibration_data; static _QMC5883L_calibration_data calibration_data = {0}; @@ -42,7 +39,7 @@ float QMC5883L_get_temperature(void) raw_temp |= data; - return (float) raw_temp / 100.0; + return (float) raw_temp / 100.0 + calibration_data.temperature_offset; } bool QMC5883L_is_data_available(void) @@ -54,7 +51,7 @@ bool QMC5883L_is_data_available(void) return data & QMC5883L_DRDY_BIT ? true : false; } -void QMC5883L_set_calibration_data(int16_t x_min, int16_t x_max, int16_t y_min, int16_t y_max, int16_t z_min, int16_t z_max) +void QMC5883L_set_calibration_data(int16_t x_min, int16_t x_max, int16_t y_min, int16_t y_max, int16_t z_min, int16_t z_max, float temperature_offset) { calibration_data.x_min = x_min; calibration_data.x_max = x_max; @@ -62,6 +59,7 @@ void QMC5883L_set_calibration_data(int16_t x_min, int16_t x_max, int16_t y_min, calibration_data.y_max = y_max; calibration_data.z_min = z_min; calibration_data.z_max = z_max; + calibration_data.temperature_offset = temperature_offset; } QMC5883L_MData_t QMC5883L_get_MFields_raw(void) @@ -111,9 +109,9 @@ QMC5883L_MData_calibrated_t QMC5883L_get_MFields_calibrated(void) return Mdata; } -int16_t QMC5883L_get_azimuth(const QMC5883L_MData_calibrated_t data) +uint16_t QMC5883L_get_azimuth(const QMC5883L_MData_calibrated_t data) { - int16_t angle = atan2(data.MFieldY, data.MFieldX) * 180.0 / PI; + int16_t angle = atan2(data.MFieldY, data.MFieldX) * 180.0 / M_PI; return angle < 0 ? 360 + angle : angle; } diff --git a/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.h b/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.h index f52ca7c..8d5aa29 100644 --- a/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.h +++ b/src/W800 SDK v1.00.08/app/drivers/i2c/QMC5883L.h @@ -63,27 +63,116 @@ typedef struct } QMC5883L_MData_calibrated_t; -/* QMC5883L Driver API */ +/** + * @brief Initializes the QMC5883L sensor. This must be called before any other API functions. + * Don't forget to initialize the I2C peripheral using the i2c_init function first ! + * + * @return true on success + * @return false on failure + */ bool QMC5883L_init(void); +/** + * @brief Issues a software reset of the sensor. + * + * @return true on success + * @return false on failure + */ bool QMC5883L_software_reset(void); +/** + * @brief Gets the temperature measured by the sensor in degrees celsius. + * Only the relative temperature value is accurate ! + * If you need the real temperature, a calibration offset IS NEEDED using the @ref QMC5883L_set_calibration_data function ! + * + * @return float the temperature in °C + */ float QMC5883L_get_temperature(void); +/** + * @brief Indicates if data is ready to be read from the sensor or not. + * You can check the ouput of this function before calling @ref QMC5883L_get_MFields_raw or @ref QMC5883L_get_MFields_calibrated. + * + * @return true if data is available + * @return false if no data is available + */ bool QMC5883L_is_data_available(void); -void QMC5883L_set_calibration_data(int16_t x_min, int16_t x_max, int16_t y_min, int16_t y_max, int16_t z_min, int16_t z_max); +/** + * @brief Sets all the calibration data needed to get accurate readings from the sensor. + * Default value if not set is 0. + * You can use the @ref QMC5883L_get_MFields_raw function to get raw readings from the sensor in order to find the min and max values of the three axes. + * + * @param x_min the min value of the magnetic field on the X axis + * @param x_max the max value of the magnetic field on the X axis + * @param y_min the min value of the magnetic field on the Y axis + * @param y_max the max value of the magnetic field on the Y axis + * @param z_min the min value of the magnetic field on the Z axis + * @param z_max the max value of the magnetic field on the Z axis + * @param temperature_offset the temperature offset needed to be applied to get an accurate reading + */ +void QMC5883L_set_calibration_data(int16_t x_min, int16_t x_max, int16_t y_min, int16_t y_max, int16_t z_min, int16_t z_max, float temperature_offset); +/** + * @brief Reads the latest data available from the sensor and returns a structure containing : + * The magnetic field value for the X axis as a signed integer on 16 bits + * The magnetic field value for the Y axis as a signed integer on 16 bits + * The magnetic field value for the Z axis as a signed integer on 16 bits + * These values are raw data, this means that they are not calibrated ! Use the @ref QMC5883L_get_MFields_calibrated instead. + * + * @return QMC5883L_MData_t the structure containing the fields + */ QMC5883L_MData_t QMC5883L_get_MFields_raw(void); +/** + * @brief Reads the latest data available from the sensor, calibrates them and returns a structure containing : + * The calibrated magnetic field value for the X axis as a signed integer on 16 bits + * The calibrated magnetic field value for the Y axis as a signed integer on 16 bits + * The calibrated magnetic field value for the Z axis as a signed integer on 16 bits + * + * @return QMC5883L_MData_calibrated_t the structure containing the calibrated fields + */ QMC5883L_MData_calibrated_t QMC5883L_get_MFields_calibrated(void); -int16_t QMC5883L_get_azimuth(const QMC5883L_MData_calibrated_t data); +/** + * @brief Returns the azimuth (the angle to north) in degrees. + * + * @param data a previously retrieved calibrated data using the @ref QMC5883L_get_MFields_calibrated function + * @return uint16_t the angle in degrees between 0 and 359. + */ +uint16_t QMC5883L_get_azimuth(const QMC5883L_MData_calibrated_t data); +/** + * @brief Configures the sensor by setting the Output Data Rate, the Range of Scale and the Over Sampling Rate. + * + * @param ODR the output data rate, can be ODR_10HZ, ODR_50HZ, ODR_100HZ or ODR_200HZ + * @param RNG the range or scale, can be FS_2G or FS_8G. + * @param OSR the over sampling rate, can be OSR_512, OSR_256, OSR_128 or OSR_64. + * @return true on success + * @return false on failure + */ bool QMC5883L_configure_1(QMC5883L_Output_Data_Rate_e ODR, QMC5883L_Full_Scale_e RNG, QMC5883L_Over_Sample_Ratio_e OSR); +/** + * @brief Configures the sensor by enabling the rolling pointer functionality (not useful) and the data ready interrupt pin. + * + * @param rolling_ptr true to enable or false to disable + * @param data_ready_int true to enable or false to disable + * @return true on success + * @return false on failure + */ bool QMC5883L_configure_2(bool rolling_ptr, bool data_ready_int); +/** + * @brief Toggles between the two availables power modes : + * Standby : puts the sensor in standby modes. In this mode, no measurements are performed and the power consumption is lowest. + * Continuous : puts the sensor in active mode by continuously performing measurement that can be retrieved using the @ref QMC5883L_get_MFields_raw + * or @ref QMC5883L_get_MFields_calibrated functions. + * + * @param MC + * @return true on success + * @return false on failure + */ bool QMC5883L_set_power_mode(QMC5883L_Mode_Control_e MC); #endif //QMC5883L_H \ No newline at end of file