Document SPI transactions and SPISettings

[damellis]

These were added recently but I didn't see any documentation for them.

[PaulStoffregen]

If it would help, you're welcome to use anything from my page's documentation.

http://www.pjrc.com/teensy/td_libs_SPI.html

[svgeesus]

Hello David,

Monday, February 16, 2015, 11:05:03 PM, you wrote:

These were added recently but I didn't see any documentation for them.

I would be happy to add documentation for those but I don't see SPI in
the recently released documentation-en github repo (just a couple of
mentions of software SPI):

Chris@M6700 /cygdrive/d/Arduino/reference-en-master
$ find . -type f -exec grep SPI {} ;
Note: this is a software implementation; Arduino also provides an link:SPI{ext-relative}[SPI library] that uses the hardware implementation, which is faster but only works on specific pins.

• #LANGUAGE# link:SPI{ext-relative}[SPI]
  This is a software implementation; see also the link:SPI{ext-relative}[SPI library], which provides a hardware implementation that is faster but works only on specific pins.
• #LANGUAGE# link:SPI{ext-relative}[SPI]

Best regards,
Nantonos mailto:nantonos@epona.net

[agdl]

@Nantonos we haven't write them yet. But if you wanna make these docs you are very welcome!

[PaulStoffregen]

The reference-en repository does not seem to correspond to the actual reference web pages. It only has a small fraction of the content that's on the web.

It's also clearly not the same. For example, this page on the website documents addition, substraction, multiplication and division:

http://arduino.cc/en/Reference/Arithmetic

In the reference-en repository, those are 4 separate pages:

https://github.com/arduino/reference-en/blob/master/Language/Structure/Arithmetic%20Operators/addition.adoc
https://github.com/arduino/reference-en/blob/master/Language/Structure/Arithmetic%20Operators/subtraction.adoc
https://github.com/arduino/reference-en/blob/master/Language/Structure/Arithmetic%20Operators/multiplication.adoc
https://github.com/arduino/reference-en/blob/master/Language/Structure/Arithmetic%20Operators/division.adoc

It's pretty clearly not the content for the website which most user read to learn the Arduino API.

Is there another place to access and contribute directly to the context that is actually published on the website?

[agdl]

@PaulStoffregen we are still working on that repo. The repo will completely substitute the system used now. So if you want to include documentation you are very welcome to make a PR in that repo! When all the system will be completed everything on the repository will be pushed online in the arduino.cc site

[PaulStoffregen]

Can we update the actual web site sooner, rather than later when a new but sparsely populated repo eventually replaces the current system?

[PaulStoffregen]

I would like to point out how much damage the lack of SPI transactions has done to Arduino's reputation over the last 2 years. Common wisdom has grown on forums, online communities, in hackerspaces and elsewhere, that Arduino is a toy system incapable of handling more than one or two real devices, that more complex projects should be done with a Linux-based system like Raspberry Pi.

Arduino has lost massive market share to Raspberry Pi. Despite the complexity of Linux, many people believe it's a necessary burden when dealing with multiple devices. Arduino has earned a terrible reputation, and most of Arduino's design failure for hobbyists building more complex projects is due to SPI libraries like Ethernet and SD crashing when used together with SPI-based radio modules like RFM69 and CC3000.

I wrote the SPI transaction stuff almost 1 year ago. Only now is it finally published in a non-beta release. That's a terrible lag for something so important.

Now you're saying documentation on this feature, which can finally allow combinations of SPI-based libraries to work together, should be pushed to a new system that's not ready to be used yet.

I'm very frustrated by what seems to be a complete lack of urgency on Arduino's part. Don't you care about Arduino as a platform? Do you have any idea how many forum threads and online conversations have already concluded with the understanding that Arduino as a platform is simply not up to the task of using multiple modern SPI devices?

[q2dg]

Well...is this documentation ready yet?

[agdl]

I'm still working on them. I have to link the example and the new methods in the old ones. But they are already online. Keep in touch. Thank you Paul.

http://arduino.cc/en/Reference/SPISettings
http://arduino.cc/en/Reference/SPIbeginTransaction
http://arduino.cc/en/Reference/SPIendTransaction
http://arduino.cc/en/Reference/SPIusingInterrupt

[agdl]

Please give a check and let me know what to improve if needed. In this way we can finally close this issue

[damellis]

It might be worth explaining the effect of usingInterrupt() in a bit more
detail: e.g. "The interrupt specified in the call to usingInterrupt() will
be disabled on a call to beginTransaction() and re-enabled in
endTransaction()" (or something along those lines). Someone with more
knowledge of the transactions code please correct me if that's not actually
what happens.

Also, I would give the units for speed on the SPISettings page.

Finally, it might be good to include an example showing the use of those
functions together in one code sample.

On Fri, Apr 10, 2015 at 8:52 AM, Arturo Guadalupi notifications@github.com
wrote:

Please give a check and let me know what to improve if needed. In this way
we can finally close this issue

—
Reply to this email directly or view it on GitHub
#2654 (comment).

[agdl]

@damellis the example is here except for the usinf of UseInterrupt
http://arduino.cc/en/Tutorial/SPITransaction

[agdl]

I'm closing this. Let me know if something else must be updated

[svgeesus]

Just checking that I understand here. The documentation is not in a repo, so no-one can help improve it. The online documentation has been updated, in the most terse manner possible, and ignoring (most of the) feedback given in this issue. The only example is in a tutorial, which is also not in a repo, and is not linked from the documentation. Thus, issue closed. Astonishing.