Introduction

Smablo GridEye Shield is a 8x8 pixel infrared array sensor that offers digital output for thermal presence, direction and temperature values. Grideye Shield will return an array of 64 points of thermal readings.

Applications

Smablo Grid Eye Shield can be used to detect thermal activity but also define the object number and type:

• Security - built advanced security system that detect different types of object and movements
• Light control – built intelligent lights that detect object and react by turning the lights on
• Door control – built automatic door that will open when specific object will be near
• People counting – keep track of the people on specific area
• Etc.

Getting started

To get started with Smablo GPS Shield you will need:

• Smablo Development Board
• Smablo Grideye Shield
• Smablo CPU
• Smablo SDK
• Visual Studio Code

Take Smablo Development Board from your Smablo Development Kit and place CPU and Smablo Grideye Shield on the described connectors like in the pictures and video below:

{.force-inline} {.force-inline} {.force-inline}

When you’ve done connecting Shields you can connect Smablo Development board to your computer with USB cable.

Example programs

Smablo prepared demo project to show you how to use Smablo GridEye Sensor. To see how to use run them open Visual Studio Code and Click file->Open folder and from your libsmablo/examples directory choose one of them just like it was shown on the videos below.

gps

To compile and program the Shield press F5 button and hit the run button on the top menu of Visual Studio Code. . Example will measure 8x8 temperature grid every 1000 ms and show it on screen. To see the output of the grideye_raw_data example open RTT Viewer.

Minimal code

Minimal example code is the same code that you can find in the Example code chapter and will show you how to use Smablo Grideye Shield. The code below will measure the 8x8 thermal grid and then print thermal data on the screen every 100 ms.

//1
#include "drv_amg8833.h"
#include "sm_timer.h"
#include "nrf_log.h"
#include "nrf_assert.h"

//2
///amg8833 driver instance
static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

//3
SM_TIMER_DEF(grideye_polling_timer);

static void grideye_polling_timer_handler(void* p_ctx)
{
    ASSERT(p_ctx!=NULL);
//6
    //dereference the pointer 
    amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;
//7
    //get the data
    amg8833_get_data_blocking(p_instance);
//8
    //get pixel temperatures
    amg8833_converted_pixel_data_t pixel_data;
    amg8833_get_pixel_temperature(p_instance, &pixel_data);
//9
    //print pixel temperatures
    NRF_LOG_RAW_DEBUG("Pixel data Celsius degrees :\r\n");
    for (uint8_t i=0; i< AMG8833_PIXEL_NO; i++)
    {
        if (i>0 && i%8==0) NRF_LOG_RAW_DEBUG("\r\n");
        NRF_LOG_RAW_DEBUG(NRF_LOG_FLOAT_MARKER"\t",NRF_LOG_FLOAT(pixel_data.pixels[i]));
    }
    NRF_LOG_RAW_DEBUG("\r\n\r\n");
}

void grideye_raw_demo(void)
{   
    //4
    //initialize GridEye
    amg8833_init(&grideye_instance);

    //write configuration to the device
    amg8833_commit_blocking(&grideye_instance);

    //5
    //create polling timer
    ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
    APP_ERROR_CHECK(err_code);

    //start polling timer
    err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(100), &grideye_instance);
    APP_ERROR_CHECK(err_code);

}

In point 1 we need to include all the libraries that we will need to work with:

• drv_amg8833.h driver is the main Grideye Shield driver holding all the functions to configure and use the shield.
• sm_timer.h that let us use timers in our project.
• #include "nrf_log.h" that help us debug the programs and let us show sentencies and data on screen with use of RTT Viewer.

In point 2 we are creating the instance of the Smablo Grideye Shield with static amg8833_instance_t grideye_instance. Instance will hold all of the current registers values and configuration of the module. SM_GRIDEYE_INSTANCE_CREATE macro holds all the default values of the shield and it is recomended to use it.

In point 3 we are creating the definition of the timer SM_TIMER_DEF(grideye_polling_timer);, more information about timers are here .

In point 4 we are initializing the Grideye Shield with the grideye_instance instance. We need to do it only once at the begining of the program. Then sending this configuration using amg8833_commit_blocking() function in blocking manner. If the changes would be made to the instance they would take place after this function execute.

In point 5 we are creating and starting grideye_polling_timer timer from its definition and setting it to work in repeating mode to execute the grideye_polling_timer_handler function every 100ms. More information about timers can be found here.

In point 6 we need to dereference the pointer from void type back to amg8833_instance_t instance type for further use.

