249 lines
9 KiB
C
249 lines
9 KiB
C
|
/**
|
||
|
|
* Driver for LIS3MDL 3-axes digital magnetometer connected to I2C or SPI.
|
||
|
|
*
|
||
|
|
* This driver is for the usage with the ESP8266 and FreeRTOS (esp-open-rtos)
|
||
|
|
* [https://github.com/SuperHouse/esp-open-rtos]. It is also working with ESP32
|
||
|
|
* and ESP-IDF [https://github.com/espressif/esp-idf.git] as well as Linux
|
||
|
|
* based systems using a wrapper library for ESP8266 functions.
|
||
|
|
*
|
||
|
|
* ---------------------------------------------------------------------------
|
||
|
|
*
|
||
|
|
* The BSD License (3-clause license)
|
||
|
|
*
|
||
|
|
* Copyright (c) 2017 Gunar Schorcht (https://github.com/gschorcht)
|
||
|
|
* All rights reserved.
|
||
|
|
*
|
||
|
|
* Redistribution and use in source and binary forms, with or without
|
||
|
|
* modification, are permitted provided that the following conditions are met:
|
||
|
|
*
|
||
|
|
* 1. Redistributions of source code must retain the above copyright notice,
|
||
|
|
* this list of conditions and the following disclaimer.
|
||
|
|
*
|
||
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
||
|
|
* notice, this list of conditions and the following disclaimer in the
|
||
|
|
* documentation and/or other materials provided with the distribution.
|
||
|
|
*
|
||
|
|
* 3. Neither the name of the copyright holder nor the names of its
|
||
|
|
* contributors may be used to endorse or promote products derived from this
|
||
|
|
* software without specific prior written permission.
|
||
|
|
*
|
||
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
||
|
|
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||
|
|
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||
|
|
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
|
||
|
|
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
||
|
|
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
||
|
|
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
||
|
|
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
||
|
|
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
||
|
|
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
||
|
|
*/
|
||
|
|
|
||
|
|
#ifndef __LIS3MDL_H__
|
||
|
|
#define __LIS3MDL_H__
|
||
|
|
|
||
|
|
// Uncomment one of the following defines to enable debug output
|
||
|
|
// #define LIS3MDL_DEBUG_LEVEL_1 // only error messages
|
||
|
|
// #define LIS3MDL_DEBUG_LEVEL_2 // debug and error messages
|
||
|
|
|
||
|
|
// LIS3MDL addresses
|
||
|
|
#define LIS3MDL_I2C_ADDRESS_1 0x1c // SDO pin is low
|
||
|
|
#define LIS3MDL_I2C_ADDRESS_2 0x1e // SDO pin is high
|
||
|
|
|
||
|
|
// LIS3MDL chip id
|
||
|
|
#define LIS3MDL_CHIP_ID 0x3d // LIS3MDL_REG_WHO_AM_I<7:0>
|
||
|
|
|
||
|
|
// Definition of error codes
|
||
|
|
#define LIS3MDL_OK 0
|
||
|
|
#define LIS3MDL_NOK -1
|
||
|
|
|
||
|
|
#define LIS3MDL_INT_ERROR_MASK 0x000f
|
||
|
|
#define LIS3MDL_DRV_ERROR_MASK 0xfff0
|
||
|
|
|
||
|
|
// Error codes for I2C and SPI interfaces ORed with LIS3MDL driver error codes
|
||
|
|
#define LIS3MDL_I2C_READ_FAILED 1
|
||
|
|
#define LIS3MDL_I2C_WRITE_FAILED 2
|
||
|
|
#define LIS3MDL_I2C_BUSY 3
|
||
|
|
#define LIS3MDL_SPI_WRITE_FAILED 4
|
||
|
|
#define LIS3MDL_SPI_READ_FAILED 5
|
||
|
|
#define LIS3MDL_SPI_BUFFER_OVERFLOW 6
|
||
|
|
|
||
|
|
// LIS3MDL driver error codes ORed with error codes for I2C and SPI interfaces
|
||
|
|
#define LIS3MDL_WRONG_CHIP_ID ( 1 << 8)
|
||
|
|
#define LIS3MDL_GET_RAW_DATA_FAILED ( 2 << 8)
|
||
|
|
#define LIS3MDL_CONFIG_INT_FAILED ( 3 << 8)
|
||
|
|
#define LIS3MDL_INT_SOURCE_FAILED ( 4 << 8)
|
||
|
|
#define LIS3MDL_GET_ADC_DATA_FAILED ( 5 << 8)
|
||
|
|
|
||
|
|
#include "lis3mdl_platform.h"
|
||
|
|
#include "lis3mdl_types.h"
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
extern "C"
|
||
|
|
{
|
||
|
|
#endif
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Initialize the sensor
|
||
|
|
*
|
||
|
|
* Reset the sensor and switch to power down mode. All registers are reset to
|
||
|
|
* default values.
|
||
|
|
*
|
||
|
|
* @param bus I2C or SPI bus at which LIS3MDL sensor is connected
|
||
|
|
* @param addr I2C addr of the LIS3MDL sensor, 0 for using SPI
|
||
|
|
* @param cs SPI CS GPIO, ignored for I2C
|
||
|
|
* @return pointer to sensor data structure, or NULL on error
|
||
|
|
*/
|
||
|
|
lis3mdl_sensor_t* lis3mdl_init_sensor (uint8_t bus, uint8_t addr, uint8_t cs);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Set sensor operation mode (OM) and output data rate (ODR)
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param mode sensor operation mode (OM) at output data rate (ODR)
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_set_mode (lis3mdl_sensor_t* dev, lis3mdl_mode_t mode);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Set scale (full scale range)
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param scale full range scale
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_set_scale (lis3mdl_sensor_t* dev, lis3mdl_scale_t scale);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Test whether new data samples are available
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @return true on new data, otherwise false
|
||
|
|
*/
|
||
|
|
bool lis3mdl_new_data (lis3mdl_sensor_t* dev);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get one sample of sensor data as floating point values (unit Gauss)
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param data pointer to float data structure filled with g values
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_get_float_data (lis3mdl_sensor_t* dev,
|
||
|
|
lis3mdl_float_data_t* data);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get one sample of raw sensor data as 16 bit two's complements
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param raw pointer to raw data structure filled with values
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_get_raw_data (lis3mdl_sensor_t* dev, lis3mdl_raw_data_t* raw);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Set configuration for threshold interrupt signal INT
|
||
|
|
*
|
||
|
|
* The function enables the interrupt signal if one of the possible sources
|
||
|
|
* is enabled for interrupts.
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param config configuration for the specified interrupt signal
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_set_int_config (lis3mdl_sensor_t* dev,
|
||
|
|
lis3mdl_int_config_t* config);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get configuration for threshold interrupt signal INT
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param config configuration for the specified interrupt signal
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_get_int_config (lis3mdl_sensor_t* dev,
|
||
|
|
lis3mdl_int_config_t* config);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get the source of the threshold interrupt signal INT
|
||
|
|
*
|
||
|
|
* Returns a byte with flags that indicate the value(s) that triggered
|
||
|
|
* the interrupt signal (see INT_SRC register in datasheet for details)
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param source pointer to the interrupt source
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_get_int_source (lis3mdl_sensor_t* dev,
|
||
|
|
lis3mdl_int_source_t* source);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Enable/Disable temperature sensor
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param enable if true, temperature sensor is enabled
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_enable_temperature (lis3mdl_sensor_t* dev, bool enable);
|
||
|
|
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Get temperature
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @return temperature in degree
|
||
|
|
*/
|
||
|
|
float lis3mdl_get_temperature (lis3mdl_sensor_t* dev);
|
||
|
|
|
||
|
|
// ---- Low level interface functions -----------------------------
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Direct write to register
|
||
|
|
*
|
||
|
|
* PLEASE NOTE: This function should only be used to do something special that
|
||
|
|
* is not covered by the high level interface AND if you exactly know what you
|
||
|
|
* do and what effects it might have. Please be aware that it might affect the
|
||
|
|
* high level interface.
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param reg address of the first register to be changed
|
||
|
|
* @param data pointer to the data to be written to the register
|
||
|
|
* @param len number of bytes to be written to the register
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_reg_write (lis3mdl_sensor_t* dev,
|
||
|
|
uint8_t reg, uint8_t *data, uint16_t len);
|
||
|
|
|
||
|
|
/**
|
||
|
|
* @brief Direct read from register
|
||
|
|
*
|
||
|
|
* PLEASE NOTE: This function should only be used to do something special that
|
||
|
|
* is not covered by the high level interface AND if you exactly know what you
|
||
|
|
* do and what effects it might have. Please be aware that it might affect the
|
||
|
|
* high level interface.
|
||
|
|
*
|
||
|
|
* @param dev pointer to the sensor device data structure
|
||
|
|
* @param reg address of the first register to be read
|
||
|
|
* @param data pointer to the data to be read from the register
|
||
|
|
* @param len number of bytes to be read from the register
|
||
|
|
* @return true on success, false on error
|
||
|
|
*/
|
||
|
|
bool lis3mdl_reg_read (lis3mdl_sensor_t* dev,
|
||
|
|
uint8_t reg, uint8_t *data, uint16_t len);
|
||
|
|
|
||
|
|
#ifdef __cplusplus
|
||
|
|
}
|
||
|
|
#endif /* End of CPP guard */
|
||
|
|
|
||
|
|
#endif /* __LIS3MDL_H__ */
|