From a6035d7ef4b944998deafadb12df6f5677f0045b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Wed, 19 Jan 2022 15:50:55 +0100 Subject: [PATCH 1/2] Migrate & convert SPI docs from older platform --- Language/Functions/Communication/SPI.adoc | 52 +++++++++++++++++++ .../Communication/SPI/SPISettings.adoc | 42 +++++++++++++++ .../Functions/Communication/SPI/begin.adoc | 33 ++++++++++++ .../Communication/SPI/beginTransaction.adoc | 33 ++++++++++++ Language/Functions/Communication/SPI/end.adoc | 33 ++++++++++++ .../Communication/SPI/endTransaction.adoc | 33 ++++++++++++ .../Communication/SPI/setBitOrder.adoc | 35 +++++++++++++ .../Communication/SPI/setClockDivider.adoc | 47 +++++++++++++++++ .../Communication/SPI/setDataMode.adoc | 41 +++++++++++++++ .../Functions/Communication/SPI/transfer.adoc | 40 ++++++++++++++ .../Communication/SPI/usingInterrupt.adoc | 33 ++++++++++++ 11 files changed, 422 insertions(+) create mode 100644 Language/Functions/Communication/SPI.adoc create mode 100644 Language/Functions/Communication/SPI/SPISettings.adoc create mode 100644 Language/Functions/Communication/SPI/begin.adoc create mode 100644 Language/Functions/Communication/SPI/beginTransaction.adoc create mode 100644 Language/Functions/Communication/SPI/end.adoc create mode 100644 Language/Functions/Communication/SPI/endTransaction.adoc create mode 100644 Language/Functions/Communication/SPI/setBitOrder.adoc create mode 100644 Language/Functions/Communication/SPI/setClockDivider.adoc create mode 100644 Language/Functions/Communication/SPI/setDataMode.adoc create mode 100644 Language/Functions/Communication/SPI/transfer.adoc create mode 100644 Language/Functions/Communication/SPI/usingInterrupt.adoc diff --git a/Language/Functions/Communication/SPI.adoc b/Language/Functions/Communication/SPI.adoc new file mode 100644 index 00000000..b77499d5 --- /dev/null +++ b/Language/Functions/Communication/SPI.adoc @@ -0,0 +1,52 @@ +--- +title: SPI +categories: [ "Functions" ] +subCategories: [ "Communication" ] +--- + + += SPI + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + + +This library allows you to communicate with SPI devices, with the Arduino as the controller device. This library is bundled with every Arduino platform (avr, megaavr, mbed, samd, sam, arc32), so *you do not need to install* the library separately. + +To use this library + +`#include ` + +To read more about Arduino and SPI, you can visit the https://docs.arduino.cc/learn/communication/spi[Arduino & Serial Peripheral Interface (SPI)] guide. + +-- +// OVERVIEW SECTION ENDS + + +// FUNCTIONS SECTION STARTS +[#functions] +-- + +''' + +[float] +=== Functions +link:../SPI/SPISettings[SPISettings] + +link:../SPI/begin[begin()] + +link:../SPI/beginTransaction[beginTransaction()] + +link:../SPI/end[end()] + +link:../SPI/setBitOrder[setBitOrder()] + +link:../SPI/setClockDivider[setClockDivider()] + +link:../SPI/setDataMode[setDataMode()] + +link:../SPI/transfer[transfer()] + +link:../SPI/usingInterrupt[usingInterrupt()] + +''' + +-- +// SEEALSO SECTION ENDS diff --git a/Language/Functions/Communication/SPI/SPISettings.adoc b/Language/Functions/Communication/SPI/SPISettings.adoc new file mode 100644 index 00000000..d8c7351a --- /dev/null +++ b/Language/Functions/Communication/SPI/SPISettings.adoc @@ -0,0 +1,42 @@ +--- +title: SPISettings +--- + += SPISettings + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `SPISettings` object is used to configure the SPI port for your SPI device. All 3 parameters are combined to a single `SPISettings` object, which is given to `SPI.beginTransaction()`. + +When all of your settings are constants, SPISettings should be used directly in `SPI.beginTransaction()`. See the syntax section below. For constants, this syntax results in smaller and faster code. + +If any of your settings are variables, you may create a SPISettings object to hold the 3 settings. Then you can give the object name to SPI.beginTransaction(). Creating a named SPISettings object may be more efficient when your settings are not constants, especially if the maximum speed is a variable computed or configured, rather than a number you type directly into your sketch. + +[float] +=== Syntax +`SPI.beginTransaction(SPISettings(14000000, MSBFIRST, SPI_MODE0))` +Note: Best if all 3 settings are constants + +`SPISettings mySettting(speedMaximum, dataOrder, dataMode)` +Note: Best when any setting is a variable'' + + +[float] +=== Parameters +`speedMaximum`: The maximum speed of communication. For a SPI chip rated up to 20 MHz, use 20000000. + +`dataOrder`: MSBFIRST or LSBFIRST + +`dataMode`: SPI_MODE0, SPI_MODE1, SPI_MODE2, or SPI_MODE3 + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/begin.adoc b/Language/Functions/Communication/SPI/begin.adoc new file mode 100644 index 00000000..757e57c6 --- /dev/null +++ b/Language/Functions/Communication/SPI/begin.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.begin() +--- + += SPI.begin() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Initializes the SPI bus by setting SCK, MOSI, and SS to outputs, pulling SCK and MOSI low, and SS high. + + +[float] +=== Syntax +`SPI.begin()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/beginTransaction.adoc b/Language/Functions/Communication/SPI/beginTransaction.adoc new file mode 100644 index 00000000..6c9f63b7 --- /dev/null +++ b/Language/Functions/Communication/SPI/beginTransaction.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.beginTransaction() +--- + += SPI.beginTransaction() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Initializes the SPI bus using the defined link:SPISettings[SPISettings]. + + +[float] +=== Syntax +`SPI.beginTransaction(mySettings)` + + +[float] +=== Parameters +mySettings: the chosen settings according to link:SPISettings[SPISettings]. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/end.adoc b/Language/Functions/Communication/SPI/end.adoc new file mode 100644 index 00000000..76eef802 --- /dev/null +++ b/Language/Functions/Communication/SPI/end.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.end() +--- + += SPI.end() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Disables the SPI bus (leaving pin modes unchanged). + + +[float] +=== Syntax +`SPI.end()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/endTransaction.adoc b/Language/Functions/Communication/SPI/endTransaction.adoc new file mode 100644 index 00000000..4bf8ec89 --- /dev/null +++ b/Language/Functions/Communication/SPI/endTransaction.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.endTransaction() +--- + += SPI.endTransaction() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Stop using the SPI bus. Normally this is called after de-asserting the chip select, to allow other libraries to use the SPI bus. + + +[float] +=== Syntax +`SPI.endTransaction()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setBitOrder.adoc b/Language/Functions/Communication/SPI/setBitOrder.adoc new file mode 100644 index 00000000..b1e09d26 --- /dev/null +++ b/Language/Functions/Communication/SPI/setBitOrder.adoc @@ -0,0 +1,35 @@ +--- +title: SPI.setBitOrder() +--- + += SPI.setBitOrder() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the order of the bits shifted out of and into the SPI bus, either LSBFIRST (least-significant bit first) or MSBFIRST (most-significant bit first). + + +[float] +=== Syntax +`SPI.setBitOrder(order)` + + +[float] +=== Parameters +order: either LSBFIRST or MSBFIRST + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setClockDivider.adoc b/Language/Functions/Communication/SPI/setClockDivider.adoc new file mode 100644 index 00000000..2aad770e --- /dev/null +++ b/Language/Functions/Communication/SPI/setClockDivider.adoc @@ -0,0 +1,47 @@ +--- +title: SPI.setClockDivider() +--- + += SPI.setClockDivider() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the SPI clock divider relative to the system clock. On AVR based boards, the dividers available are 2, 4, 8, 16, 32, 64 or 128. The default setting is SPI_CLOCK_DIV4, which sets the SPI clock to one-quarter the frequency of the system clock (4 Mhz for the boards at 16 MHz). + +*For Arduino Due:* On the Due, the system clock can be divided by values from 1 to 255. The default value is 21, which sets the clock to 4 MHz like other Arduino boards. + + +[float] +=== Syntax +`SPI.setClockDivider(divider)` + + +[float] +=== Parameters + +divider (only AVR boards): +* SPI_CLOCK_DIV2 +* SPI_CLOCK_DIV4 +* SPI_CLOCK_DIV8 +* SPI_CLOCK_DIV16 +* SPI_CLOCK_DIV32 +* SPI_CLOCK_DIV64 +* SPI_CLOCK_DIV128 + +chipSelectPin: peripheral device CS pin (Arduino Due only) +divider: a number from 1 to 255 (Arduino Due only) + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setDataMode.adoc b/Language/Functions/Communication/SPI/setDataMode.adoc new file mode 100644 index 00000000..4a0472fa --- /dev/null +++ b/Language/Functions/Communication/SPI/setDataMode.adoc @@ -0,0 +1,41 @@ +--- +title: SPI.setDataMode() +--- + += SPI.setDataMode() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the SPI data mode: that is, clock polarity and phase. See the Wikipedia article on http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus:[SPI] for details. + +[float] +=== Syntax +`SPI.setDataMode(mode)` + + +[float] +=== Parameters + +mode: + +* SPI_MODE0 +* SPI_MODE1 +* SPI_MODE2 +* SPI_MODE3 + + +chipSelectPin - peripheral device CS pin (Arduino Due only) + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/transfer.adoc b/Language/Functions/Communication/SPI/transfer.adoc new file mode 100644 index 00000000..ff59a3b3 --- /dev/null +++ b/Language/Functions/Communication/SPI/transfer.adoc @@ -0,0 +1,40 @@ +--- +title: SPI.transfer() +--- + += SPI.transfer() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +SPI transfer is based on a simultaneous send and receive: the received data is returned in receivedVal (or receivedVal16). In case of buffer transfers the received data is stored in the buffer in-place (the old data is replaced with the data received). + +[float] +=== Syntax + +`receivedVal = SPI.transfer(val)` + +`receivedVal16 = SPI.transfer16(val16)` + +`SPI.transfer(buffer, size)` + + +[float] +=== Parameters + +* val: the byte to send out over the bus +* val16: the two bytes variable to send out over the bus +* buffer: the array of data to be transferred + + +[float] +=== Returns +The received data. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/usingInterrupt.adoc b/Language/Functions/Communication/SPI/usingInterrupt.adoc new file mode 100644 index 00000000..7769ba39 --- /dev/null +++ b/Language/Functions/Communication/SPI/usingInterrupt.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.usingInterrupt() +--- + += SPI.usingInterrupt() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +If your program will perform SPI transactions within an interrupt, call this function to register the interrupt number or name with the SPI library. This allows `SPI.beginTransaction()` to prevent usage conflicts. Note that the interrupt specified in the call to usingInterrupt() will be disabled on a call to `beginTransaction()` and re-enabled in `endTransaction().` + +[float] +=== Syntax + +`SPI.usingInterrupt(interruptNumber)` + + +[float] +=== Parameters + +interruptNumber: the associated interrupt number. + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + From b92545196f62f1ce4b6385419b10a84e9ebba6b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karl=20S=C3=B6derby?= <35461661+karlsoderby@users.noreply.github.com> Date: Fri, 21 Jan 2022 17:59:12 +0100 Subject: [PATCH 2/2] Update links with lowercase --- Language/Functions/Communication/SPI.adoc | 18 +++++++++--------- .../Communication/SPI/SPISettings.adoc | 3 ++- .../Communication/SPI/beginTransaction.adoc | 4 ++-- .../Communication/SPI/setBitOrder.adoc | 2 +- .../Communication/SPI/setClockDivider.adoc | 7 ++++--- .../Communication/SPI/setDataMode.adoc | 2 +- 6 files changed, 19 insertions(+), 17 deletions(-) diff --git a/Language/Functions/Communication/SPI.adoc b/Language/Functions/Communication/SPI.adoc index b77499d5..7d8f8203 100644 --- a/Language/Functions/Communication/SPI.adoc +++ b/Language/Functions/Communication/SPI.adoc @@ -36,15 +36,15 @@ To read more about Arduino and SPI, you can visit the https://docs.arduino.cc/le [float] === Functions -link:../SPI/SPISettings[SPISettings] + -link:../SPI/begin[begin()] + -link:../SPI/beginTransaction[beginTransaction()] + -link:../SPI/end[end()] + -link:../SPI/setBitOrder[setBitOrder()] + -link:../SPI/setClockDivider[setClockDivider()] + -link:../SPI/setDataMode[setDataMode()] + -link:../SPI/transfer[transfer()] + -link:../SPI/usingInterrupt[usingInterrupt()] +link:../spi/spisettings[SPISettings] + +link:../spi/begin[begin()] + +link:../spi/begintransaction[beginTransaction()] + +link:../spi/end[end()] + +link:../spi/setbitorder[setBitOrder()] + +link:../spi/setclockdivider[setClockDivider()] + +link:../spi/setdatamode[setDataMode()] + +link:../spi/transfer[transfer()] + +link:../spi/usinginterrupt[usingInterrupt()] ''' diff --git a/Language/Functions/Communication/SPI/SPISettings.adoc b/Language/Functions/Communication/SPI/SPISettings.adoc index d8c7351a..a0586c8b 100644 --- a/Language/Functions/Communication/SPI/SPISettings.adoc +++ b/Language/Functions/Communication/SPI/SPISettings.adoc @@ -22,12 +22,13 @@ If any of your settings are variables, you may create a SPISettings object to ho `SPI.beginTransaction(SPISettings(14000000, MSBFIRST, SPI_MODE0))` Note: Best if all 3 settings are constants -`SPISettings mySettting(speedMaximum, dataOrder, dataMode)` +`SPISettings mySetting(speedMaximum, dataOrder, dataMode)` Note: Best when any setting is a variable'' [float] === Parameters + `speedMaximum`: The maximum speed of communication. For a SPI chip rated up to 20 MHz, use 20000000. + `dataOrder`: MSBFIRST or LSBFIRST + `dataMode`: SPI_MODE0, SPI_MODE1, SPI_MODE2, or SPI_MODE3 diff --git a/Language/Functions/Communication/SPI/beginTransaction.adoc b/Language/Functions/Communication/SPI/beginTransaction.adoc index 6c9f63b7..3b5147af 100644 --- a/Language/Functions/Communication/SPI/beginTransaction.adoc +++ b/Language/Functions/Communication/SPI/beginTransaction.adoc @@ -11,7 +11,7 @@ title: SPI.beginTransaction() [float] === Description -Initializes the SPI bus using the defined link:SPISettings[SPISettings]. +Initializes the SPI bus using the defined link:../spisettings[SPISettings]. [float] @@ -21,7 +21,7 @@ Initializes the SPI bus using the defined link:SPISettings[SPISettings]. [float] === Parameters -mySettings: the chosen settings according to link:SPISettings[SPISettings]. +mySettings: the chosen settings according to link:../spisettings[SPISettings]. [float] diff --git a/Language/Functions/Communication/SPI/setBitOrder.adoc b/Language/Functions/Communication/SPI/setBitOrder.adoc index b1e09d26..c67d40c1 100644 --- a/Language/Functions/Communication/SPI/setBitOrder.adoc +++ b/Language/Functions/Communication/SPI/setBitOrder.adoc @@ -11,7 +11,7 @@ title: SPI.setBitOrder() [float] === Description -This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. Sets the order of the bits shifted out of and into the SPI bus, either LSBFIRST (least-significant bit first) or MSBFIRST (most-significant bit first). diff --git a/Language/Functions/Communication/SPI/setClockDivider.adoc b/Language/Functions/Communication/SPI/setClockDivider.adoc index 2aad770e..edb835c9 100644 --- a/Language/Functions/Communication/SPI/setClockDivider.adoc +++ b/Language/Functions/Communication/SPI/setClockDivider.adoc @@ -11,7 +11,7 @@ title: SPI.setClockDivider() [float] === Description -This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. Sets the SPI clock divider relative to the system clock. On AVR based boards, the dividers available are 2, 4, 8, 16, 32, 64 or 128. The default setting is SPI_CLOCK_DIV4, which sets the SPI clock to one-quarter the frequency of the system clock (4 Mhz for the boards at 16 MHz). @@ -27,6 +27,7 @@ Sets the SPI clock divider relative to the system clock. On AVR based boards, th === Parameters divider (only AVR boards): + * SPI_CLOCK_DIV2 * SPI_CLOCK_DIV4 * SPI_CLOCK_DIV8 @@ -35,8 +36,8 @@ divider (only AVR boards): * SPI_CLOCK_DIV64 * SPI_CLOCK_DIV128 -chipSelectPin: peripheral device CS pin (Arduino Due only) -divider: a number from 1 to 255 (Arduino Due only) +*chipSelectPin*: peripheral device CS pin (Arduino Due only) +*divider*: a number from 1 to 255 (Arduino Due only) [float] === Returns diff --git a/Language/Functions/Communication/SPI/setDataMode.adoc b/Language/Functions/Communication/SPI/setDataMode.adoc index 4a0472fa..4089e5e8 100644 --- a/Language/Functions/Communication/SPI/setDataMode.adoc +++ b/Language/Functions/Communication/SPI/setDataMode.adoc @@ -10,7 +10,7 @@ title: SPI.setDataMode() [float] === Description -This function should not be used in new projects. Use link:SPISettings[SPISettings]. with link:beginTransaction[SPI.beginTransaction()]. to configure SPI parameters. +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. Sets the SPI data mode: that is, clock polarity and phase. See the Wikipedia article on http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus:[SPI] for details.