In point 7 we getting the new data from the shield with use of amg8833_get_data_blocking() function. After this function executes the raw pixel data are stored in the instance and need to be decoded.

In point 8 we are converting the raw pixel data to thermal data array in Centigrade using amg8833_get_pixel_temperature() function. We will store the converted data in the amg8833_converted_pixel_data_t type structure in our case called pixel_data.

In point 9 we are printing the 8x8 temperature grid to the screen using NRF_LOG macros.

drv_amg883.h driver reference

To use this driver you need to include it to your project with #include statement. It is also important that before using any of the driver functions create instance of the module:

///amg8833 driver instance
static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

The example of usage if instance was showan in Minimal code snippet.

amg8833_init

Prototype:

void amg8833_init(amg8833_instance_t* const p_instance);

Function is used to initialize Smablo GPS Shiled, function set the module in the default settings which instance. Function takes 1 parameter:

• p_instance which is pointer to instance type amg8833_instance_t that you need to create ealier. When creating the instance it is convienient and recommended to use SM_GRIDEYE_INSTANCE_CREATE macro that holds all the defaul module values.

The example use of the function was shown in Minimal code snippet.

amg8833_reset

Prototype:

void amg8833_reset(amg8833_instance_t* const p_instance, const amg8833_reg_reset_state_t reset_flag);

Function send reset command to the Smablo GPS Shield in blockin manner. Function takes 2 parameters:

• p_instance to work on

• reset_flag which is reset type that we want to sent to the Shield. There are 2 types of reset that we can send to the shield and they are all avaiable in amg8833_reg_reset_state_t after pressing F12 button when on type.

  ///Possible values for ::amg8833_reg_reset_t
  typedef enum
  {
      AMG8833_RESET_FLAG_ONLY=0x30,   ///< Flag reset
      AMG8833_RESET_INITIAL=0x3F      ///< Initial reset
  
  } amg8833_reg_reset_state_t;

  • AMG8833_RESET_FLAG_ONLY This reset clear all the status register(temperature output overflow and interrupy outbreak), and all the interrupt table (Register for reading only to indicate pixels which temperature outputs are over the threshold.)
  • AMG8833_RESET_INITIAL This reset do same things as AMG8833_RESET_FLAG_ONLY and read nonvolatile memorys which storage adujustment value of sensor.

The code snippet below shows how to use amg8833_reset(); and will perform shield initial reset to the default register values.

#include "drv_amg8833.h"

static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

void grideye_raw_demo(void)
{   
    //initialize GridEye
    amg8833_init(&grideye_instance);

    //perform initial reset that will set the shield to the default values
    amg8833_reset(&grideye_instance, AMG8833_RESET_INITIAL);
}

amg8833_commit_blocking

Prototype:

void amg8833_commit_blocking(amg8833_instance_t* const p_instance);

Function is used for sending new instance configuration to shield. After this function executes new configurations will take place in working of the module. Example use of this function can be found Minimal code chapter.

amg8833_set_average_state_blocking

Prototype:

void amg8833_set_average_state_blocking(amg8833_instance_t* const p_instance, const amg8833_avg_state_t avg_state);

Function enables or disables the moving average feature in blocking manners.

• p_instance instance to work on

• avg_state enable or disable running average of pixel data

  ///Possible states for running average function
  typedef enum
  {
      AMG8833_AVERAGING_DISABLED=0,   ///< Running average of pixel data disabled
      AMG8833_AVERAGING_ENABLED=0x20  ///< Running average of pixel data enabled
  
  } amg8833_avg_state_t;

  Moving average helps to smooth out short-term fluctuations and highlight longer-term trends or cycles. By default moving average is disabled.

  #include "drv_amg8833.h"
  #include "sm_timer.h"
  #include "nrf_log.h"
  #include "nrf_assert.h"
  
  ///amg8833 driver instance
  static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;
  
  //create the definition of the grideye_polling_timer timer
  SM_TIMER_DEF(grideye_polling_timer);
  
  static void grideye_polling_timer_handler(void* p_ctx)
  {
      ASSERT(p_ctx!=NULL);
  
      //driver instance pointer is passed as parameter to sm_timer_start()
      amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;
  
      //get the data
      amg8833_get_data_blocking(p_instance);
  
      //get pixel temperatures
      amg8833_converted_pixel_data_t pixel_data;
      amg8833_get_pixel_temperature(p_instance, &pixel_data);
  
      //print pixel temperatures
      NRF_LOG_RAW_DEBUG("Pixel data Celsius degrees :\r\n");
      for (uint8_t i=0; i< AMG8833_PIXEL_NO; i++)
      {
          if (i>0 && i%8==0) NRF_LOG_RAW_DEBUG("\r\n");
          NRF_LOG_RAW_DEBUG(NRF_LOG_FLOAT_MARKER"\t",NRF_LOG_FLOAT(pixel_data.pixels[i]));
      }
      NRF_LOG_RAW_DEBUG("\r\n\r\n");
  
  }
  
  void grideye_raw_demo(void)
  {   
      //initialize GridEye
      amg8833_init(&grideye_instance);
  
      //Enable the moving average 
      amg8833_set_average_state_blocking(&grideye_instance, AMG8833_AVERAGING_ENABLED);
  
      //create polling timer
      ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
      APP_ERROR_CHECK(err_code);
  
      //start polling timer
      err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(100), &grideye_instance);
      APP_ERROR_CHECK(err_code);
  
  }

  Function will print 8x8 temperature grid as in the Minimal code only this time the data will be proccesed with moving average feature which make the output data smoother.

