// ----------------------------------------------------------------------------------------
//
//  avr/sensors/avrcam/avrcam.h
//    
//  Bob Cook Development, Robotics Library
//  http://www.bobcookdev.com/rl/
//    
//  This file implements support for the JROBOT AVRcam.
//
//  Copyright (C) 2009 Bob Cook
//
//      This program is free software; you can redistribute it and/or modify it
//      under the terms of the GNU General Public License as published by the
//      Free Software Foundation; either version 2 of the License, or (at your
//      option) any later version.
//    
//      This program is distributed in the hope that it will be useful, but 
//      WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
//      or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License 
//      for more details.
//    
//      You should have received a copy of the GNU General Public License along
//      with this program; if not, write to the Free Software Foundation, Inc., 
//      51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
//
// ----------------------------------------------------------------------------------------


#if !defined( BCDRL_AVR_SENSORS_AVRCAM_H )
#define BCDRL_AVR_SENSORS_AVRCAM_H


#include <stdint.h>


// ----------------------------------------------------------------------------------------
//  definitions from "project_defs.h"
//
//  specify the UART port to use with one (and only one) of:
//
//      + PRJ_AVRCAM_USE_UART0
//      + PRJ_AVRCAM_USE_UART1
//
//  enable AVRcam commands with one or more of:
//
//      + PRJ_AVRCAM_ENABLE_GETVERSION
//      + PRJ_AVRCAM_ENABLE_TRACKING
//      + PRJ_AVRCAM_ENABLE_TRACKING_CLIP
//      + PRJ_AVRCAM_ENABLE_FRAMEGRAB
//
//  enable the debug support with:
//
//      + PRJ_AVRCAM_ENABLE_DEBUG
//
// ----------------------------------------------------------------------------------------

// ----------------------------------------------------------------------------------------
//  notes
//
//      Commands sent to the AVRcam (such as PING) will return true if the response is
//      the expected ACK. If the response is something else, or the AVRcam does not
//      respond within 1.25ms the result will be false.
//
// ----------------------------------------------------------------------------------------

// ----------------------------------------------------------------------------------------
//  avrcam_init
//
//      Initialize the AVRcam h/w according to the project_defs.h specification. This
//      will send a PING command to the camera to test connectivity.
//
//      Returns true if the initialization was successful.
//

bool avrcam_init();

    
// ----------------------------------------------------------------------------------------
//  avrcam_ping
//
//      Returns true if the PING command is successful.
//

bool avrcam_ping();


// ----------------------------------------------------------------------------------------
//  avrcam_get_version
//
//      Retrieve the version of the firmware in the AVRcam. The version string will be
//      valid only if the result is true.
//
//      Only compiled if PRJ_AVRCAM_ENABLE_GETVERSION is defined.
//

bool avrcam_get_version( char* verstr, uint8_t str_size );


// ----------------------------------------------------------------------------------------
//  avrcam_set_tracking_clip
//
//      Restrict the resulting rectangles from color blob tracking to the given area.
//      For best results call this before avrcam_start_tracking(). 
//
//      Only compiled if PRJ_AVRCAM_ENABLE_TRACKING_CLIP is defined.
//

void avrcam_set_tracking_clip( uint8_t ulx, uint8_t uly, uint8_t lrx, uint8_t lry );


// ----------------------------------------------------------------------------------------
//  avrcam_start_tracking
//
//      Start tracking color blobs. Returns true if tracking is now enabled. The results
//      will be stored in the provided structure, althougth no results will be available
//      immediately. Call avrcam_update_tracking() regularly to update the results.
//
//      Only compiled if PRJ_AVRCAM_ENABLE_TRACKING is defined.
//

typedef struct
{
    uint8_t id; // color table index: 1, 2, etc. not valid if 0
    uint8_t ul_x, ul_y, lr_x, lr_y; // ul = 0,0

} avrcam_track_data_t;

bool avrcam_start_tracking( avrcam_track_data_t* data, uint8_t num_data );


// ----------------------------------------------------------------------------------------
//  avrcam_update_tracking
//
//      Process tracking data and populate the structure set by avrcam_start_tracking()
//      as color blob information is received. Returns true if any entries in the table
//      are updated.
//
//      This function should be called on average every millisecond (1 kHz).
//
//      Has no effect if avrcam_start_tracking() was never called, or if tracking was
//      stopped by calling avrcam_stop_tracking(). The result will always be false.
//
//      Only compiled if PRJ_AVRCAM_ENABLE_TRACKING is defined.
//

bool avrcam_update_tracking();


// ----------------------------------------------------------------------------------------
//  avrcam_stop_tracking
//
//      Turn off the color blob tracking function.
//
//      Only compiled if PRJ_AVRCAM_ENABLE_TRACKING is defined.
//

void avrcam_stop_tracking();


#endif  // #if defined( BCDRL_AVR_SENSORS_AVRCAM_H )
// ----------------------------------------------------------------------------------------
//  end of avrcam.h
// ----------------------------------------------------------------------------------------

