arduino / arduino/reference-en

Comment on `Wire.read()` reference: "slave may send less than requested" is misleading

Open
#893 2 comments 0 reactions 0 assignees View on GitHub
bug
Dominant language
No language data
Stars
173
Forks
704
PR merge metrics
No merged PRs in 30d

Description

In the documentation of [Wire.read()](https://www.arduino.cc/en/Reference/WireRead) is this example:
```
#include

void setup()
{
Wire.begin(); // join i2c bus (address optional for master)
Serial.begin(9600); // start serial for output
}

void loop()
{
Wire.requestFrom(2, 6); // request 6 bytes from slave device arduino/Arduino#2

while(Wire.available()) // slave may send less than requested
{
char c = Wire.read(); // receive a byte as character
Serial.print(c); // print the character
}

delay(500);
}
```
The comment "slave may send less than requested" is misleading.
Some might think that they have to wait for the rest of the bytes to arrive. Some might think that the Slave can decide to send less bytes, even when there was no bus error.

It is however inherit to the I2C protocol that the Slave can not send less or more than requested. If the Slave stops sending data, then the SDA will stay high and the Master will read 0xFF. The Master will continue to read all the bytes and does not know that the 0xFF is not valid data from the Slave. When reading data from a Slave, the Master provides the SCL clock signal, the ACK between the data bytes and the STOP at the end. The Slave has no way to influence that.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start from the linked Wire.read() reference page and inspect the example containing the “slave may send less than requested” comment. Check the wording against the documented behavior of Wire.requestFrom() and Wire.read(); done means the example no longer suggests that a slave can arbitrarily send fewer bytes or that a reader should wait for more data.

Written by the indexing model from the issue text.

Assessment

Tech stack
arduino
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.