amg8833_configure_power_state

Prototype:

void amg8833_configure_power_state(amg8833_instance_t* const p_instance, const amg8833_reg_pctrl_state_t power_state);

Function is used to configure Smablo Grideye Shield power operating mode of device. To changes take place we need to use amg8833_commit_blocking function afterwards.

• p_instance instance that we want to configure.

• power_state type amg8833_reg_pctrl_state_t from we can choose four states of power the shields:

  ///Possible values for ::amg8833_reg_pctrl_t
  typedef enum
  {
      AMG8833_MODE_NORMAL=0,          ///< Normal mode
      AMG8833_MODE_SLEEP=0x10,        ///< Sleep mode
      AMG8833_MODE_STANDBY_60S=0x20,  ///< Stand-by mode (60sec intermittence)
      AMG8833_MODE_STANDBY_10S=0x21   ///< Stand-by mode (10sec intermittence)
  
  } amg8833_reg_pctrl_state_t;

  • AMG8833_MODE_NORMAL is a normal operating mode no power is saved in this mode but the Shield is getting the data in a rate specified in amg8833_configure_fps function. The current consumtion in normal mode is around 4.5 mA
  • AMG8833_MODE_SLEEP in this mode the configuration of the shield cannot be changed. To change the parameters of the module you need to set it back to the normal mode. The current consumption is the lowest around 0.2 mA
  • AMG8833_MODE_STANDBY_60S in this mode that measurements are performed every 60s. The current consumption in this mode is around 0.8mA
  • AMG8833_MODE_STANDBY_10S in this mode that measurements are performed every 10s. The current consumption in this mode is around 0.8mA

  The code snippet below is setting the Smablo Grideye Shield in to the AMG8833_MODE_STANDBY_10S. To show it how it works the timer was set to pull the new data from the shield every 1s and every 10 s you should see that the data was changed. To see printed data open RTT Viewer

  #include "drv_amg8833.h"
  #include "sm_timer.h"
  #include "nrf_log.h"
  #include "nrf_assert.h"
  
  ///amg8833 driver instance
  static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;
  
  SM_TIMER_DEF(grideye_polling_timer);
  
  static void grideye_polling_timer_handler(void* p_ctx)
  {
      ASSERT(p_ctx!=NULL);
  
      //driver instance pointer is passed as parameter to sm_timer_start()
      amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;
  
      //get the data
      amg8833_get_data_blocking(p_instance);
  
      //get pixel temperatures
      amg8833_converted_pixel_data_t pixel_data;
      amg8833_get_pixel_temperature(p_instance, &pixel_data);
  
      //print pixel temperatures
      NRF_LOG_RAW_DEBUG("Pixel data Celsius degrees :\r\n");
      for (uint8_t i=0; i< AMG8833_PIXEL_NO; i++)
      {
          if (i>0 && i%8==0) NRF_LOG_RAW_DEBUG("\r\n");
          NRF_LOG_RAW_DEBUG(NRF_LOG_FLOAT_MARKER"\t",NRF_LOG_FLOAT(pixel_data.pixels[i]));
      }
      NRF_LOG_RAW_DEBUG("\r\n\r\n");
  
  }
  
  void grideye_raw_demo(void)
  {   
      //initialize GridEye
      amg8833_init(&grideye_instance);
  
      //configure shields power mode 
      amg8833_configure_power_state(&grideye_instance, AMG8833_MODE_STANDBY_10S);
  
      //send the instance configuration to the shield 
      amg8833_commit_blocking(&grideye_instance);
  
      //create polling timer
      ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
      APP_ERROR_CHECK(err_code);
  
      //start polling timer
      err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(1000), &grideye_instance);
      APP_ERROR_CHECK(err_code);
  
  }
  

