Arduino Forum

Development => Other Software Development => Topic started by: olikraus on Aug 21, 2016, 08:59 am

Title: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 08:59 am
I refer to the first table (SPI Modes) on this page: https://www.arduino.cc/en/Reference/SPI (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

(http://www.corelis.com/images/screenshots/spi-bus-timing.jpg)
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



Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 09:20 am
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
Title: Re: Documentation Bug in SPI Reference
Post by: Robin2 on Aug 21, 2016, 10:11 am
Alas, the people who maintain the documentation never seem to read this Forum.

...R
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 10:52 am
Alas, the people who maintain the documentation never seem to read this Forum.

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

Oliver
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 10:56 am
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
Title: Re: Documentation Bug in SPI Reference
Post by: pert on Aug 21, 2016, 12:32 pm
You have to submit an issue report on the Arduino IDE GitHub repository: https://github.com/arduino/Arduino/issues (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 (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 (https://github.com/esp8266/Arduino/issues/2416). Thanks!
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 01:29 pm
pert,
Thanks for the information. I will use the Arduino Issue tracker.

Oliver
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 01:53 pm
For reference: I have created an issue for this:

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

Oliver
Title: Re: Documentation Bug in SPI Reference
Post by: Robin2 on Aug 21, 2016, 02:01 pm
You have to submit an issue report on the Arduino IDE GitHub repository: https://github.com/arduino/Arduino/issues (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
Title: Re: Documentation Bug in SPI Reference
Post by: pert on Aug 21, 2016, 02:14 pm
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 (https://github.com/arduino/forum-issues) repository.
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 04:44 pm
Yes, I fully agree. I just wanted to follow the suggested way of issue reporting.

Oliver
Title: Re: Documentation Bug in SPI Reference
Post by: Robin2 on Aug 21, 2016, 08:08 pm
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
Title: Re: Documentation Bug in SPI Reference
Post by: olikraus on Aug 21, 2016, 09:23 pm
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