Task 27 -- The Wire Librrary

27. List the main functions of the Wire library.

       Say what they do with examples.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Wire Library Functions
======================

1.    begin()
      begin(address)

Initiates the Wire library and joins I2C bus as master or slave.
Normally called only once.

Parameters: address: the 7-bit slave address (optional);
        if not specified, join the bus as a master.
No returns.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2.  requestFrom(address, count)

Used by master to request bytes from slave device.
The bytes may then be retrieved with the available() and receive() functions.

Parameters:    address:  the 7-bit address of device to request bytes from
        quantity: the number of bytes to request
No returns.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3.  beginTransmission(address)

Begin transmission to I2C slave device with address given.
Queue bytes for transmission with send() function.
Transmit bytes by calling endTransmission().

Parameters: address: 7-bit address of device to transmit to
No returns.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

4.  endTransmission()

Ends transmission to slave device begun by beginTransmission()
Actually transmits the bytes queued by send().

No parameters.

Returns: byte, indicating transmission status:

0   success
1   data too long to fit in transmit buffer
2   received NACK on transmit of address
3   received NACK on transmit of data
4   other error.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

5.  send()

Sends data from slave device in response to request from master, or
queues bytes for transmission from master to slave device
(in-between calls to beginTransmission() and endTransmission()).

Parameters: value:      a byte to send (byte)
        string:     a string to send (char *)
        data:       an array of data to send (byte *)
        quantity:     the number of bytes of data to transmit (byte)
No returns.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

6.  byte available()

Returns number of bytes available for retrieval with receive().
Should be called on master device after call to requestFrom(),
or on slave inside the onReceive() handler.

No parameters;
Returns:  number of bytes available for reading.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

7.  byte receive()

Retrieves byte transmitted from slave device to master
after call to requestFrom()
         or transmitted from master to slave.

No parameters;
Returns:  next byte received.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8.    onReceive(handler)
9.    onRequest(handler)
These are not much used in our projects.

Note: On most Arduino boards,
                   SDA (data line) is on analog input pin 4, and
                   SCL (clock line) is on analog input pin 5.


Reference:  http://arduino.cc/en/Reference/Wire
.