amg8833_configure_fps

Prototype:

void amg8833_configure_fps(amg8833_instance_t* const p_instance, const amg8833_reg_fps_state_t fps);

Function is used for for configuration of the frames per second of the 8x8 grid of thermal data from the shield. Function takes two parameters:

• p_instance the instance to configure to

• fps frames per second configuration that we can choose from amg8833_reg_fps_state_t:

  ///Possible values for amg8833_reg_fps_t::FPS
  typedef enum
  {
      AMG8833_FPS_10=0,   ///< 10 FPS (default)
      AMG8833_FPS_1       ///<  1 FPS
  
  } amg8833_reg_fps_state_t;

  • AMG8833_FPS_10 is the default Grideye data rate and equals 10 Hz. This means that the new data of thermal 8x8 grid will be avaiable every 100 ms.
  • AMG8833_FPS_1 is slower data rate and equals 1 Hz. This means that the new data of thermal 8x8 grid will be avaiable every 1000 ms.

  The code snippet below is very similar to Minimal code but in this example the FPS rate was changed to 1 Hz which means that the new thermal data will be avaiable every 1s.

  #include "drv_amg8833.h"
  #include "sm_timer.h"
  #include "nrf_log.h"
  #include "nrf_assert.h"
  
  ///amg8833 driver instance
  static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;
  
  SM_TIMER_DEF(grideye_polling_timer);
  
  static void grideye_polling_timer_handler(void* p_ctx)
  {
      ASSERT(p_ctx!=NULL);
  
      //driver instance pointer is passed as parameter to sm_timer_start()
      amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;
  
      //get the data
      amg8833_get_data_blocking(p_instance);
  
      //get pixel temperatures
      amg8833_converted_pixel_data_t pixel_data;
      amg8833_get_pixel_temperature(p_instance, &pixel_data);
  
      //print pixel temperatures
      NRF_LOG_RAW_DEBUG("Pixel data Celsius degrees :\r\n");
      for (uint8_t i=0; i< AMG8833_PIXEL_NO; i++)
      {
          if (i>0 && i%8==0) NRF_LOG_RAW_DEBUG("\r\n");
          NRF_LOG_RAW_DEBUG(NRF_LOG_FLOAT_MARKER"\t",NRF_LOG_FLOAT(pixel_data.pixels[i]));
      }
      NRF_LOG_RAW_DEBUG("\r\n\r\n");
  
  }
  
  void grideye_raw_demo(void)
  {   
      //initialize GridEye
      amg8833_init(&grideye_instance);
  
      //configure instance to 1 Hz FPS rate
      amg8833_configure_fps(&grideye_instance, AMG8833_FPS_1);
  
      //send the instance configuration to the shield.
      amg8833_commit_blocking(&grideye_instance);
  
      //create polling timer
      ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
      APP_ERROR_CHECK(err_code);
  
      //start polling timer
      err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(1000), &grideye_instance);
      APP_ERROR_CHECK(err_code);
  
  }

  To show it how it works the timer was set to pull the new data from the shield every 100ms and every 1s you should see that the data was changed. To see printed data open RTT Viewer .

  The example of usage if instance was shown in Minimal code snippet.

amg8833_get_data_blocking

Prototype:

void amg8833_get_data_blocking(amg8833_instance_t* const p_instance);

Function is used for getting the new data from the Smablo Grideye Shield in blocking manner. After execution instance is updated with 8x8 grid of thermal data.

The example of usage if instance was shown in Minimal code snippet.

amg8833_get_thermistor_temperature_count

Prototype:

int16_t amg8833_get_thermistor_temperature_count(const amg8833_generic_temperature_t* const p_temp);

Function is used to convert 12 bit temperature representation to signed 16 bit integer in counts. Function take one parameter which is p_temp pointer to the amg8833_generic_temperature_t type structure.

The code snippet below shows how to use the function. The amg8833_generic_temperature_t type can be also found inthe Grideye instance which hold thermistor value. Using the function convert the value and then print it on the screen using the timer every 1s.

#include "drv_amg8833.h"
#include "sm_timer.h"
#include "nrf_log.h"
#include "nrf_assert.h"

///amg8833 driver instance
static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

//timer definition
SM_TIMER_DEF(grideye_polling_timer);

