Ambient Light Sensor #

This chapter introduces how to configure and use the ambient light sensor MAX44009 on the XDK via the light sensor interface. It provides not only an example on how to initialize and read the sensor data, but also an explanation of some specific presettings.

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

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

Light Sensor 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.

Initializing the ambient light sensor #

Before we start with the implementation of the ambient light sensor, 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_LightSensor.h. Afterwards the function LightSensor_init() is used to initialize the sensor with the correct sensor specific handler.

/* Interface for all sensors on the XDK */

#include "XdkSensorHandle.h"

LightSensor_init(xdkLightSensor_MAX44009_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 MAX44009 Sensor */
extern LightSensor_HandlePtr_T xdkLightSensor_MAX44009_Handle;

Configuring the Presettings #

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

The functions LightSensor_setBrightness() and LightSensor_setIntegrationTime() set a specific brightness and integration time for the light sensor. Please keep in mind that before any presettings can be configured, the light sensor needs to be initialized first.

LightSensor_setBrightness(xdkLightSensor_MAX44009_Handle,LIGHTSENSOR_NORMAL_BRIGHTNESS);

LightSensor_setIntegrationTime(xdkLightSensor_MAX44009_Handle,LIGHTSENSOR_200MS);

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

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

Reading sensor data #

This section describes how to read measured data from the ambient light sensor.

First, a storage variable for ambient light data is declared. The data is then read by the LightSensor_readLuxData() function and then stored in the ambient light data variable.

uint32_t max44009 = INT32_C(0);

LightSensor_readLuxData(xdkLightSensor_MAX44009_Handle, &max44009);

Measurement data from the ambient light sensor 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 lux. Additionally the physical data is stored in 32 bit integers and therefore measured in milli lux. The other function provides the digital converted analog sensor data in bytes.

LightSensor_readLuxData(xdkLightSensor_MAX44009_Handle,&max44009);

LightSensor_readRawData(xdkLightSensor_MAX44009_Handle,&max44009);

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 lightSensorHandle  = NULL;

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

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

    Retcode_T returnValue = RETCODE_FAILURE;
    uint32_t max44009 = UINT32_C(0);

        returnValue = LightSensor_readLuxData(xdkLightSensor_MAX44009_Handle, &max44009);

        if (RETCODE_OK == returnValue){
            printf("Light sensor data obtained in milli lux :%d \n\r",(unsigned int) max44009);
        }
}

static void initLightSensor(void)
{
    Retcode_T returnValue = RETCODE_FAILURE;
    Retcode_T returnBrightnessValue = RETCODE_FAILURE;
    Retcode_T returnIntegrationTimeValue = RETCODE_FAILURE;

    returnValue = LightSensor_init(xdkLightSensor_MAX44009_Handle);

    if ( RETCODE_OK != returnValue) {
        printf("MAX44009 Light Sensor initialization failed\n\r");
    }
    returnBrightnessValue = LightSensor_setBrightness(xdkLightSensor_MAX44009_Handle,LIGHTSENSOR_NORMAL_BRIGHTNESS);
    if (RETCODE_OK != returnBrightnessValue) {
        printf("Configuring brightness failed \n\r");
    }
    returnIntegrationTimeValue = LightSensor_setIntegrationTime(xdkLightSensor_MAX44009_Handle,LIGHTSENSOR_200MS);
    if (RETCODE_OK != returnIntegrationTimeValue) {
        printf("Configuring integration time 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(lightSensorHandle,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
    initLightSensor();

    // Creation and start of the timer
    lightSensorHandle = xTimerCreate((const char *) "readAmbientLight", timerDelay, timerAutoReloadOn, NULL, readLightSensor);
    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 Ambient Light example guide: