// ----------------------------------------------------------------------------------------
//
//  avr/device/twi_master.h
//    
//  Bob Cook Development, Robotics Library
//  http://www.bobcookdev.com/rl/
//    
//  This file provides the interface for the TWI library, using master mode.
//
//  Copyright (C) 2008 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_DEVICE_TWI_MASTER_H )
#define BCDRL_AVR_DEVICE_TWI_MASTER_H


#include <stdint.h>


// ----------------------------------------------------------------------------------------
//  definitions from "project_defs.h"
//
//  enable TWI master mode by:
//  
//      + PRJ_TWI_MASTER_ENABLE
//
//  specify the bus speed (for the master) with:
//
//      + PRJ_TWI_BUS_FREQ
//
// ----------------------------------------------------------------------------------------



// ----------------------------------------------------------------------------------------
//  twi_master_init
//
//      Initialize the TWI h/w for master mode; call this once, before doing any i/o.
//

void twi_master_init();


// ----------------------------------------------------------------------------------------
//  twi_master_start
//
//      Issue a start condition and send the address of the device to communicate with.
//
//      Returns true if the device is now accessible.
//

bool twi_master_start( const uint8_t address );


// ----------------------------------------------------------------------------------------
//  twi_master_start_repeated
//
//      Similar to twi_master_start() except this is a repeated start.
//
//      Returns true if the device is now accessible.
//

bool twi_master_start_repeated( const uint8_t address );


// ----------------------------------------------------------------------------------------
//  twi_master_start_wait
//
//      Similar to twi_master_start() except it waits for the bus and device to become 
//      accessible.
//

void twi_master_start_wait( const uint8_t address );


// ----------------------------------------------------------------------------------------
//  twi_master_write
//
//      Send a byte to the remote device. Assumes twi_master_start() was successful.
//
//      Returns true if the byte was sent successfully.
//

bool twi_master_write( const uint8_t data );


// ----------------------------------------------------------------------------------------
//  twi_master_read_and_request_more
//
//      Read a byte from the remote device, and signal that we intend to receive more
//      data from the device immediately afterwards.
//

uint8_t twi_master_read_and_request_more();


// ----------------------------------------------------------------------------------------
//  twi_master_read_and_stop
//
//      Read a byte from the remote device, and signal this is the last read (puts a
//      stop condition on the bus).
//

uint8_t twi_master_read_and_stop();


// ----------------------------------------------------------------------------------------
//  twi_master_send_stop
//
//      Send a stop condition on the bus.
//

void twi_master_send_stop();


#endif  // #if !defined( BCDRL_AVR_DEVICE_TWI_MASTER_H )
// ----------------------------------------------------------------------------------------
//  end of twi_master.h
// ----------------------------------------------------------------------------------------

