Created by Jonathan Richardson, last modified on Aug 07, 2013
This Panasonic Grid Eye library is a C code library that allows Atmel boards using the Atmel Software Framework (ASF) to communicate with single or multiple Grid Eye modules. With the inclusion of this library, the working project will be able to access raw Grid Eye data including pixel data, temperature, interrupts and frame rate, alongside secondary functions to visualize the data.
To utilize this library, download grideye_library.zip.zip (2.8 KB) . Include the library into your AtmelStudio 6 project and include GridEye.h. The Grid Eye must be connected to the microcontroller via an I2C bus.
This article assumes you have a basic working knowledge of AtmelStudio 6 and ASF.
Library Overview
Direct Access
These functions send and read data from the Grid Eye.
uint8_t ge_init (GridEye *ge, Twim *twim, uint8_t grideye_address);
bool ge_setFPS (GridEye *ge, bool fps_set_10);
bool ge_readAverage (GridEye *ge);
bool ge_initialReset (GridEye *ge);
bool ge_setInterrupt (GridEye *ge, bool absolute, uint16_t upper, uint16_t lower, uint16_t hysteresis);
bool ge_readInterruptFlag (GridEye *ge, bool clearFlag);
bool ge_clearInterruptFlag (GridEye *ge);
uint8_t ge_readFPS (GridEye *ge);
bool ge_readTemp (GridEye *ge);
Image Manipulation
These functions provide basic image operations.
void geimage_copy (GridEyeImage *from, GridEyeImage *to);
void geimage_sum (GridEyeImage *from, GridEyeImage *to);
void geimage_subtract (GridEyeImage *source, GridEyeImage *minus);
void geimage_abs (GridEyeImage *image);
Example Usage
Connection
Choose a Two-Wire Interface Master bus for your board. In this article, I chose TWIM3 . After checking the datasheet for my Atmel SAM4L Xplained Pro board, I found the pins that TWIM3 uses.
Using the following wiring scheme, connect the Grid Eye to the bus on your board. You may change AD_SELECT from ground to VDD with a 10k Ω pull-up resistor to change the device’s address.
Includes
-
Import both “grideye.h” and “grideye.c” into your working project.
-
Include “grideye.h” into your main operating file.
-
Using ASF Wizard, include the following modules into your project:
- TWI - Two-Wire Interface
- TWI - Two-Wire Master Interface
- System Clock Control
- Sleep Manager
- Power Management
- IOPORT - General purpose I/O service
- FLASHCALW Controller Software Driver
Setup I2C
The following will setup both the I2C data and clock to be used on the extension pins. The defines are for a Atmel SAM4L Xplained Pro board. You will have to change the defines according to your board.
To find the pins you need to setup, you need to know the Two-Wire Interface Master bus name for your board. In my example, I use TWIM3 which correlates to EXT2_PIN_TWI_SCL and EXT2_PIN_TWI_SDA.
ioport_set_pin_mode(EXT2_PIN_TWI_SCL, EXT2_TWI_SCL_MUX);
ioport_disable_pin(EXT2_PIN_TWI_SCL);
ioport_set_pin_mode(EXT2_PIN_TWI_SDA, EXT2_TWI_SDA_MUX);
ioport_disable_pin(EXT2_PIN_TWI_SDA);`
Initialize the Grid Eye
Now that the I2C pins are setup, the Grid Eye can be initialized using the library.
//Allocate memory to the Grid Eye structure
GridEye ge_inst;
//initialize the Grid Eye
ge_init(&ge_inst, TWIM3, 0);
Select Grid Eye Options
Using the library, we can change options in the Grid Eye registers. Here we set the Grid Eye to operate at 10 FPS and we setup interrupts.
//set FPS to 10
ge_setFPS(&ge_inst, true);
//Setup Grid Eye interrupt
ge_setInterrupt(&ge_inst, true, 115, 0, 5);
After setting up the Grid Eye interrupts, the INT pin on the Grid Eye will be pulled low whenever an interrupt occur along with the interrupt flag being set in the register.
Read Data
Finally, the Grid Eye is setup for operation. We can start to read the raw data values.
//Read the thermistor temperature
ge_readTemp(&ge_inst);
//Read in all 64 pixels of data
ge_readData(&ge_inst);
After executing ge_readData(), the Grid Eye buffer in the library has been filled with data. To print the most recent frame use the following:
//Loop through each pixel and print it to the console
for(i = 0; i < 64; i++)
printf("%d ", ge_inst.image[ge_inst.imagepointer].data[i]);
By default, the library holds the previous five frames read in. This allows for old frame comparison. To print out the previous frame, subtract one from ge_inst.imagepointer in the above code.
Basic Manipulation
Through extensive testing, I have found the most effective method of filtering noise from the background was to subtract the thermistor temperature from each pixel. This will cancel out a good amount of noise from the background and allow heat sources to stick out better.
//Loop through each pixel and print it to the console
for(i = 0; i < 64; i++)
printf("%d ", ge_inst.image[ge_inst.imagepointer].data[i] - ge_inst.temperature);
Now, check for any pixels with a value above 10. These ‘warm’ pixels will give a good indication that there is a valid heat source located in that region.
Usable Functions
C Data Structure
This library requires the use of a structure to contain the library data. This setup allows for multiple Grid Eye instances operating at once.
To allocate memory to a structure use the following:
‘’’
//Allocate memory to structure
GridEye ge_init;
‘’’
You can operate as many Grid Eyes in the same program as long as you have the buses and memory to support it.
Only two Grid Eyes may operate on a single bus. This is due to the Grid Eye only having two selectable I2C addresses.
ge_init
This function will initialize the Grid Eye structure variables and setup the needed variables to connect to the Grid Eye using the I2C interface.
uint8_t ge_init (GridEye *ge, Twim *twim, uint8_t grideye_address);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Twim *twim | ASF Two-Wire Interface Master address | TWIM3 |
| uint8_t grideye_address | Selectable Address (0 for AD_SELECT set to ground, else AD_SELECT at VDD) | 0 |
ge_readData
Reads in all 64 pixels of raw data from the Grid Eye. This will fill the a single frame in the data buffer.
bool ge_readData (GridEye *ge);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Returns | Result |
|---|---|
| false | Data read failed |
| true | Data read successful |
After executing this command, imagepointer will be incremented to reflect where the data was updated in the buffer.
To access the most recent frame after executing use the following example:
ge_readData(&ge_inst);
for(int i = 0; i < 64; i++)
printf("%d ", ge_inst.image[ge_inst.imagepointer].data[i]);
When the buffer is full, imagepointer will be wrapped around to zero.
ge_setFPS
Sets the frame rate in the Grid Eye register.
bool ge_setFPS (GridEye *ge, bool fps_set_10);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| bool fps_set_10 | Sets FPS (true for 10 FPS, false for 1 FPS) | true |
| Returns | Result |
|---|---|
| false | Data write failed |
| true | Data write successful |
ge_readData() will be able to read the data register as often as possible but the data will only be updated at the frame rate selected.
ge_readFPS
Read the current FPS value from the Grid Eye.
bool ge_setFPS (GridEye *ge, bool fps_set_10);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| bool fps_set_10 | Sets FPS (true for 10 FPS, false for 1 FPS) | true |
| Returns | Result |
|---|---|
| 1 | FPS set at 1 |
| 10 | FPS set at 10 |
| else | Value couldn’t be read |
ge_readTemp
Read the current thermistor temperature value from the Grid Eye. The result is stored under temperature in the data structure. This value is useful to subtract from the readData frame to filter out background noise.
bool ge_readTemp (GridEye *ge);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Returns | Result |
|---|---|
| false | Value couldn’t be read |
| true | Value read |
ge_readAverage
This function will fill the read buffer and average all the values. The default buffer is set to 5 which will take 500 ms to complete.
bool ge_readAverage (GridEye *ge);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Returns | Result |
|---|---|
| false | Data write failed |
| true | Data write successful |
ge_initialReset
Provides a quick way of resetting all setting registers on the Grid Eye. Essentially, this function performs a software reset.
bool ge_initialReset (GridEye *ge);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Returns | Result |
|---|---|
| false | Failed to reset |
| true | Reset sent successfully |
ge_setInterrupt
Initializes the Grid Eye’s built in interrupt system. The system will trigger an interrupt when the system’s settings match current conditions. An interrupt appears on the INT pin by pulling it low and will also set the interrupt flag high in the register. In code, the easiest way to detect an interrupt is by using ge_readInterruptFlag.
bool ge_setInterrupt (GridEye *ge, bool absolute, uint16_t upper, uint16_t lower, uint16_t hysteresis);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| bool absolute | Select absolute or difference mode | true |
| uint16_t upper | Upper boundary to trigger an interrupt | 115 |
| uint16_t lower | Lower boundary to trigger an interrupt | 0 |
| uint16_t hysteresis | Hysteresis level | 0 |
| Returns | Result |
|---|---|
| false | Data write failed |
| true | Data write successful |
ge_readInterruptFlag
Returns the value of the interrupt flag in the Grid Eye’s memory. Will clear the flag if given the argument.
bool ge_readInterruptFlag (GridEye *ge, bool clearFlag);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| bool clearFlag | Clear the flag after read | true |
| Returns | Result |
|---|---|
| false | Flag not set |
| true | Flag set |
ge_clearInterruptFlag
Clears the interrupt flag in the Grid Eye’s memory without reading the value.
bool ge_clearInterruptFlag (GridEye *ge);
| Argument | Use | Example |
|---|---|---|
| GridEye *ge | Pass the address of the Grid Eye structure | &ge_init |
| Returns | Result |
|---|---|
| false | Flag could not be cleared |
| true | Flag cleared |
Download
grideye_library.zip.zip (2.8 KB)
Additional Information
Panasonic Grid Eye Breakout Board and GUI
Panasonic Grid Eye Memory Registers