static void grideye_polling_timer_handler(void* p_ctx)
{
    ASSERT(p_ctx!=NULL);

    //driver instance pointer is passed as parameter to sm_timer_start()
    amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;

    //get the data
    amg8833_get_data_blocking(p_instance);

    //convert thermistor temperature to counts  
    int16_t therm_temp_count =  amg8833_get_thermistor_temperature_count(&p_instance->regs.thermistor.value);

    //print counts on the screen
    NRF_LOG_RAW_DEBUG("thermistor value in counts %d\r\n", therm_temp_count);
}

void grideye_raw_demo(void)
{   
    //initialize GridEye
    amg8833_init(&grideye_instance);

    //create polling timer
    ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
    APP_ERROR_CHECK(err_code);

    //start polling timer
    err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(1000), &grideye_instance);
    APP_ERROR_CHECK(err_code);

}

amg8833_get_pixel_temperature_count

Prototype:

int16_t amg8833_get_pixel_temperature_count(const amg8833_generic_temperature_t* const p_temp);

Function is used to convert the pixel temperature values in C to the counts values. Function takes one parameters which is pointer to the amg8833_generic_temperature_t structure.

Function below show how to use the function. Function is printing the pixel temperature values like in Minimal code snippet only in counts. To see the output open RTT Viewer

#include "drv_amg8833.h"
#include "sm_timer.h"
#include "nrf_log.h"
#include "nrf_assert.h"

///amg8833 driver instance
static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

//timer definition
SM_TIMER_DEF(grideye_polling_timer);

static void grideye_polling_timer_handler(void* p_ctx)
{
    ASSERT(p_ctx!=NULL);

    //driver instance pointer is passed as parameter to sm_timer_start()
    amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;

    //get the data
    amg8833_get_data_blocking(p_instance);

    //print data 
    int16_t pixel_temp_count;
    for(uint8_t i =0;i<AMG8833_PIXEL_NO;i++)
    {   
        if (i>0 && i%8==0) NRF_LOG_RAW_DEBUG("\r\n");
        pixel_temp_count = amg8833_get_pixel_temperature_count(&p_instance->regs.pixel_data.pixels[i]);
        NRF_LOG_RAW_DEBUG("%d \t",pixel_temp_count );
    }
    NRF_LOG_RAW_DEBUG("\r\n\r\n");  

}

void grideye_raw_demo(void)
{   
    //initialize GridEye
    amg8833_init(&grideye_instance);

    //create polling timer
    ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
    APP_ERROR_CHECK(err_code);

    //start polling timer
    err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(1000), &grideye_instance);
    APP_ERROR_CHECK(err_code);

}

amg8833_get_pixel_temperature

Prototype:

void amg8833_get_pixel_temperature(const amg8833_instance_t* const p_instance, amg8833_converted_pixel_data_t* const p_converted);

Function convert raw pixel data to array of temperatures in Centigrade. The use of function was shown in Minimal code snippet.

amg8833_get_thermistor_temperature

Prototype:

float amg8833_get_thermistor_temperature(amg8833_instance_t* const p_instance);

Function convert raw thermistor data to float value in Centigrade. Function takes only one parameter which is pointer to the Grideye instance.

Code snippet below show how to use the function. Program using timer prints the value of the thermistor in Centigrade every 1s. To see the output open RTT Viewer

#include "drv_amg8833.h"
#include "sm_timer.h"
#include "nrf_log.h"
#include "nrf_assert.h"

///amg8833 driver instance
static amg8833_instance_t grideye_instance=SM_GRIDEYE_INSTANCE_CREATE;

//timer definition 
SM_TIMER_DEF(grideye_polling_timer);

static void grideye_polling_timer_handler(void* p_ctx)
{
    ASSERT(p_ctx!=NULL);

    //driver instance pointer is passed as parameter to sm_timer_start()
    amg8833_instance_t* const p_instance=(amg8833_instance_t*)p_ctx;

    //get the data
    amg8833_get_data_blocking(p_instance);

    float thermistor_temp = amg8833_get_thermistor_temperature( p_instance);
    NRF_LOG_RAW_DEBUG("Thermistor temperature in C "NRF_LOG_FLOAT_MARKER"\t\r\n",NRF_LOG_FLOAT(thermistor_temp));

}

void grideye_raw_demo(void)
{   
    //initialize GridEye
    amg8833_init(&grideye_instance);

    //create polling timer
    ret_code_t err_code=sm_timer_create(&grideye_polling_timer, SM_TIMER_MODE_REPEATED, grideye_polling_timer_handler);
    APP_ERROR_CHECK(err_code);

    //start polling timer
    err_code=sm_timer_start(grideye_polling_timer, SM_TIMER_TICKS(1000), &grideye_instance);
    APP_ERROR_CHECK(err_code);

}