nodemcu-firmware/docs/modules/i2c.md

I²C Module

Since	Origin / Contributor	Maintainer	Source
2014-12-22	Zeroday	Zeroday	i2c.c

This module supports different interfaces for communicating via I²C protocol. All interfaces can be assigned to arbitrary GPIOs for SCL and SDA and can be operated concurrently.

• i2c.SW software based bitbanging, master mode only, synchronous operation
• i2c.HW0 ESP32 hardware port 0, master or slave mode, synchronous or asynchronous operation
• i2c.HW1 ESP32 hardware port 1, master or slave mode, synchronous or asynchronous operation

The hardware master interfaces differ from the SW interface as the commands (start, stop, read, write) are queued up to an internal command list. Actual I²C communication is initiated afterwards using the i2c.transfer() function. Commands for the i2c.SW interface are immediately effective on the I²C bus and read data is also instantly available.

i2c.address()

Send (SW) or queue (HWx) I²C address and read/write mode for the next transfer.

Communication stops when the slave answers with NACK to the address byte. This can be avoided with parameter ack_check_en on false.

Syntax

i2c.address(id, device_addr, direction[, ack_check_en])

Parameters

• id interface id
• device_addr device address
• direction i2c.TRANSMITTER for writing mode , i2c.RECEIVER for reading mode
• ack_check_en enable check for slave ACK with true (default), disable with false

Returns

true if ack received (always for ids i2c.HW0 and i2c.HW1), false if no ack received (only possible for i2c.SW).

See also

i2c.read()

i2c.read()

Read (SW) or queue (HWx) data for variable number of bytes.

Syntax

i2c.read(id, len)

Parameters

• id interface id
• len number of data bytes

Returns

• string of received data for interface i2c.SW
• nil for ids i2c.HW0 and i2c.HW1

Example

id  = i2c.SW
sda = 1
scl = 2

-- initialize i2c, set pin1 as sda, set pin2 as scl
i2c.setup(id, sda, scl, i2c.SLOW)

-- user defined function: read from reg_addr content of dev_addr
function read_reg(dev_addr, reg_addr)
    i2c.start(id)
    i2c.address(id, dev_addr, i2c.TRANSMITTER)
    i2c.write(id, reg_addr)
    i2c.stop(id)
    i2c.start(id)
    i2c.address(id, dev_addr, i2c.RECEIVER)
    c = i2c.read(id, 1)
    i2c.stop(id)
    return c
end

-- get content of register 0xAA of device 0x77
reg = read_reg(0x77, 0xAA)
print(string.byte(reg))

####See also i2c.write()

i2c.setup()

Initialize the I²C interface for master mode.

Syntax

i2c.setup(id, pinSDA, pinSCL, speed)

####Parameters

• id interface id
• pinSDA IO index, see GPIO Overview
• pinSCL IO index, see GPIO Overview
• speed bit rate in Hz, positive integer
  • i2c.SLOW for 100000 Hz, max for i2c.SW
  • i2c.FAST for 400000 Hz
  • i2c.FASTPLUS for 1000000 Hz

Returns

speed the selected speed

####See also i2c.read()

i2c.start()

Send (SW) or queue (HWx) an I²C start condition.

Syntax

i2c.start(id)

Parameters

id interface id

Returns

nil

####See also i2c.read()

i2c.stop()

Send (SW) or queue (HWx) an I²C stop condition.

Syntax

i2c.stop(id)

####Parameters id interface id

Returns

nil

####See also i2c.read()

i2c.transfer()

Starts a transfer for the specified hardware module. Providing a callback function allows the transfer to be started asynchronously in the background and i2c.transfer() finishes immediately. Without a callback function, the transfer is executed synchronously and i2c.transfer() comes back when the transfer completed. Data from a read operation is returned from i2c.transfer() in this case.

First argument to the callback is a string with data obtained from a read operation during the transfer or nil, followed by the ack flag (true = ACK received).

Syntax

i2c.transfer(id[, cb_fn][, to_ms])

Parameters

• id interface id, i2c.SW not allowed
• cb_fn(data, ack) function to be called when transfer finished
• to_ms timeout for the transfer in ms, defaults to 0=infinite

Returns

• synchronous operation:
  • data string of received data (nil if no read or NACK)
  • ack true if ACK received, false for NACK
• nil for asynchronous operation

i2c.write()

Write (SW) or queue (HWx) data to I²C bus. Data items can be multiple numbers, strings or lua tables.

Communication stops when the slave answers with NACK to a written byte. This can be avoided with parameter ack_check_en on false.

####Syntax i2c.write(id, data1[, data2[, ..., datan]][, ack_check_en])

####Parameters

• id interface id
• data data can be numbers, string or lua table.
• ack_check_en enable check for slave ACK with true (default), disable with false

Returns

number number of bytes written

Example

i2c.write(0, "hello", "world")

See also

i2c.read()

I²C slave mode

The I²C slave mode is only available for the hardware interfaces i2c.HW0 and i2c.HW1.

i2c.slave.on()

Registers or unregisters an event callback handler.

Syntax

i2c.slave.on(id, event[, cb_fn])

Parameters

• id interface id, i2c.HW0 or i2c.HW1
• event one of
  • "receive" data received from master
• cb_fn(err, data) function to be called when data was received from the master. Unregisters previous callback for event when omitted.

Returns

nil

i2c.slave.setup()

Initialize the I²C interface for slave mode.

Syntax

i2c.slave.setup(id, slave_config)

Parameters

• id interface id, i2c.HW0 or i2c.HW1
• slave_config table containing slave configuration information
  • sda IO index, see GPIO Overview
  • scl IO index, see GPIO Overview
  • addr slave address (7bit or 10bit)
  • 10bit enable 10bit addressing with true, use 7bit with false (optional, defaults to false is omitted)
  • rxbuf_len length of receive buffer (optional, defaults to 128 if omitted)
  • txbuf_len length of transmit buffer (optional, defaults to 128 if omitted)

Returns

nil

i2c.slave.send()

Writes send data for the master into the transmit buffer. This function returns immediately if there's enough room left in the buffer. It blocks if the buffer is doesn't provide enough space.

Data items can be multiple numbers, strings or lua tables.

Syntax

i2c.slave.send(id, data1[, data2[, ..., datan]])

Parameters

• id interface id, i2c.HW0 or i2c.HW1
• data data can be numbers, string or lua table.

Returns

number number of bytes written