Magnetometer

This chapter introduces the configuration and use of the magnetometer BMM150 also known as the geomagnetic sensor BMM150 on the XDK via the magnetometer interface. It shows not only how to initialize and read the sensor data, but also provides an explanation of some presetting parameters.

For more specific information about the BMM150, please take a look at the corresponding datasheet.

  1. Magnetometer API Overview
  2. Initializing the magnetic sensor
  3. Configuring the Presettings
  4. Reading magnetic data
  5. Full Code Example
  6. Appendix
    1. XDK Console Output example

Magnetometer API Overview

It is generally recommended to develop an application based on the highest API level the XDK framework supports, although it is possible to access deeper API levels if this isn’t enough for the distinct purpose.

Image

Initializing the magnetic sensor

Before we start with the implementation of the magnetometer, the sensor handling header file has to be included, which is XdkSensorHandle.h. This header file provides the interfaces for every sensor type, in this case, BCDS_Magnetometer.h. Afterwards the function Magnetometer_init() is used to initialize the sensor with the correct sensor specific handler.

/* Interface for all sensors on the XDK */

#include "XdkSensorHandle.h"

Magnetometer_init(xdkMagnetometer_BMM150_Handle);

The particular sensor specific handler can be found within XdkSensorHandle.h. It contains the sensor specific handler for every sensor type on the XDK.

/************************************************************
*   XdkSensorHandle.h
************************************************************/

/* Sensor Handler for the BMM150 Sensor */
extern Magnetometer_HandlePtr_T xdkMagnetometer_BMM150_Handle;

Configuring the Presettings

This short overview provides an example on how to configure the magnetometer with presettings. It is of course possible to use the magnetometer without modifying the settings, too.

The functions Magnetometer_setDataRate() and Magnetometer_setPresetMode() set a specific datarate and sampling mode for the magnetometer. Please keep in mind that before any presettings can be configured, the magnetometer needs to be initialized first.

Magnetometer_setDataRate(xdkMagnetometer_BMM150_Handle,MAGNETOMETER_BMM150_DATARATE_10HZ);

Magnetometer_setPresetMode(xdkMagnetometer_BMM150_Handle,MAGNETOMETER_BMM150_PRESETMODE_REGULAR);

The table below contains some of the configuration functions of the magnetometer which are available in the interface BCDS_Magnetometer.h.

FunctionEffect
Magnetometer_setDataRate()Configures the magnetometer with the given data rate enumeration.
Magnetometer_getDataRate()Returns the configured data rate of the magnetometer in a passed reference variable.
Magnetometer_setPresetMode()Configures the magnetometer with the given preset mode enumeration.
Magnetometer_getPresetMode()Returns the configured preset mode of the magnetometer in a passed reference variable.
Magnetometer_setPowerMode()Configures the magnetometer with the given power mode enumeration.
Magnetometer_getPowerMode()Returns the configured power mode of the magnetometer in a passed reference variable.

A more detailed explanation can be found in the mentioned interface BCDS_Magnetometer.h.

Reading magnetic data

This section describes how to read measured data from the magnetometer. A storage struct for every axis’ magnetic field data is declared. The data is then read by the Magnetometer_readXyzTeslaData() function and then stored in a passed reference of the storage struct.

Magnetometer_XyzData_T bmm150 = {INT32_C(0), INT32_C(0), INT32_C(0),INT32_C(0)};

Magnetometer_readXyzTeslaData(xdkMagnetometer_BMM150_Handle,&bmm150);

Measurement data from the magnetometer can be received using two different function calls. These function calls provide data which differs in the unit in which it is displayed. One of the two functions provides data which is measured in its physical unit tesla. Additionally the physical data is stored in 32 bit integers and therefore measured in milli tesla. The other function provides the analog sensor data converted into its raw digital representation.

Magnetometer_readXyzTeslaValue(xdkMagnetometer_BMM150_Handle,&bmm150);

Magnetometer_readXyzLsbValue(xdkMagnetometer_BMM150_Handle,&bmm150);

Full Code Example

Note: The full code example is intended for XDK-Workbench versions 3.4.0 and higher.

/*----------------------------------------------------------------------------*/

/* --------------------------------------------------------------------------- |
 * INCLUDES & DEFINES ******************************************************** |
 * -------------------------------------------------------------------------- */

/* own header files */
#include "XdkAppInfo.h"
#undef BCDS_MODULE_ID  /* Module ID define before including Basics package*/
#define BCDS_MODULE_ID XDK_APP_MODULE_ID_APP_CONTROLLER

/* system header files */
#include <stdio.h>

/* additional interface header files */
#include "FreeRTOS.h"
#include "BCDS_CmdProcessor.h"
#include "BCDS_Assert.h"

