You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| 0x01 | ~TX buffer overflow~ Not Used | "Yes" | Partial if uncaught |
453
-
| 0x02 | Timeout waiting for ack of address | Yes | None |
454
-
| 0x03 | Timeout waiting for ack of data | Yes | Some, but target likely now in bad state |
452
+
| 0x01 | ~TX buffer overflow~ Not Used | "Yes" | Not Applicable |
453
+
| 0x02 | Address was not acknowledged | Yes | None |
454
+
| 0x03 | Data was not acknowledged | Yes | Some |
455
455
| 0x04 | Unknown error | Yes | Unknown |
456
-
| 0x05 | Timeout | Yes | No |
457
-
| 0x10 | Arbitration lost | No | No - wait and retry |
458
-
| 0x11 | Line held low or not pulled up| No | No. |
459
-
| 0xFF | Bus in unknown state (begin() not called?) | No | No. Bug likely yours|
456
+
| 0x05 | Timeout | Yes | Unknown |
457
+
| 0x10 | TWI in bad state| No | No, re-initialize Wire() |
458
+
| 0x11 | Likely: No Pull-ups on the lines | No | No |
459
+
| 0x12 | Arbitration lost | No | No, retry endTransmission() |
460
460
461
461
##### Handling endTransmission errors
462
462
463
-
* 0 is a success, so the ideom `if(endTransaction()) {errorhandler();}` or `uint8_t temp = endTransaction(); if (temp) {errorHandler(temp);}` should be used
463
+
* 0x00 is a success
464
464
465
-
* 1 will never be seen, because (just like in stock versions) the information that In the case of a TX buffer overflow, this is not indicated by endTransmission(). endTransmission simply transmits the portion of the buffer that fits. This condition should be detected (if your code could potentially generate it), because write() earlier returned a number smaller than the number of bytes passed to it. Error code 1 is never returned by endTransmission; we do not store an extra byte of state just to report this condition that was already reported by write(), with more complete information
466
-
467
-
* 2, A timeout waiting for the ack of address implies the chip is able to manipulate the bus pins and see the expected result (the I2C master hardware, but never saw any response from the client
468
-
* The address may be wrong. Be aware that I2C addresses have 7 bits, and that conventions for how to align the bits when representing the address (0b0AAAAAAA, which is the logical representation, and the one which we use, versus 0bAAAAAAA0, which is also used). In the opinion of this author, neither way is strictly better - the first is less confusing, but only slightly so, while the second one is the natural way to think about it if you're used to working with the I2C protocol at a very low level (when the actual address is transmitted, the address byte is, in fact, sent as 0bAAAAAAAR with the final bit indicating a read (1) or write (0), which is the main argument in favor of the second convention.
465
+
* 0x01 will never be seen, because (just like in stock versions) the information that In the case of a TX buffer overflow, this is not indicated by endTransmission(). endTransmission simply transmits the portion of the buffer that fits. This condition should be detected (if your code could potentially generate it), because write() earlier returned a number smaller than the number of bytes passed to it. Error code 1 is never returned by endTransmission; we do not store an extra byte of state just to report this condition that was already reported by write(), with more complete information
466
+
* 0x02, there was no ACK from a slave during the addressing phase.
467
+
* The address may be wrong. Be aware that I2C addresses have 7 bits, and that conventions for how to align the bits when representing the address (0b0AAAAAAA, which is the logical representation, and the one which we use, versus 0bAAAAAAA0, which is also used). In the opinion of this author, neither way is strictly better - the first is less confusing, but only slightly so, while the second one is the natural way to think about it if you're used to working with the I2C protocol at a very low level (when the actual address is transmitted, the address byte is, in fact, sent as 0bAAAAAAAR with the final bit indicating a read (1) or write (0), which is the main argument in favour of the second convention.
469
468
* What is not in question is that the fact that there are two slightly different conventions does not aid individuals working with I2C devices
470
469
* I believe that this phenomenon is likely baked into silicon (ie, that companies exist making microcontrollers where the address register is left aligned instead of right aligned.
471
-
* We always use right aligned addresses, if the address from the datasheet doesn't work, but you can't find wiring problems, if the address is even (LSB 0) try rightshifting the address one place.
472
-
* Any address 128 or higher is *definitely* left alighted, and must be rightshifted one place.
470
+
* We always use right aligned addresses, if the address from the datasheet doesn't work, but you can't find wiring problems, if the address is even (LSB 0) try right-shifting the address one place.
471
+
* Any address 128 or higher is *definitely* left alighted, and must be right-shifted one place. The library verifies this with constants and at compile-time only.
473
472
* This error can also be caused by a variety of wiring problems, including the peripheral being disconnected entirely. Another very simple I2C device on the bus that's easy to talk to can help by allowing you to verify that any wiring error could only be confined to the connection between the SDA and SCL bus lines, and the corresponding pins on slave device that is not cooperating (and anything in it's path (such as a bidirectional level shifter - which may not have been connected properly, or may be designed only for shifting between 3.3 and 5v levels (this will be obvious measuring the data line on either side of the level shifter with the 'scope )
474
-
* 3, A timeout waiting for the ack of data is mysterious. It typically implies that a device, likely the one addressed, choked on whatever it was sent and collapsed on top of the SCL and SDA lines. After this error occurs, you may find that one or both of the I2C lines are held low. If this is resolved while disconnecting the SCL and SDA pins from the device you were talking to, this would provide positive proof that the cause was the device getting into a bad state, likely because you missed a key detail in the datasheet.
475
-
* 4, unknown error, indicates an error not otherwise specified. As suggested by the name, the cause and corrective actions should it occur are unknown to the writer of this document.
476
-
* 5, timeout, indicated a timeout waiting for the bus to return to idle state. This may imply that some device is malfunctioning and refusing to release pins.
477
-
* 0x10, Arbitration lost, indicates that it attempted to start sending, but must have started at the exact moment another master did. As I2C checks the state of the lines as it's sending data (necessary considering it's nature as a multidrop bus with two bidirectional lines) The master became aware of this when it attempted to transmit a high level, but saw that the line did not rise, indicating something else was holding it down, which must be another masterIn the case of Arbitration loss, that means on a multimaster bus, another device started transmitting at the same moment. At the first bit where the addresses being targeted by the respective masters differed, the master who was tying to output a 1, but can't because the line is held low by the other master, notices that the line isn't at the voltage its' supposed to be at, and deduces that it has lost arbitration. No data was sent.
478
-
* 0x11 indicates a line-state error (SCL and SDA were not both high), implying missing or insufficient external pullups, a device on the bus in a bad state holding SDA and/or SCL low eternally, or a simple short between ground and one or both lines. No data could be sent with the linesin this state.
479
-
Line held low or not pulled up indicates one of the following are true of SCL and/or SDA; a multimeter will instantly tell you which line is hung. I
473
+
* 0x03, data was NACK'd. The specification allows slaves to issue a NACK on the last byte of a transmission or if it can't receive any more data. If the NACK happens on the last byte to be transferred, this error is NOT issued, but a success. On any other transfer this error will be issued. This is likely caused by a wrong payload.
474
+
* 0x04, unknown error, indicates an error not otherwise specified. As suggested by the name, the cause and corrective actions should it occur are unknown to the writer of this document.
475
+
* 0x05, timeout, indicated a timeout waiting for the bus to return to idle state. This may imply that some device is malfunctioning and refusing to release pins.
476
+
* 0x10, the TWI Module was uninitialized or in an other wise unrecoverable state, please call .end() with a new .begin() .
477
+
* 0x11 indicates a line-state error (SCL and/or SDA were not both high), implying missing or insufficient external pullups, a device on the bus in a bad state holding SDA and/or SCL low eternally, or a simple short between ground and one or both lines. No data could be sent with the lines in this state.
478
+
Line held low or not pulled up indicates one of the following are true of SCL and/or SDA; a multimeter will instantly tell you which line is hung.
480
479
* Pullup resistors are missing. Pullups are mandatory as discussed at lengths elsewhere here.
481
480
* A soldering error has accidentally shorted one of both of those lines to ground
482
481
* A I2C slave device is in a bad state.
483
482
* This is nearly always the fault of your code or your hardware.
484
483
* You didn't leave the data lines connected and try to save power by disconnecting them from Vcc while leaving the bus pulled up did you? Very few devices will resume function correctly after this, and could potentially be damaged.
485
484
* Sending bogus commands to some devices will hang them make them hang, crash, or sit on the data and/or clock lines until powercycled.
486
-
After determining the line that's stuck, start disconnecting the I2C devices (if possible) with power still on and multimeter monitoring the stuck line. At some point, it will llikely return to HIGH after removing something. Now plug everything else back in and make sure one the others isn't holding the line low (if power has not been removed, and reconnecing a device drags the line back down again, disconnect it entirely and reconnect it - line till low indicates wiring or soldering defect or bad part connected, as it should not ever drag the line down without being addressed by the master)
487
-
485
+
*After determining the line that's stuck, start disconnecting the I2C devices (if possible) with power still on and multimeter monitoring the stuck line. At some point, it will llikely return to HIGH after removing something. Now plug everything else back in and make sure one the others isn't holding the line low (if power has not been removed, and reconnecing a device drags the line back down again, disconnect it entirely and reconnect it - line till low indicates wiring or soldering defect or bad part connected, as it should not ever drag the line down without being addressed by the master)
486
+
* 0x12, Arbitration lost, indicates that it attempted to start sending, but must have started at the exact moment another master did. As I2C checks the state of the lines as it's sending data (necessary considering it's nature as a multidrop bus with two bidirectional lines) The master became aware of this when it attempted to transmit a high level, but saw that the line did not rise, indicating something else was holding it down, which must be another masterIn the case of Arbitration loss, that means on a multimaster bus, another device started transmitting at the same moment. At the first bit where the addresses being targeted by the respective masters differed, the master who was tying to output a 1, but can't because the line is held low by the other master, notices that the line isn't at the voltage its' supposed to be at, and deduces that it has lost arbitration. No data was sent. A simple reissue of .endTransmission() is enough to try to resend the data in this case.
488
487
489
488
### Methods that have their standard behaviour
490
489
The implementation isn't identical, but the behaviour is unchanged, or is different only in an irrelevant and implicitly convertible return or argument type.
author=@MX682X, with contributions by @SpenceKonde. Original library, mostly reimplemented, was by Arduino.
4
4
maintainer=Spence Konde <spencekonde@gmail.com>
5
5
sentence=This library allows you to communicate with I2C devices, acting as either a master, slave, or both master and slave.
6
-
paragraph=2.0.12 - Correct bug in checkPinLevels. Previously VPORTs were used on non-tiny parts, even though the port was not known at compile time, generating code with no advantages and demonstrating what was undeniably an anitpattern. PORT registers are now used except on tinyAVR.I2C, also known as IIC (or, for trademark reasons, TWI) stands for Inter-Integrated-Circuit. It is a two wire bus which can have a number of devices limited only by the overall bus capacitance. The two wires are both open drain: SCL (clock) and SDA (data) lines. During every transfer, a device operates as either a master (or "host") or slave (or "client"). Devices either drive these pins LOW or let them float, and they must be pulled up to a voltage recognized as a logic HIGH by all devices using external resistors. For testing purposes only, we provide usePullups() to enable the internal ones. The internal pullups are less than 1/3rd the strength required by the standard, and I2C may not operate reliably or at all with only internal pullups, but in simple cases, it can be used as a quick test to see if the problem is missing external pullups (if calling Wire.usePullups() fixes a problem, remove that line and correctly install external resistors). Common slave devices include temperature sensors, realtime clocks, EEPROMs and all manner of sensors. The Wire library can act as either a master or a slave device, and as of DxCore/megaTinyCore versions with the reimplemented Wire 2.0.0, can operate as both at the same time (in what is called a multi-master topology). This must be enabled from the tools submenu. Refer to the library README for detailed information about speed, limitations, pullup sizing, and enhancements to slave mode (multiple addresses, and a way to see how much the master read, enabling Wire slaves to behave more like commercial devices. Older versions, without that feature, could not implement the "register model" which is ubiquitous in commercial I2C devices. <br/> This enhanced Wire library supports the tinyAVR 0/1/2-series, megaAVR 0-series and AVR Dx-series parts. It is part of megaTinyCore and DxCore, and the library distributed with the two packages differs only in the documentation, since not all options are available on tinyAVR. <br/> Version History: <br/> Correct a regression introduced in 2.0.9 (1.5.x DxC, 2.6.x mTC) impacting master-and-slave mode. <br/>2.0.9 Implement a protection against soft-locking TWI with Stand-by/Power-down sleep<br/>2.0.8 Do away with multiple signatures for requestFrom. When they worked, it was no better than it is now, but when it didn't it wouldn't compile at all, breaking some libraries. Other assorted improvements from @MX682X. <br/>2.0.6 - Improved baud calculation. <br/>2.0.5 - Better fix for buffer issue. <br/>2.0.4 - Change buffer size as emergency fix to ensure 32b of buffer is always available. <br/>2.0.3 - Make endTransmission give correct status codes (0 = success) as return values, instead of the count of bytes. Document change. <br/>2.0.2 - Add the last two missing functions. <br/>2.0.0: Wire Master & Slave support and near total rewrite. Massive flash savings realized as well!
6
+
paragraph=<br/>2.0.13 - Clarifying errors in Readme, allow easy retransmission on bus arbitration. The Wire library can act as either a master or a slave device, and as of DxCore/megaTinyCore versions with the reimplemented Wire 2.0.0, can operate as both at the same time (in what is called a multi-master topology). This must be enabled from the tools submenu. Refer to the library README for detailed information about speed, limitations, pullup sizing, and enhancements to slave mode (multiple addresses, and a way to see how much the master read, enabling Wire slaves to behave more like commercial devices. Older versions, without that feature, could not implement the "register model" which is ubiquitous in commercial I2C devices. <br/> This enhanced Wire library supports the tinyAVR 0/1/2-series, megaAVR 0-series and AVR Dx-series parts. It is part of megaTinyCore and DxCore, and the library distributed with the two packages differs only in the documentation, since not all options are available on tinyAVR. <br/> Version History: <br/>2.0.12 Correct some issues in some functions. <br/>2.0.10: Correct a regression introduced in 2.0.9 (1.5.x DxC, 2.6.x mTC) impacting master-and-slave mode. <br/>2.0.9 Implement a protection against soft-locking TWI with Stand-by/Power-down sleep<br/>2.0.8 Do away with multiple signatures for requestFrom. When they worked, it was no better than it is now, but when it didn't it wouldn't compile at all, breaking some libraries. Other assorted improvements from @MX682X. <br/>2.0.6 - Improved baud calculation. <br/>2.0.5 - Better fix for buffer issue. <br/>2.0.4 - Change buffer size as emergency fix to ensure 32b of buffer is always available. <br/>2.0.3 - Make endTransmission give correct status codes (0 = success) as return values, instead of the count of bytes. Document change. <br/>2.0.2 - Add the last two missing functions. <br/>2.0.0: Wire Master & Slave support and near total rewrite. Massive flash savings realized as well!
0 commit comments