|
NetBurner 3.5.8
PDF Version |
Arduino Wire-compatible I2C controller/target interface. More...
#include <Wire.h>
Public Member Functions | |
| TwoWire (void) | |
| Construct a TwoWire using the platform default I2C module. | |
| TwoWire (int mod) | |
| Bind to a specific hardware I2C module, leaving the pins to the caller. | |
| TwoWire (PinIO scl, PinIO sda) | |
| Construct a TwoWire using specific SCL/SDA pins. | |
| TwoWire (int sclpin_num, int sdapin_num) | |
| Construct a TwoWire using Pins[] array index numbers. | |
| ~TwoWire () | |
| Destructor. | |
| bool | isValid () const |
| Report whether this object is bound to a hardware I2C module. | |
| void | setClock (uint32_t clockbaud) |
| Set the I2C clock speed. | |
| void | begin (uint8_t slave_addr=0) |
| Initialize the I2C interface. | |
| void | end () |
| Shut down the I2C interface. | |
| void | beginTransmission (uint8_t address) |
| Begin a write transaction to a target device. | |
| int | endTransmission (bool bStop=true) |
| End a write transaction and send data on the bus. | |
| size_t | write (const uint8_t *pdata, int len) |
| Queue data bytes for transmission. | |
| size_t | write (uint8_t v) |
| Queue a single byte for transmission. | |
| size_t | write (const char *pStr, int len=-1) |
| Queue a string for transmission. | |
| int | requestFrom (uint8_t address, size_t quantity, bool stop=true) |
| Request bytes from a target device. | |
| size_t | available () |
| Check how many bytes are available to read. | |
| size_t | read (uint8_t *pbuf, size_t maxlen) |
| Read available data into a buffer (non-standard extension). | |
| uint8_t | read () |
| Read the next byte from the receive buffer. | |
Target functions | |
| void | onReceive (slave_rx_handler *handler) |
| Register a callback for target (slave) receive events. | |
| void | onRequest (slave_rq_handler *handler) |
| Register a callback for target (slave) request events. | |
| void | setWireTimeout (int timeout_usec=0, bool reset_on_timeout=false) |
| Set the transaction completion timeout. | |
| void | clearTimeout () |
| Clear the transaction completion timeout. | |
| bool | getWireTimeoutFlag () |
| Check whether a timeout has occurred. | |
Non-standard extensions | |
| void | reset () |
| Reset the I2C peripheral and return the object to an idle state. | |
| bool | ping (uint8_t addr) |
| Check whether a device is present at the given address. | |
| int | writeRegN (uint8_t dAddr, uint32_t reg, const uint8_t *buf, uint32_t blen) |
| Write a number of bytes to a device register. | |
| void | setNumAddressBytes (uint8_t numAddressBytes=1) |
| Specify the register address size for a read or write transaction. | |
| int | readRegN (uint8_t dAddr, uint32_t reg, uint8_t *buf, uint32_t blen) |
| Read a number of bytes from a device register. | |
| int | writeReg8 (uint8_t dAddr, uint32_t reg, uint8_t data) |
| Write a single byte to a device register. | |
| int | readReg8 (uint8_t dAddr, uint32_t reg, uint8_t &data) |
| Read a single byte from a device register. | |
Arduino Wire-compatible I2C controller/target interface.
Provides a TwoWire interface for communicating with I2C devices, compatible with the Arduino Wire library API. Internal 256-byte TX and RX buffers are used to stage data for each transaction. All bus operations are thread-safe using semaphore-based locking.
In addition to the standard Wire API, non-standard extensions are provided for register-level I2C access (writeRegN(), readRegN()), bus scanning (ping()), and bus recovery (reset()).
TwoWire always drives a hardware I2C peripheral. It does not fall back to a software bit-banged implementation. For bit-banged I2C on arbitrary GPIO pins, use the separate BBI2C class.
| TwoWire::TwoWire | ( | void | ) |
Construct a TwoWire using the platform default I2C module.
Selects the first entry (index 0) in the platform's valid_i2c[] table. See I2C Pin Mapping Reference for default pins on each platform.
| TwoWire::TwoWire | ( | int | mod | ) |
Bind to a specific hardware I2C module, leaving the pins to the caller.
This constructor deliberately does not configure any pins. It binds the peripheral and nothing else, so the SCL and SDA pads keep whatever function they already had. The caller owns the pins.
It is not an incomplete version of the other constructors. A module number on its own does not identify a pin pair, because a module can usually be reached from several. On the SOMRT1061, for example, three different pin pairs reach LPI2C3. Choosing one automatically would mean muxing pads the application never named, which could take over pins already in use for something else.
Use this constructor when the pins are already set up by other means, such as board initialisation code, another TwoWire object on the same module, or your own call to PinIO::function(). If you want the driver to configure the pins, use TwoWire(PinIO, PinIO), TwoWire(int, int) or the parameterless constructor instead.
An object built this way with pins that are not muxed to the peripheral will construct successfully and report isValid() as true, because a module really is bound. It simply will not transact, since the peripheral is not connected to anything. There is no way for the driver to detect that.
Module numbering is platform-dependent:
| mod | I2C module number (platform-dependent, see above) |
Construct a TwoWire using specific SCL/SDA pins.
Searches the platform's valid_i2c[] table for a matching pin pair, configures the pins to their I2C alternate function, and initializes the corresponding hardware I2C module.
| scl | SCL pin |
| sda | SDA pin |
| TwoWire::TwoWire | ( | int | sclpin_num, |
| int | sdapin_num ) |
Construct a TwoWire using Pins[] array index numbers.
Behaves identically to TwoWire(PinIO, PinIO), but accepts integer indexes into the platform's Pins[] array instead of PinIO objects.
| sclpin_num | SCL pin index in the Pins[] array |
| sdapin_num | SDA pin index in the Pins[] array |
| TwoWire::~TwoWire | ( | ) |
Destructor.
Releases I2C hardware resources. Calls end() if the interface is still active.
| size_t TwoWire::available | ( | ) |
Check how many bytes are available to read.
Returns the number of unread bytes remaining in the receive buffer after a requestFrom() call.
| Number | of bytes available in the buffer |
| void TwoWire::begin | ( | uint8_t | slave_addr = 0 | ) |
Initialize the I2C interface.
Call with no argument (or 0) for controller (master) mode, or with a non-zero 7-bit address for target (slave) mode.
Uses an internal reference counter: multiple begin() calls require a matching number of end() calls before the hardware is released. Call setClock() before the first begin() if a non-default speed is desired.
| slave_addr | 7-bit target address (0 = controller/master mode) |
| void TwoWire::beginTransmission | ( | uint8_t | address | ) |
Begin a write transaction to a target device.
Sets the target address and clears the transmit buffer. Queue data bytes with write() calls, then call endTransmission() to execute the transaction on the bus. Nothing is sent until endTransmission() is called.
Expand for Example Usage
| address | 7-bit I2C address of the target device |
| void TwoWire::clearTimeout | ( | ) |
Clear the transaction completion timeout.
Disables any timeout previously set by setWireTimeout().
| void TwoWire::end | ( | ) |
| int TwoWire::endTransmission | ( | bool | bStop = true | ) |
End a write transaction and send data on the bus.
Transmits the data queued since beginTransmission(). By default sends a stop condition and releases the bus; pass false to send a repeated start instead (useful for combined write-then-read sequences).
| bStop | If true (default), sends a stop condition and releases the bus. If false, sends a repeated start for a follow-up transaction. |
| wire_success | (0) Transaction completed successfully |
| wire_data_too_big | (1) Data exceeds the 256-byte transmit buffer |
| wire_NACK_on_address | (2) Target did not acknowledge its address |
| wire_NACK_on_data | (3) Target did not acknowledge a data byte |
| wire_other_error | (4) Unspecified bus error |
| wire_timeout | (5) Transaction timed out |
| bool TwoWire::getWireTimeoutFlag | ( | ) |
Check whether a timeout has occurred.
Returns true if a transaction has timed out since the last call to clearTimeout() or setWireTimeout().
| true | A timeout has occurred |
| false | No timeout has occurred |
|
inline |
Report whether this object is bound to a hardware I2C module.
A TwoWire constructed from a pin pair that does not appear in the platform's valid_i2c[] table, or from an out of range module number, has no hardware behind it. Such an object is inert: begin() does nothing, ping() returns false, and the register calls return wire_other_error rather than touching the bus.
Nothing reports that failure at construction time, because a constructor cannot return a status, so check this before use if the pins are not hard-coded.
Expand for Example Usage
| true | A hardware module is bound and the object is usable |
| false | Construction failed; every call will do nothing or error |
| void TwoWire::onReceive | ( | slave_rx_handler * | handler | ) |
Register a callback for target (slave) receive events.
The handler is called from interrupt context when this device (operating in target mode) receives data from a controller. Keep the handler short and avoid blocking calls.
| handler | Pointer to the function to call when bytes are received |
| void TwoWire::onRequest | ( | slave_rq_handler * | handler | ) |
Register a callback for target (slave) request events.
The handler is called from interrupt context when a controller requests data from this device. The handler should call write() to queue response bytes. Keep the handler short and avoid blocking calls.
| handler | Pointer to the function to call when bytes are requested |
| bool TwoWire::ping | ( | uint8_t | addr | ) |
Check whether a device is present at the given address.
Sends a start condition and address byte, then checks for an ACK. Useful for scanning the I2C bus to discover connected devices.
Expand for Example Usage
A device that never answers leaves that loop spinning, so give it a bound if that would be a problem:
bbScanI2CBus() in the PlatformSpecific/SAME70/I2C/AddressScan example.A false negative from ping() does not mean the device is unusable. Reads and writes to a device you already know the address of are not affected, so this matters for discovery rather than for normal traffic.
false result never proves a device is absent, on any platform. An address can also fail to answer because the device is busy, held in reset, or still completing an internal operation such as an EEPROM write cycle.| addr | 7-bit I2C address to probe |
| true | Device acknowledged the address |
| false | No acknowledgment (device not present, not responding, or, on SAME70, possibly a false negative; see the warning above) |
|
inline |
Read the next byte from the receive buffer.
| The | next byte of data, or 0 if no data is available |
| size_t TwoWire::read | ( | uint8_t * | pbuf, |
| size_t | maxlen ) |
Read available data into a buffer (non-standard extension).
Copies up to maxlen bytes from the receive buffer into pbuf. This is a non-standard extension not found in the Arduino Wire library.
| pbuf | Pointer to a buffer to read bytes into |
| maxlen | Maximum number of bytes to read |
| Number | of bytes copied, or 0 if no data is available |
|
inline |
Read a single byte from a device register.
Convenience wrapper around readRegN() for single-byte reads.
| dAddr | 7-bit I2C device address |
| reg | Register address to read |
| data | Reference to variable in which to store the register data |
| int TwoWire::readRegN | ( | uint8_t | dAddr, |
| uint32_t | reg, | ||
| uint8_t * | buf, | ||
| uint32_t | blen ) |
Read a number of bytes from a device register.
Performs a combined I2C write-read transaction: start → address+W → register byte → repeated-start → address+R → data bytes → stop.
There is no length limit. Reads longer than the internal 256-byte buffer are split automatically into several register reads, each continuing from the register the previous one finished at. The target must therefore auto-increment its register pointer across the whole transfer for a split read to give the same result as one long one, which is the normal behaviour for memories such as EEPROMs.
| dAddr | 7-bit I2C device address |
| reg | Register address to read |
| *buf | Pointer to buffer to store received data |
| blen | Number of bytes to read |
| int TwoWire::requestFrom | ( | uint8_t | address, |
| size_t | quantity, | ||
| bool | stop = true ) |
Request bytes from a target device.
Sends a read request to the target device and stores the response in the internal receive buffer. Use available() and read() to retrieve the received data.
If bytes have been queued with write() since beginTransmission(), they are sent first and the read is issued with a repeated start. This is how a register read is built: write the register address, then request the data. In that case the transaction stays with the beginTransmission() target and address is not consulted, since the queued bytes belong to that device.
With nothing queued, this is a plain read and address selects the device directly, so requestFrom() may be called on its own.
Expand for Example Usage
| address | 7-bit I2C address of the target device. Used when nothing has been queued with write(); otherwise the pending bytes keep the transaction on the beginTransmission() target. |
| quantity | Number of bytes to request |
| stop | If true (default), sends a stop condition after the read. If false, sends a repeated start, keeping the bus for a follow-up transaction. |
| Number | of bytes actually read and placed in the receive buffer |
| void TwoWire::reset | ( | ) |
Reset the I2C peripheral and return the object to an idle state.
Use this after a timeout or an incomplete transaction, when the bus is unresponsive. The peripheral is reset, reconfigured and re-enabled, and the object's own transaction state is cleared, so a partly finished transfer cannot leak into the next one. The bus speed, register address width and any target address set by begin() are preserved.
Does nothing if the object is not bound to a hardware module, see isValid().
Expand for Example Usage
|
inline |
Set the I2C clock speed.
Must be called before begin() to take effect. Common values:
The maximum supported speed is platform-dependent. The default is 100 kHz.
| clockbaud | Clock speed in Hz |
|
inline |
Specify the register address size for a read or write transaction.
A number of bytes, from 0 to 3, can be sent to specify an address up to 24-bit (3 bytes): 0 = none, 1 = 8-bits, 2 = 16-bits, 3 = 24-bits. Address bytes are sent most significant first.
The width applies to readRegN(), writeRegN() and the 8-bit convenience wrappers, and stays in effect until changed. If every device on the bus uses the same width, call this once after begin(). With a mix of devices, call it before each transaction.
Expand for Example Usage
| numAddressBytes | The number of address bytes to send: 0 - 3. The default value is 1 byte. |
| void TwoWire::setWireTimeout | ( | int | timeout_usec = 0, |
| bool | reset_on_timeout = false ) |
Set the transaction completion timeout.
Configures a timeout for I2C bus transactions. If a transaction does not complete within the specified time, it is aborted and endTransmission() / requestFrom() returns wire_timeout.
| timeout_usec | Timeout in microseconds (0 = disable timeout) |
| reset_on_timeout | If true, automatically calls reset() to recover the bus when a timeout occurs |
|
inline |
Queue a string for transmission.
Copies string data into the transmit buffer. If len is -1, the string length is determined automatically via strlen(). Must be called between beginTransmission() and endTransmission().
| pStr | C-style string to send |
| len | Number of bytes to send, or -1 to auto-detect length |
| Number | of bytes written to the buffer |
| size_t TwoWire::write | ( | const uint8_t * | pdata, |
| int | len ) |
Queue data bytes for transmission.
Copies data into the internal 256-byte transmit buffer. Must be called between beginTransmission() and endTransmission(). The total data queued per transaction must not exceed 256 bytes.
| pdata | Pointer to data to send |
| len | Number of bytes to queue |
| Number | of bytes written to the buffer |
|
inline |
Queue a single byte for transmission.
Convenience overload that queues one byte. Must be called between beginTransmission() and endTransmission().
Integer literals select this overload, so Wire.write(0x80) queues one byte. The lone exception is a literal 0, which is also a null pointer constant and therefore ambiguous with write(const char *, int); write a zero byte as Wire.write((uint8_t)0).
| v | Byte value to queue |
| Number | of bytes written (1 on success) |
|
inline |
Write a single byte to a device register.
Convenience wrapper around writeRegN() for single-byte writes.
| dAddr | 7-bit I2C device address |
| reg | Register address to write |
| data | Data byte to write |
| int TwoWire::writeRegN | ( | uint8_t | dAddr, |
| uint32_t | reg, | ||
| const uint8_t * | buf, | ||
| uint32_t | blen ) |
Write a number of bytes to a device register.
Performs a complete I2C write transaction: start → address+W → register byte → data bytes → stop. This is equivalent to:
Note that the register address is not auto-incremented; whether the target device increments its internal pointer is device-specific.
There is no length limit. Transfers longer than the internal 256-byte buffer are split automatically into several register transactions, each continuing from the register the previous one finished at. The target must therefore auto-increment its register pointer across the whole transfer for a split read or write to give the same result as one long one, which is the normal behaviour for memories such as EEPROMs.
Expand for Example Usage
| dAddr | 7-bit I2C device address |
| reg | Register address to write |
| *buf | Pointer to buffer containing data to write |
| blen | Number of bytes to write |