I2C Communications (Wire)

I²C Communications (Wire)

This is an I²C communications library that facilitates two-wire class communications with I²C/TWI devices (also called "Wire Library"). The pull-up to communication lines is needed. To use, specify #include <wire.h>.

begin

Description: Initiate the Wire library and joins the I²C bus as a master or slave. This should normally be called only once.
Syntax: Wire.begin()
Wire.begin(address)
Parameters: address: The 7-bit slave address (optional); if not specified, join the bus as a master.
Returns: None

requestFrom

Description: Used by the master to request bytes from a slave device. The bytes may then be retrieved with the available() and read() functions.
Syntax: Wire.requestFrom(address, quantity)
Wire.requestFrom(address, quantity, stop)
Parameters: address: The 7-bit address of the device from which to request bytes.
quantity: The number of bytes to request.
stop: Boolean. True will send a stop message after the request, releasing the bus. False will continually send a restart after the request, keeping the connection active.
Returns: Byte: The number of bytes returned from the slave device.

beginTransmission

Description: Begin a transmission to the I²C slave device with the given address. Subsequently, queue bytes for transmission with the write() function and transmit them by calling endTransmission().
Syntax: Wire.beginTransmission(unsigned char address)
Parameters: address: The 7-bit address of the device to which to transmit
Returns: None

endTransmission

Description: Ends a transmission to a slave device that was begun by beginTransmission() and transmits the bytes that were queued by write().
Syntax: unsigned char Wire.endTransmission()
Parameters: None
Returns: 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

write

Description: Adds a character string or data to the end of the transmit buffer.
Syntax: Wire.write(value)
Wire.write(string)
Wire.write(data, length)
Parameters: value: A value to send as a single byte
string: A string to send as a series of bytes
data: An array of data to send as bytes
length: The number of bytes to transmit
Returns: Byte: Write() will return the number of bytes written, though reading that number is optional.

available

Description: Returns the number of bytes available for retrieval in the receive buffer.
Syntax: Wire.available()
Parameters: None
Returns: The number of bytes available for reading.

read

Description: Reads one byte of data from the receive buffer.
Syntax: Wire.read()
Parameters: None
Returns: The next byte received.

onReceive

Description: Registers a function to be called when a slave device receives a transmission from a master.
Syntax: Wire.onReceive(handler)
Parameters: handler: The function to be called when the slave receives data; this should take a single int parameter (the number of bytes read from the master) and return nothing; e.g. void myHandler(int numBytes)
Returns: None

onRequest

Description: Register a function to be called when a master requests data from this slave device.
Syntax: Wire.onRequest(handler)
Parameters: handler: The function to be called, takes no parameters and returns nothing; e.g. void myHandler()
Returns: None

Example

Example to transfer to address 10.


#include <Arduino.h>
#include <Wire.h>
    
byte val = 0;
    
void setup() {
    Wire.begin();
    
    Wire.beginTransmission(10); //send to address 10
    Wire.write(val);  // send 1byte to que
    Wire.endTransmission();
}
    
void loop() {}