Gyroscope

This chapter introduces the configuration and use of the gyroscope BMG160 and the gyroscope component of the BMI160 on the XDK via the gyroscope interface. It shows how to initialize and read the measured sensor data and provides an explanation for some specific presettings.

For more specific information about the BMG160 and the BMI160, please take a look at the corresponding datasheet.

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

Gyroscope 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.

fig1

Initializing the gyro sensor

Before we start with the implementation of the gyroscope (BMG160 or BMI160), 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_Gyroscope.h. Afterwards the function Gyroscope_init() is used to initialize the sensor with the correct sensor specific handler.

/* Interface for all sensors on the XDK */

#include "XdkSensorHandle.h"

Gyroscope_init(xdkGyroscope_BMG160_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 BMG160 Gyroscope */
extern Gyroscope_HandlePtr_T xdkGyroscope_BMG160_Handle;
/* Sensor Handler for the BMI160 Gyroscope */
extern Gyroscope_HandlePtr_T xdkGyroscope_BMI160_Handle;

Configuring the Presettings

This short overview gives an example about how to configure the gyroscope with presettings. It is of course possible to use the gyroscope without modifying the settings, too.

The functions Gyroscope_setBandwidth() and Gyroscope_setRange() set a specific bandwidth and sensor range for the gyroscope. Please keep in mind that before any presettings can be configured, the gyroscope needs to be initialized first.

Gyroscope_setBandwidth(xdkGyroscope_BMG160_Handle,GYROSCOPE_BMG160_BANDWIDTH_116HZ);

Gyroscope_setRange(xdkGyroscope_BMG160_Handle,GYROSCOPE_BMG160_RANGE_500s);

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

FunctionEffect
Gyroscope_setBand width()Configures the gyroscope with the given bandwidth enumeration.
Gyroscope_getBandwidth()Returns the configured bandwidth of the gyroscope in a passed reference variable.
Gyroscope_setRange()Configures the gyroscope with the given range enumeration.
Gyroscope_getRange()Returns the configured range of the gyroscope in a passed reference variable.
Gyroscope_setMode()Configures the gyroscope with the given power mode enumeration.
Gyroscope_getMode()Returns the configured power mode of the gyroscope in a passed reference variable.
Gyroscope_setSleepDuration()Configures the gyroscope with the given sleep duration.
Gyroscope_getSleepDuration()Returns the configured sleep duration of the gyroscope in a passed reference variable.

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

Reading sensor data

This section describes how to read data from the gyroscope. First a storage struct for every axis’ position data is declared. The data is then read by the Gyroscope_readXyzDegreeValue() function and stored in a passed reference of the storage struct.

Gyroscope_XyzData_T bmg160 = {INT32_C(0), INT32_C(0), INT32_C(0)};

Gyroscope_readXyzDegreeValue(xdkGyroscope_BMI160_Handle,&bmg160);

The data from the gyroscope 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 degree. Additionally the physical data is stored in 32 bit integers and therefore measured in milli degree. The other function provides the analog sensor data converted into its raw digital representation.

Gyroscope_readXyzDegreeValue(xdkGyroscope_BMG160_Handle,&bmg160);

Gyroscope_readXyzValue(xdkGyroscope_BMG160_Handle,&bmg160);

Full Code Example

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

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

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

#include "XdkAppInfo.h"
#undef BCDS_MODULE_ID  // [i] Module ID define before including Basics package
#define BCDS_MODULE_ID XDK_APP_MODULE_ID_APP_CONTROLLER

#include <stdio.h>
#include "BCDS_CmdProcessor.h"
#include "FreeRTOS.h"
#include "XdkSensorHandle.h"
#include "timers.h"

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

static CmdProcessor_T * AppCmdProcessor;
xTimerHandle gyroscopeHandle = NULL;

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

static void readGyroscope(xTimerHandle xTimer)
{
    (void) xTimer;

    Retcode_T returnValue = RETCODE_FAILURE;

    Gyroscope_XyzData_T bmg160 = {INT32_C(0), INT32_C(0), INT32_C(0)};

        memset(&bmg160, 0, sizeof(CalibratedGyro_DpsData_T));
        returnValue = Gyroscope_readXyzDegreeValue(xdkGyroscope_BMG160_Handle, &bmg160);

        if (RETCODE_OK == returnValue){
            printf("BMG160 Gyroscope Data: %10d mDeg[X] %10d mDeg[Y] %10d mDeg[Z]\n\r",
                (int) bmg160.xAxisData, (int) bmg160.yAxisData, (int) bmg160.zAxisData);
        }
}

static void initGyroscope(void)
{
    Retcode_T returnValue = RETCODE_FAILURE;
    Retcode_T returnBandwidthValue = RETCODE_FAILURE;
    Retcode_T returnRangeValue = RETCODE_FAILURE;

    returnValue = Gyroscope_init(xdkGyroscope_BMG160_Handle);

    if ( RETCODE_OK != returnValue) {
        printf("BMG160 Gyroscope initialization failed\n\r");
    }
    returnBandwidthValue = Gyroscope_setBandwidth(xdkGyroscope_BMG160_Handle, GYROSCOPE_BMG160_BANDWIDTH_116HZ);
    if (RETCODE_OK != returnBandwidthValue) {
        printf("Configuring bandwidth failed \n\r");
    }
    returnRangeValue = Gyroscope_setRange(xdkGyroscope_BMG160_Handle, GYROSCOPE_BMG160_RANGE_500s);
    if (RETCODE_OK != returnRangeValue) {
        printf("Configuring range 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(gyroscopeHandle,timerBlockTime);
}

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

    Retcode_T retcode = RETCODE_OK;
    uint32_t timerDelay = UINT32_C(1000);
    uint32_t timerAutoReloadOn = UINT32_C(1);

    // Setup of the necessary module
    initGyroscope();

    // Creation and start of the timer
    gyroscopeHandle = xTimerCreate((const char *) "readGyroscope", timerDelay, timerAutoReloadOn, NULL, readGyroscope);
    retcode = CmdProcessor_Enqueue(AppCmdProcessor, AppControllerEnable, NULL, UINT32_C(0));

    if (RETCODE_OK != retcode)
    {
        printf("AppControllerSetup : Failed \r\n");
        Retcode_RaiseError(retcode);
        assert(0);
    }
}

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);
    }
}

Appendix

XDK Console Output example

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

Image