Go Down

Topic: Documentation Bug in SPI Reference (Read 2054 times) previous topic - next topic

olikraus

Aug 21, 2016, 08:59 am Last Edit: Aug 21, 2016, 09:35 am by olikraus
I refer to the first table (SPI Modes) on this page: https://www.arduino.cc/en/Reference/SPI

Problem: In the last column (output edge) the lower two entries have to be swapped.

The correct table should be:
SPI_MODE0: CPOL=0, CPHA=0, data out on falling clock, data sample on rising clock
SPI_MODE1: CPOL=0, CPHA=1, data out on rising clock, data sample on falling clock
SPI_MODE2: CPOL=1, CPHA=0, data out on rising clock, data sample on falling clock
SPI_MODE3: CPOL=1, CPHA=1, data out on falling clock, data sample on rising clock


Source: www.corelis.com

Somre more notes from my side:
- The internet is full of descriptions for these modes and many of them are different. Especially the last two modes are often exchanged (as also happend on the Arduino Reference)
- We should document the behavior of the Arduino Boards (Which currently differs from the table on the SPI reference page)
- The table on the reference page includes the column for the data output. However this is misleading, because the first data output has to happen without clock edge in modes 0 and 2.
- I think it is more important to mention the time when the data is sampled from the client.
- A picture would be helpful here too...
- Finally: I think this topic is very important. I spent days on this topic and had to apply all the modern measure equipment to figure out the problem in my hardware setup.

 
Thanks,
Oliver




olikraus

I took some screenshots from Arduino Uno, Due and 101 boards with the following code:

Code: [Select]

#include <SPI.h>
void setup() {
  SPI.begin();
}
void loop() {
  SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE0));
  SPI.transfer(0x053);
  SPI.endTransaction();
  delayMicroseconds(1);
  SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE1));
  SPI.transfer(0x053);
  SPI.endTransaction();
  delayMicroseconds(1);
  SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE2));
  SPI.transfer(0x053);
  SPI.endTransaction();
  delayMicroseconds(1); 
  SPI.beginTransaction(SPISettings(1000000, MSBFIRST, SPI_MODE3));
  SPI.transfer(0x053);
  SPI.endTransaction();
  delayMicroseconds(16*8);
}


The byte 0x053 (bit pattern 01010011) is sent via SPI in all four modes. From left to right SPI Mode 0, 1, 2 and 3.
Please look at the attached screenshots from my scope.
You can see that (1) all three plattforms behave in the same way and (2) that the output data is changed on the falling edge of the clock signal for mode 0 and 3 (and not for mode 0 and 2 as mentioned on the SPI reference page).

Oliver

Robin2

Alas, the people who maintain the documentation never seem to read this Forum.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

olikraus

Alas, the people who maintain the documentation never seem to read this Forum.

...R
But they refer to exactly this forum  :smiley-confuse:

Oliver

olikraus

Here es one more update: Ich checked the ESP8266 output and it seems, that the ESP8266 deviates from the other three boards. It looks like that SPI Modes 2 and 3 are swapped (see attachment)

This is bad, because .ino files will not be portable with respect to SPI Modes 2 and 3.

Oliver

pert

#5
Aug 21, 2016, 12:32 pm Last Edit: Aug 21, 2016, 12:35 pm by pert
You have to submit an issue report on the Arduino IDE GitHub repository: https://github.com/arduino/Arduino/issues if you want the web team to see this.
Please do some searching first to make sure it hasn't already been reported.

I get better results when I provide the full text of the suggested change so they can just copy and paste it over to the documentation.

The ESP8266 issue should be reported to https://github.com/esp8266/Arduino/issues, not the Arduino IDE repository.

EDIT: I just noticed you already reported the issue to ESP8266: https://github.com/esp8266/Arduino/issues/2416. Thanks!

olikraus

pert,
Thanks for the information. I will use the Arduino Issue tracker.

Oliver

olikraus

#7
Aug 21, 2016, 01:53 pm Last Edit: Aug 21, 2016, 01:55 pm by olikraus
For reference: I have created an issue for this:

 https://github.com/arduino/Arduino/issues/5273

Oliver

Robin2

You have to submit an issue report on the Arduino IDE GitHub repository: https://github.com/arduino/Arduino/issues if you want the web team to see this.
It really p*sses me off that this is necessary when there is a perfectly good Forum here if the Arduino folks would just take the trouble to participate.

...R
Two or three hours spent thinking and reading documentation solves most programming problems.

pert

An issue tracker is actually a much better way to handle it than the forum because they can assign someone to it and then close the issue when it's fixed. The problem is that all the links point people to report issues to the forum where they will just get ignored unless someone in the know moves them over to the tracker. I try to do that for anything that I can verify but there's a lot of stuff like this issue that I wouldn't feel comfortable doing that for.

In this case it makes sense to report the issue in the Arduino IDE repository because it's a problem with the documentation for an Arduino AVR Boards library and that core is part of the IDE repository but there are other website issues that aren't really relevant to that repository. I end up reporting those to the IDE repository anyway because there's no other place to do so. The developers have never had a problem with that, even though I've asked in several reports if there was a better place to submit the issue. It might be better if they would create a separate repository just for those sorts of issues, similar to the forum-issues repository.

olikraus

Yes, I fully agree. I just wanted to follow the suggested way of issue reporting.

Oliver

Robin2

#11
Aug 21, 2016, 08:08 pm Last Edit: Aug 21, 2016, 08:09 pm by Robin2
An issue tracker is actually a much better way to handle it than the forum because they can assign someone to it and then close the issue when it's fixed.
I don't dispute that. But they can easily pick up the issues from this Forum and assign them to the issue tracker themselves. I don't see why we have to do that for them - we give enough of our free time already.

If they participated in the Forum we could have some discussion and feedback about what issues are important and which ones can be dealt with later.


...R
Two or three hours spent thinking and reading documentation solves most programming problems.

olikraus

Actually I do not mind how and where an issue is created. However if they suggest to post it here, then indeed someone from the doc team should whatch the forum. Or the wiki pages should refer directly to the github tracker.

Oliver

Go Up