I2C Communications (Wire)

Digital I/O
Analog I/O
Advanced I/O
Time
Math
Trigonometry
Random Numbers
Bits and Bytes
Interrupts
Serial Comm.

Servo Motor
Stepping Motor
Character LCD
EEPROM
SPI
I²C (Wire)
SD Card
SD (File Operations)
Ethernet
Ethernet (Server)
Ethernet (Client)
Firmata
Periodic Operation
Power Save
Clock (RTC)
SoftwareSerial
Utility

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 are 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 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() {}