Minor changes to spi_master and spi_slave. Adjusted documentation.

Author: Michael Stoops

spi/spi_master_slave/README.adoc

@@ -0,0 +1,140 @@
+= Communicating as master and slave via SPI
+
+This example code shows how to interface two RP2040 microcontrollers to each other using SPI.
+
+== Wiring information
+
+[frame="topbot",options="header"]
+|===
+| Function | Master (RP2040) | Slave (RP2040) | Master (Pico) | Slave (Pico)
+| MOSI | DO0  | DI0  | 25 | 21
+| SCLK | SCK0 | SCK0 | 24 | 24
+| GND  | GND  | GND  | 23 | 23
+| CS   | CS0  | CS0  | 22 | 22
+| MISO | DI0  | DO0  | 21 | 25
+|===
+
+[[spi_master_slave_wiring]]
+[pdfwidth=75%]
+.Wiring Diagram for SPI Master and Slave.
+image::spi_master_slave_bb.png[]
+
+At least one of the boards should be powered, and will share power to the other.
+
+If the master is not connected properly to a slave, the master will report reading all zeroes.
+
+If the slave is not connected properly to a master, it will initialize but never transmit nor receive, because it's waiting for clock signal from the master.
+
+== Outputs
+
+Both master and slave boards will give output to their UART or USB CDC serial port.
+
+With master and slave properly connected, the master should output something like this:
+
+....
+SPI master example
+SPI master says: The following buffer will be written to MOSI endlessly:
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+80 81 82 83 84 85 86 87 88 89 8a 8b 8c 8d 8e 8f
+90 91 92 93 94 95 96 97 98 99 9a 9b 9c 9d 9e 9f
+a0 a1 a2 a3 a4 a5 a6 a7 a8 a9 aa ab ac ad ae af
+b0 b1 b2 b3 b4 b5 b6 b7 b8 b9 ba bb bc bd be bf
+c0 c1 c2 c3 c4 c5 c6 c7 c8 c9 ca cb cc cd ce cf
+d0 d1 d2 d3 d4 d5 d6 d7 d8 d9 da db dc dd de df
+e0 e1 e2 e3 e4 e5 e6 e7 e8 e9 ea eb ec ed ee ef
+f0 f1 f2 f3 f4 f5 f6 f7 f8 f9 fa fb fc fd fe ff
+SPI master says: read page 0 from the MISO line:
+ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0
+ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0
+df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0
+cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0
+bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0
+af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0
+9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90
+8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80
+7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70
+6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60
+5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50
+4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40
+3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30
+2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20
+1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10
+0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00
+....
+
+The slave should output something like this:
+
+....
+SPI slave example
+SPI slave says: When reading from MOSI, the following buffer will be written to MISO:
+ff fe fd fc fb fa f9 f8 f7 f6 f5 f4 f3 f2 f1 f0
+ef ee ed ec eb ea e9 e8 e7 e6 e5 e4 e3 e2 e1 e0
+df de dd dc db da d9 d8 d7 d6 d5 d4 d3 d2 d1 d0
+cf ce cd cc cb ca c9 c8 c7 c6 c5 c4 c3 c2 c1 c0
+bf be bd bc bb ba b9 b8 b7 b6 b5 b4 b3 b2 b1 b0
+af ae ad ac ab aa a9 a8 a7 a6 a5 a4 a3 a2 a1 a0
+9f 9e 9d 9c 9b 9a 99 98 97 96 95 94 93 92 91 90
+8f 8e 8d 8c 8b 8a 89 88 87 86 85 84 83 82 81 80
+7f 7e 7d 7c 7b 7a 79 78 77 76 75 74 73 72 71 70
+6f 6e 6d 6c 6b 6a 69 68 67 66 65 64 63 62 61 60
+5f 5e 5d 5c 5b 5a 59 58 57 56 55 54 53 52 51 50
+4f 4e 4d 4c 4b 4a 49 48 47 46 45 44 43 42 41 40
+3f 3e 3d 3c 3b 3a 39 38 37 36 35 34 33 32 31 30
+2f 2e 2d 2c 2b 2a 29 28 27 26 25 24 23 22 21 20
+1f 1e 1d 1c 1b 1a 19 18 17 16 15 14 13 12 11 10
+0f 0e 0d 0c 0b 0a 09 08 07 06 05 04 03 02 01 00
+SPI slave says: read page 0 from the MOSI line:
+00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
+10 11 12 13 14 15 16 17 18 19 1a 1b 1c 1d 1e 1f
+20 21 22 23 24 25 26 27 28 29 2a 2b 2c 2d 2e 2f
+30 31 32 33 34 35 36 37 38 39 3a 3b 3c 3d 3e 3f
+40 41 42 43 44 45 46 47 48 49 4a 4b 4c 4d 4e 4f
+50 51 52 53 54 55 56 57 58 59 5a 5b 5c 5d 5e 5f
+60 61 62 63 64 65 66 67 68 69 6a 6b 6c 6d 6e 6f
+70 71 72 73 74 75 76 77 78 79 7a 7b 7c 7d 7e 7f
+80 81 82 83 84 85 86 87 88 89 8a 8b 8c 8d 8e 8f
+90 91 92 93 94 95 96 97 98 99 9a 9b 9c 9d 9e 9f
+a0 a1 a2 a3 a4 a5 a6 a7 a8 a9 aa ab ac ad ae af
+b0 b1 b2 b3 b4 b5 b6 b7 b8 b9 ba bb bc bd be bf
+c0 c1 c2 c3 c4 c5 c6 c7 c8 c9 ca cb cc cd ce cf
+d0 d1 d2 d3 d4 d5 d6 d7 d8 d9 da db dc dd de df
+e0 e1 e2 e3 e4 e5 e6 e7 e8 e9 ea eb ec ed ee ef
+f0 f1 f2 f3 f4 f5 f6 f7 f8 f9 fa fb fc fd fe ff
+....
+
+If you look at the communication with a logic analyzer, you should see this:
+
+[[spi_master_slave_wiring]]
+[pdfwidth=75%]
+.Data capture as seen in Saleae Logic.
+image::spi_master_slave_logic.png[]
+
+== List of Files
+
+CMakeLists.txt:: CMake file to incorporate the example in to the examples build tree.
+spi_master/spi_master.c:: The example code for SPI master.
+spi_slave/spi_slave.c:: The example code for SPI slave.
+spi_master_slave_logic.png:: Communication as seen by logic analyzer (screenshot).
+spi_master_slave.logicdata:: Communication as seen by logic analyzer (original file, free viewer at https://www.saleae.com/downloads/).
+spi_master_slave.fzz:: Fritzing file.
+spi_master_slave_bb.png:: Breadboard wiring diagram.
+
+== Bill of Materials
+
+.A list of materials required for the example
+[[spi-master-slave-bom-table]]
+[cols=3]
+|===
+| *Item* | *Quantity* | Details
+| Breadboard | 1 | generic part
+| Raspberry Pi Pico | 2 | http://raspberrypi.org/
+| M/M Jumper wires | 8 | generic part
+|===
+

spi/spi_master_slave/README.md

@@ -1,10 +1,26 @@
-/**
- * Copyright (c) 2021 Michael Stoops. All rights reserved.
- * Portions copyright (c) 2021 Raspberry Pi (Trading) Ltd.
- *
- * SPDX-License-Identifier: BSD-3-Clause
- */
-
+// Copyright (c) 2021 Michael Stoops. All rights reserved.
+// Portions copyright (c) 2021 Raspberry Pi (Trading) Ltd.
+// 
+// Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 
+// following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+//    disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+//    following disclaimer in the documentation and/or other materials provided with the distribution.
+// 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
+//    products derived from this software without specific prior written permission.
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
+// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 
+// USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+//
 // Example of an SPI bus master using the PL022 SPI interface
 
 #include <stdio.h>
@@ -39,34 +55,35 @@ int main() {
 
     printf("SPI master example\n");
 
-    // Enable SPI 0 at 1 KHz and connect to GPIOs
-    spi_init(spi_default, 1000);
+    // Enable SPI 0 at 1 MHz and connect to GPIOs
+    spi_init(spi_default, 1000 * 1000);
     gpio_set_function(PICO_DEFAULT_SPI_RX_PIN, GPIO_FUNC_SPI);
     gpio_set_function(PICO_DEFAULT_SPI_SCK_PIN, GPIO_FUNC_SPI);
     gpio_set_function(PICO_DEFAULT_SPI_TX_PIN, GPIO_FUNC_SPI);
     gpio_set_function(PICO_DEFAULT_SPI_CSN_PIN, GPIO_FUNC_SPI);
     // Make the SPI pins available to picotool
     bi_decl(bi_4pins_with_func(PICO_DEFAULT_SPI_RX_PIN, PICO_DEFAULT_SPI_TX_PIN, PICO_DEFAULT_SPI_SCK_PIN, PICO_DEFAULT_SPI_CSN_PIN, GPIO_FUNC_SPI));
 
-    printf("SPI master initialised.\n");
-
     uint8_t out_buf[BUF_LEN], in_buf[BUF_LEN];
 
     // Initialize output buffer
     for (size_t i = 0; i < BUF_LEN; ++i) {
         out_buf[i] = i;
     }
-    
-    printf("The following buffer will be written to MOSI endlessly.\n");
+
+    printf("SPI master says: The following buffer will be written to MOSI endlessly:\n");
     printbuf(out_buf, BUF_LEN);
 
-    for (size_t i = 0; true; ++i) {
+    for (size_t i = 0; ; ++i) {
         // Write the output buffer to MOSI, and at the same time read from MISO.
         spi_write_read_blocking(spi_default, out_buf, in_buf, BUF_LEN);
 
         // Write to stdio whatever came in on the MISO line.
-        printf("Read the following from MISO, page %d:\n", i);
+        printf("SPI master says: read page %d from the MISO line:\n", i);
         printbuf(in_buf, BUF_LEN);
+
+        // Sleep for ten seconds so you get a chance to read the output.
+        sleep_ms(10 * 1000);
     }
 #endif
 }

spi/spi_master_slave/spi_master/spi_master.c

@@ -1,10 +1,26 @@
-/**
- * Copyright (c) 2021 Michael Stoops. All rights reserved.
- * Portions copyright (c) 2021 Raspberry Pi (Trading) Ltd.
- *
- * SPDX-License-Identifier: BSD-3-Clause
- */
-
+// Copyright (c) 2021 Michael Stoops. All rights reserved.
+// Portions copyright (c) 2021 Raspberry Pi (Trading) Ltd.
+// 
+// Redistribution and use in source and binary forms, with or without modification, are permitted provided that the 
+// following conditions are met:
+//
+// 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+//    disclaimer.
+// 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
+//    following disclaimer in the documentation and/or other materials provided with the distribution.
+// 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
+//    products derived from this software without specific prior written permission.
+// 
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, 
+// INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
+// DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
+// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
+// WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 
+// USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+//
+// SPDX-License-Identifier: BSD-3-Clause
+//
 // Example of an SPI bus slave using the PL022 SPI interface
 
 #include <stdio.h>
@@ -41,8 +57,8 @@ int main() {
 
     printf("SPI slave example\n");
 
-    // Enable SPI 0 at 1 KHz and connect to GPIOs
-    spi_init(spi_default, 1000);
+    // Enable SPI 0 at 1 MHz and connect to GPIOs
+    spi_init(spi_default, 1000 * 1000);
     spi_set_slave(spi_default, true);
     gpio_set_function(PICO_DEFAULT_SPI_RX_PIN, GPIO_FUNC_SPI);
     gpio_set_function(PICO_DEFAULT_SPI_SCK_PIN, GPIO_FUNC_SPI);
@@ -51,8 +67,6 @@ int main() {
     // Make the SPI pins available to picotool
     bi_decl(bi_4pins_with_func(PICO_DEFAULT_SPI_RX_PIN, PICO_DEFAULT_SPI_TX_PIN, PICO_DEFAULT_SPI_SCK_PIN, PICO_DEFAULT_SPI_CSN_PIN, GPIO_FUNC_SPI));
 
-    printf("SPI slave initialised.\n");
-
     uint8_t out_buf[BUF_LEN], in_buf[BUF_LEN];
 
     // Initialize output buffer
@@ -61,14 +75,16 @@ int main() {
         out_buf[i] = ~i;
     }
 
-    printf("When reading from MOSI, the following buffer will be written to MISO:\n");
+    printf("SPI slave says: When reading from MOSI, the following buffer will be written to MISO:\n");
     printbuf(out_buf, BUF_LEN);
 
-    for (size_t i = 0; true; ++i) {
+    for (size_t i = 0; ; ++i) {
         // Write the output buffer to MISO, and at the same time read from MOSI.
         spi_write_read_blocking(spi_default, out_buf, in_buf, BUF_LEN);
 
-        // The slave doesn't print the buffer. It can't afford to ignore the SPI bus while writing to stdio.
+        // Write to stdio whatever came in on the MOSI line.
+        printf("SPI slave says: read page %d from the MOSI line:\n", i);
+        printbuf(in_buf, BUF_LEN);
     }
 #endif
 }