1 /* 2 * Copyright (c) 2015-2016, Freescale Semiconductor, Inc. 3 * Copyright 2016-2017 NXP 4 * All rights reserved. 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 /** 10 * @file mag3110_drv.h 11 * @brief The mag3110_drv.h file describes the MAG3110 driver interface and structures. 12 */ 13 14 #ifndef MAG3110_FI_H_ 15 #define MAG3110_FI_H_ 16 17 /* Standard C Includes */ 18 #include <stdint.h> 19 20 /* ISSDK Includes */ 21 #include "mag3110.h" 22 #include "sensor_io_i2c.h" 23 #include "register_io_i2c.h" 24 25 /******************************************************************************* 26 * Definitions 27 ******************************************************************************/ 28 /*! @brief This defines the sensor specific information. */ 29 typedef struct 30 { 31 registerDeviceInfo_t deviceInfo; /*!< I2C device context. */ 32 ARM_DRIVER_I2C *pCommDrv; /*!< Pointer to the i2c driver. */ 33 bool isInitialized; /*!< Init status.*/ 34 uint16_t slaveAddress; /*!< slave address.*/ 35 } mag3110_i2c_sensorhandle_t; 36 37 /*! @brief This structure defines the mag3110 data buffer.*/ 38 typedef struct 39 { 40 uint32_t timestamp; /*!< Time stamp value in micro-seconds. */ 41 int16_t mag[3]; /*!< Sensor Magnetic Strength output: signed 16-bits. */ 42 } mag3110_magdata_t; 43 44 /******************************************************************************* 45 * APIs 46 ******************************************************************************/ 47 /*! @brief The interface function to initialize the sensor. 48 * @details This function initialize the sensor and sensor handle. 49 * @param[in] pSensorHandle handle to the sensor. 50 * @param[in] pBus pointer to the CMSIS API compatible I2C bus object. 51 * @param[in] index the I2C device number. 52 * @param[in] sAddress slave address of the device on the bus. 53 * @param[in] whoami WHO_AM_I value of the device. 54 * @constraints This should be the first API to be called. 55 * Application has to ensure that previous instances of these APIs have exited before invocation. 56 * @reeentrant No 57 * @return ::MAG3110_I2C_Initialize() returns the status. 58 */ 59 int32_t MAG3110_I2C_Initialize( 60 mag3110_i2c_sensorhandle_t *pSensorHandle, ARM_DRIVER_I2C *pBus, uint8_t index, uint16_t sAddress, uint8_t whoAmi); 61 62 /*! @brief : The interface function to set the I2C Idle Task. 63 * @param[in] : mag3110_i2c_sensorhandle_t *pSensorHandle, handle to the sensor handle. 64 * @param[in] : registeridlefunction_t idleTask, function pointer to the function to execute on I2C Idle Time. 65 * @param[in] : void *userParam, the pointer to the user idle ftask parameters. 66 * @return void. 67 * @constraints This can be called any number of times only after MAG3110_I2C_Initialize(). 68 * Application has to ensure that previous instances of these APIs have exited before invocation. 69 * @reeentrant No 70 */ 71 void MAG3110_I2C_SetIdleTask(mag3110_i2c_sensorhandle_t *pSensorHandle, 72 registeridlefunction_t idleTask, 73 void *userParam); 74 75 /*! @brief The interface function to configure he sensor. 76 * @details This function configure the sensor with requested ODR, Range and registers in the regsiter pair array. 77 * @param[in] pSensorHandle handle to the sensor. 78 * @param[in] pRegWriteList pointer to the register list. 79 * @constraints This can be called any number of times only after MAG3110_I2C_Initialize(). 80 * Application has to ensure that previous instances of these APIs have exited before invocation. 81 * @reeentrant No 82 * @return ::MAG3110_I2C_Configure() returns the status. 83 */ 84 int32_t MAG3110_I2C_Configure(mag3110_i2c_sensorhandle_t *pSensorHandle, const registerwritelist_t *pRegWriteList); 85 86 /*! @brief The interface function to read the sensor data. 87 * @details This function read the sensor data out from the device and returns raw data in a byte stream. 88 * @param[in] pSensorHandle handle to the sensor. 89 * @param[in] pReadList pointer to the list of device registers and values to read. 90 * @param[out] pBuffer buffer which holds raw sensor data.This buffer may be back to back databuffer based 91 * command read in the list. 92 * @constraints This can be called any number of times only after MAG3110_I2C_Initialize(). 93 * Application has to ensure that previous instances of these APIs have exited before invocation. 94 * @reeentrant No 95 * @return ::MAG3110_I2C_ReadData() returns the status . 96 */ 97 int32_t MAG3110_I2C_ReadData(mag3110_i2c_sensorhandle_t *pSensorHandle, 98 const registerreadlist_t *pReadList, 99 uint8_t *pBuffer); 100 101 /*! @brief The interface function to De Initialize sensor.. 102 * @details This function made sensor in a power safe state and de initialize its handle. 103 * @param[in] pSensorHandle handle to the sensor. 104 * @constraints This can be called only after MAG3110_I2C_Initialize() has been called. 105 * Application has to ensure that previous instances of these APIs have exited before invocation. 106 * @reeentrant No 107 * @return ::MAG3110_I2C_DeInit() returns the status. 108 */ 109 int32_t MAG3110_I2C_DeInit(mag3110_i2c_sensorhandle_t *pSensorHandle); 110 111 /*! 112 * @brief Calibrates the magnetometer reading by determining the current hard iron offset. 113 * @details This function must be periodically called during the program execution to constantly 114 * calibrate the magnetometer sensor. 115 * @param [in/out] xValue Magnetometer X-axis reading. 116 * @param [in/out] yValue Magnetometer Y-Axis reading. 117 * @param [in/out] zValue Magnetometer Z-Axis reading. 118 * @constraints This function should be called after each ODR on acquired data. 119 * @reeentrant No 120 * @return void 121 */ 122 void MAG3110_CalibrateHardIronOffset(int16_t* xValue, int16_t* yValue, int16_t* zValue); 123 124 #endif // MAG3110_FI_H_ 125
