i2c - wire commands

[last updated: 2025-05-15]
i2c home page
Minimum code for programming alternate modes of i2c operation:
-----

• Notes:
  • default i2c speed on arduinos is 100 khz, but can be increased to 400 khz (see: Wire.setClock() below)
  • Valid I2C slave device address should be a 7-bit value that’s larger than 7 (e.g. 8, 10, …, 127).
  • The transmit queue has max capacity of 30 bytes (32???). Putting more in will get truncated.
  • Sending strings (NOT "Strings"): they must be null terminated. The null counts as a byte (re: max queue capacity).
    In slave code, use Wire.available() to check for data and then Wire.read to read it a byte at a time.
    If you are sending a string then the receiver would use the null to identify the end of the string.
  • In operation, unless actively transmitting data, the i2c software (once started with begin)
    is always listening on the bus. If data is received, an interrupt is automatically generated, and the ... handler is executed...
        (??? but incoming data will be ignored if it's not a Slave device, or if it's not a Master that has executed a
        Wire.requestFrom so is expecting a response from the Slave???)

  --------------------------------------------------------------------

  
  Wire Library Command Details:

• Wire.begin()
  Initialize the serial I2C module. It can initialize the I2C as a master device, or a slave device.
  For slave initialization, you must specify the address of the slave peripheral.
  Wire.begin(); // Initialize As A Master I2C Device
  Wire.begin(0x0A); // Initialize as a slave with 7-bit address = 0x0A
  A "7-bit" address means a number larger than 7 (e.g. 8, 10, …, 127).

• Wire.end()
  Disables the Wire library, reversing the effect of Wire.begin(). To use the Wire library again after this, call Wire.begin() again.
  Can be used to switch the I2C operation mode from master to slave or vice versa during runtime without restarting the whole microcontroller.

• Wire.beginTransmission(address); (7-bit address)
  Begins a transmission to the I2C peripheral device with the given address.
  After this begin statement, put bytes that you want to send into the output queue by using the Wire.write() function,
      then transmit the entire queue by calling Wire.endTransmission().

• Wire.endTransmission()
  Ends a transmission to a peripheral device that was begun by Wire.beginTransmission()
  and transmits the bytes that were queued by write().
  The Wire.endTransmission() accepts a boolean argument changing its behavior for compatibility with certain I2C devices.
  Wire.endTransmission(stop);
  If stop is true, then endTransmission() sends a stop condition after transmission, releasing the I2C bus.
  If stop is false, endTransmission() sends a restart condition after transmission. The bus will not be released, but will remain active with the current master in control, which prevents another controller device from transmitting. This allows one controller device to send multiple transmissions while in control. The default value is true.
  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.
  5: timeout

• Wire.write()
  Writes data from a peripheral device in response to a request from a controller device or queues bytes for transmission from a controller to a peripheral device.
  This function is called between Wire.beginTransmission() and Wire.endTransmission().
  You can use the Wire.write() function to send a single byte variable, a string of characters, or an array of bytes alongside the length of the array.
  Wire.write(value); (single byte)
  Wire.write(string);
      Wire.write("x is "); // sends five bytes
  Wire.write(data, length); (length: the number of bytes to transmit.)

  Returns the number of bytes written (reading this number is optional).

• Wire.requestFrom(address, quantity, stop);
  Used by the controller to request bytes from a peripheral device.
  The bytes may then be retrieved with the Wire.available() and Wire.read() functions.
  The Wire.requestFrom() function takes a boolean (stop) argument that changes its behavior for compatibility with certain I2C devices.
  If true, the requestFrom() function sends a stop condition on the I2C bus after the request, releasing the I2C bus.
  If false, the requestFrom() function sends a restart condition after the request.
      The bus will not be released, which prevents another master device from requesting between messages.
      This allows one master device to send multiple requests while in control.
  If not specified, the default value of true is assumed.
  address: the 7-bit slave address of the device to request bytes from.
  quantity: the number of bytes to request.
  stop: true or false. true sends 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 peripheral device.

• Wire.available()
  This function returns the number of bytes available for retrieval with read().
  This function should be called by the Master after having done a requestFrom()
      or by a Slave device inside its onReceive() handler.
  Parameters: None.
  Returns: The number of bytes available for reading.

• Wire.read()
  Reads a byte that was transmitted from a controller device to a peripheral device,
  or was transmitted from a peripheral device to a controller device after the Master did a requestFrom()
  Parameters: None.
  Returns: The next byte received.
  Example:
  #include
  byte RxBuffer[100] = {0};
  int RxIdx = 0;
  void setup() {
      Wire.begin(); // Initialize I2C (Master Mode: address is optional)
  }
  void loop() {
      Wire.requestFrom(0x55, 6); // Request 6 bytes from slave device @ address 0x55
      // Slave may send less than requested
      while(Wire.available()) {
          RxBuffer[RxIdx++] = Wire.read(); // Receive a byte & push it into the RxBuffer
      }
  delay(100);
  }

• Wire.onReceive(handler);
  This function registers a callback function to be called when a peripheral device receives a transmission from a controller device.
  Parameters: handler: the function to be called when the peripheral device receives data.
      This handler function should take a single int parameter (the number of bytes read from the controller device) and return nothing.

• Wire.onRequest(handler);
  This function registers a callback function to be called when a controller device requests data from a peripheral device.
  Parameters: handler: the function to be called, takes no parameters and returns nothing.

• Wire.setClock(clockFrequency)
  clockFrequency in Hertz. 100,000 (default) to 400,000.
  Modifies the clock frequency (data rate) for I2C communication.

.

.

eof