Interfaces can use arbitrary GPIOs for the clock (SCL) and data (SDA) lines.
The interfaces are not suitable for multi-master configurations.
In master mode, I²C communication is performed by combinations of 5 basic I²C operations, provided by the functions `i2c.start()`,`i2c.stop()`,`i2c.address()`,`i2c.write()`,`i2c.read()`.
The behaviour of these functions is quite different according to the type of interface.
For the software interface, these functions IMMEDIATELY perform the requested I²C operation and return on completion. For slow bus speeds and multi-byte reads or writes, this can tie up the CPU for a significant time.
However, any results returned reflect the effective outcome of the operation.
For the hardware interfaces, these functions do NOT trigger any immediate I²C activity but enqueue (store) a request for later, DEFERRED execution.
These functions return immediately as they do not have to wait for any I²C operation to complete.
As a consequence, any results returned do not reflect the effective outcome of the operation.
The function `i2c.transfer()` MUST be called to effectively execute the stored requests for operations.
Execution of the stored requests is performed by the hardware interface.
If `i2c.transfer()` is provided with a call-back function, it will return before completion of the enqueued I²C operations, freeing the CPU for other tasks.
#### Example using the software interface
```lua
-- check if chip is present and functional by reading a signature/chip id
-- i2c bus setup
sda = 23 -- pins as on Adafruit Huzzah32 silkscreen
scl = 22
id = i2c.SW -- software interface
speed = i2c.SLOW
-- values for Bosch Sensortech BMP180 chip
bmpAddress = 0x77
bmpIdRegister = 0xD0
bmpChipSignature = 0x55
-- initialize i2c software interface
i2c.setup(id, sda, scl, speed)
-- attempt to read chip id and compare against expected value
function simple_check_chip(dev_address, dev_register, dev_signature)
i2c.start(id)
assert(i2c.address(id, dev_address, i2c.TRANSMITTER) , "!!i2c device did not ACK first address operation" )
i2c.write(id, dev_register)
i2c.start(id) -- repeated start condition
assert( i2c.address(id, dev_address, i2c.RECEIVER) , "!!i2c device did not ACK second address operation" )
if i2c.read(id, 1):byte() == dev_signature then
print("..chip is operational")
else
print("!!The chip does not have the expected signature")
end
i2c.stop(id)
end
--
print("Chip check, should fail because device address is wrong")
-`direction``i2c.TRANSMITTER` for write mode , `i2c.RECEIVER` for read mode
-`ack_check_en` enable check for slave ACK with `true` (default), disable check with `false`
This last, optional parameter is only relevant for for hardware interfaces `i2c.HW0` and `i2c.HW1` and defaults to `true'.
The I²C `address` operation is enqueued for later execution and this parameter will be used at that later time.
At that time, if NO slave device produces an ACK to the address operation, the default assumption is that the slave at that address is absent or not functional. Any remaining I²C operations in the queue will be ignored/flushed/discarded and the communication will be stopped.
This default queue flushing behaviour on slave NACK can be overridden by specifying `false`.
for interface `i2c.SW`: returns `true` if ack received, `false` if no ack received. This value should be checked to decide whether to continue communication.
for interfaces `i2c.HW0` and `i2c.HW1`: always returns `true`.
The value returned by a read operation is a string. Refer to the slave datasheet for multibyte reads/autoincrement capability, endianness and format details.
-`i2c.SLOW` for 100000 Hz (100 KHz a.k.a Standard Mode), this is the maximum allowed value for the `i2c.SW` interface
-`i2c.FAST` for 400000 Hz (400 KHz a.k.a Fast Mode)
-`i2c.FASTPLUS` for 1000000 Hz (1 MHz, a.k.a. Fast-mode Plus), this is the maximum allowed value for `i2c.HWx`interfaces
-`stretchfactor` integer multiplier for timeout
The pins declared for SDA and SCL are configured with onchip pullup resistors. These are weak pullups.
The data sheets do not specify any specific value for the pullup resistors, but they are reported to be between 10KΩ and 100KΩ with a target value of 50 KΩ.
Additional pullups are recommended especialy for faster speeds, in doubt try 4.7 kΩ.
The `speed` constants are provided for convenience but any other integer value can be used.
The last, optional parameter `stretchfactor` is only relevant for the `HWx`interfaces and defaults to 1.
The hardware interfaces have a built-in timeout, designed to recover from abnormal I²C bus conditions.
The default timeout is defined as 8 I²C SCL clock cycles. With an 80 MHz CPU clock speed and a 100 KHz this means 8*80/0.1 = 6400 CPU clock cycles i.e. 80 µS.
A busy or slow slave device can request a temporary pause of communication by keeping the SCL line line low a.k.a. clock stretching.
This clock stretching may exceed the timeout value and cause (often intermittent) errors.
This can be avoided either by using a slower bit rate or by specifying a multiplier value for the timeout.
Calling setup on an already configured hardware interface will cause panic.
Note to wizards: The I²C specifications defines a High-Speed mode allowing communication up to 3.4 Mbits/s, with the added complexity of variable clock speed and current-source pullups. The Expressif documentation states that the I²C hardware interfaces support up to 5 MHz, constrained by SDA pull-up strength. This module will object to speeds higher than 1 MHz, but your experience and feedback is welcome !
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 returning any value.
Results from any data read will be provided to the callback function.
-`id` hardware interface id only , `i2c.SW` not allowed
-`callback` optional callback function to be called when transfer finishes
-`to_ms` optional timeout for the synchronous transfer in ms, defaults to 0 (infinite)
The optional callback function should be defined to accept 2 arguments i.e. `function( data , ack )` where
-`data `is the string from a read operation during the transfer (`nil` if no read or failed ACK )
- `ack is a boolean (true = ACK received).
The optional timeout parameter defaults to 0 meaning infinite and is only relevant for synchronous mode. This can be used to define an upper bound to the execution time of `i2c.transfer()`.
It specifies the maximum delay in mS before `i2c.transfer()` returns, possibly before the complete I²C set of operations is executed.
This timeout should not be confused with the timeout specified in `i2c.setup`.
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.