#include "XdkSensorHandle.h"

#include "task.h"
#include "timers.h"

/* --------------------------------------------------------------------------- |
 * HANDLES ******************************************************************* |
 * -------------------------------------------------------------------------- */

static CmdProcessor_T * AppCmdProcessor;
xTimerHandle magnetometerHandle = NULL;

/* --------------------------------------------------------------------------- |
 * EXECUTING FUNCTIONS ******************************************************* |
 * -------------------------------------------------------------------------- */

static void readMagnetometer(xTimerHandle xTimer){

    (void) xTimer;
    Retcode_T returnValue = RETCODE_FAILURE;

    /* read and print BMM150 magnetometer data */

    Magnetometer_XyzData_T bmm150 = {INT32_C(0), INT32_C(0), INT32_C(0), INT32_C(0)};

    returnValue = Magnetometer_readXyzTeslaData(xdkMagnetometer_BMM150_Handle, &bmm150);

    if (RETCODE_OK == returnValue) {
    printf("BMM150 Magnetic Data: x =%ld mT y =%ld mT z =%ld mT \n\r",
          (long int) bmm150.xAxisData, (long int) bmm150.yAxisData, (long int) bmm150.zAxisData);
    }
}

static void initMagnetometer(void){

    Retcode_T returnValue = RETCODE_FAILURE;
    Retcode_T returnDataRateValue = RETCODE_FAILURE;
    Retcode_T returnPresetModeValue = RETCODE_FAILURE;

    /* initialize magnetometer */

    returnValue = Magnetometer_init(xdkMagnetometer_BMM150_Handle);

    if(RETCODE_OK != returnValue){
        printf("BMM150 Magnetometer initialization failed \n\r");
    }

    returnDataRateValue = Magnetometer_setDataRate(xdkMagnetometer_BMM150_Handle,
            MAGNETOMETER_BMM150_DATARATE_10HZ);
    if (RETCODE_OK != returnDataRateValue) {
    printf("Configuring data rate failed \n\r");
    }
    returnPresetModeValue = Magnetometer_setPresetMode(xdkMagnetometer_BMM150_Handle,
            MAGNETOMETER_BMM150_PRESETMODE_REGULAR);
    if (RETCODE_OK != returnPresetModeValue) {
    printf("Configuring preset mode failed \n\r");
    }
}

/* --------------------------------------------------------------------------- |
 * BOOTING- AND SETUP FUNCTIONS ********************************************** |
 * -------------------------------------------------------------------------- */

static void AppControllerEnable(void * param1, uint32_t param2)
{
    BCDS_UNUSED(param1);
    BCDS_UNUSED(param2);

    uint32_t timerBlockTime = UINT32_MAX;

    xTimerStart(magnetometerHandle,timerBlockTime);
}

static void AppControllerSetup(void * param1, uint32_t param2)
{
    BCDS_UNUSED(param1);
    BCDS_UNUSED(param2);
    Retcode_T retcode = RETCODE_OK;

    uint32_t oneSecondDelay = UINT32_C(1000);
    uint32_t timerAutoReloadOn = UINT32_C(1);

    initMagnetometer();

    magnetometerHandle = xTimerCreate((const char *) "readMagnetometer", oneSecondDelay,timerAutoReloadOn, NULL, readMagnetometer);

    retcode = CmdProcessor_Enqueue(AppCmdProcessor, AppControllerEnable, NULL, UINT32_C(0));
    if (RETCODE_OK != retcode)
    {
        printf("AppControllerSetup : Failed \r\n");
        Retcode_RaiseError(retcode);
        assert(0); /* To provide LED indication for the user */
    }
}

void AppController_Init(void * cmdProcessorHandle, uint32_t param2)
{
    BCDS_UNUSED(param2);

    Retcode_T retcode = RETCODE_OK;

    if (cmdProcessorHandle == NULL)
    {
        printf("AppController_Init : Command processor handle is NULL \r\n");
        retcode = RETCODE(RETCODE_SEVERITY_ERROR, RETCODE_NULL_POINTER);
    }
    else
    {
        AppCmdProcessor = (CmdProcessor_T *) cmdProcessorHandle;
        retcode = CmdProcessor_Enqueue(AppCmdProcessor, AppControllerSetup, NULL, UINT32_C(0));
    }

    if (RETCODE_OK != retcode)
    {
        Retcode_RaiseError(retcode);
        assert(0); /* To provide LED indication for the user */
    }
}
/*----------------------------------------------------------------------------*/

Appendix

XDK Console Output example

The following console log is an example output of the code that has been implemented in the Sensors Magnetometer example guide:

Image