raspberrypi · kilograham · May 16, 2022 · Apr 10, 2021 · Apr 14, 2021 · Apr 14, 2021
diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@ on getting up and running.
 
 App|Description | Link to prebuilt UF2
 ---|---|---
-[hello_serial](hello_world/serial) | The obligatory Hello World program for Pico (Output over serial version) | 
+[hello_serial](hello_world/serial) | The obligatory Hello World program for Pico (Output over serial version) |
 [hello_usb](hello_world/usb) | The obligatory Hello World program for Pico (Output over USB version) | https://rptl.io/pico-hello-usb
 [blink](blink) | Blink an LED on and off. | https://rptl.io/pico-blink
 
@@ -44,7 +44,6 @@ App|Description
 [control_blocks](dma/control_blocks)| Build a control block list, to program a longer sequence of DMA transfers to the UART.
 [channel_irq](dma/channel_irq)| Use an IRQ handler to reconfigure a DMA channel, in order to continuously drive data through a PIO state machine.
 
-
 ### Flash
 
 App|Description
@@ -71,7 +70,6 @@ App|Description
 ---|---
 [hello_divider](divider) | Show how to directly access the hardware integer dividers, in case AEABI injection is disabled.
 
-
 ### I2C
 
 App|Description
@@ -99,7 +97,7 @@ App|Description
 App|Description
 ---|---
 [hello_multicore](multicore/hello_multicore) | Launch a function on the second core, printf some messages on each core, and pass data back and forth through the mailbox FIFOs.
-[multicore_fifo_irqs](multicore/multicore_fifo_irqs) | On each core, register and interrupt handler for the mailbox FIFOs. Show how the interrupt fires when that core receives a message. 
+[multicore_fifo_irqs](multicore/multicore_fifo_irqs) | On each core, register and interrupt handler for the mailbox FIFOs. Show how the interrupt fires when that core receives a message.
 [multicore_runner](multicore/multicore_runner) | Set up the second core to accept, and run, any function pointer pushed into its mailbox FIFO. Push in a few pieces of code and get answers back.
 
 ### Pico Board
@@ -162,6 +160,7 @@ App|Description
 [mpu9250_spi](spi/mpu9250_spi) | Attach a MPU9250 accelerometer/gyoscope via SPI.
 [spi_dma](spi/spi_dma) | Use DMA to transfer data both to and from the SPI simultaneously. The SPI is configured for loopback.
 [spi_flash](spi/spi_flash) | Erase, program and read a serial flash device attached to one of the SPI controllers.
+[spi_master_slave](spi/spi_master_slave) | Demonstrate SPI communication as master and slave.
 
 ### System
 
@@ -170,6 +169,7 @@ App|Description
 [hello_double_tap](system/hello_double_tap) | An LED blink with the `pico_bootsel_via_double_reset` library linked. This enters the USB bootloader when it detects the system being reset twice in quick succession, which is useful for boards with a reset button but no BOOTSEL button.
 [narrow_io_write](system/narrow_io_write) | Demonstrate the effects of 8-bit and 16-bit writes on a 32-bit IO register.
 [unique_board_id](system/unique_board_id) | Read the 64 bit unique ID from external flash, which serves as a unique identifier for the board.
+
 ### Timer
 
 App|Description

diff --git a/spi/CMakeLists.txt b/spi/CMakeLists.txt
@@ -2,5 +2,6 @@ if (NOT PICO_NO_HARDWARE)
     add_subdirectory(bme280_spi)
     add_subdirectory(mpu9250_spi)
     add_subdirectory(spi_dma)
+    add_subdirectory(spi_master_slave)
     add_subdirectory(spi_flash)
 endif ()
diff --git a/spi/spi_master_slave/CMakeLists.txt b/spi/spi_master_slave/CMakeLists.txt
@@ -0,0 +1,2 @@
+add_subdirectory(spi_master)
+add_subdirectory(spi_slave)
diff --git a/spi/spi_master_slave/README.adoc b/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 stdio.
+
+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.
+spi_master_slave.csv:: Communication as seen by logic analyzer, exported to CSV format.
+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
+|===
+
diff --git a/spi/spi_master_slave/spi_master/CMakeLists.txt b/spi/spi_master_slave/spi_master/CMakeLists.txt
@@ -0,0 +1,12 @@
+add_executable(spi_master
+        spi_master.c
+        )
+
+# Pull in basic dependencies
+target_link_libraries(spi_master pico_stdlib hardware_spi)
+
+# create map/bin/hex file etc.
+pico_add_extra_outputs(spi_master)
+
+# add url via pico_set_program_url
+example_auto_set_url(spi_master)
diff --git a/spi/spi_master_slave/spi_master/spi_master.c b/spi/spi_master_slave/spi_master/spi_master.c
@@ -0,0 +1,89 @@
+// 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>
+#include "pico/stdlib.h"
+#include "pico/binary_info.h"
+#include "hardware/spi.h"
+
+#define BUF_LEN         0x100
+
+void printbuf(uint8_t buf[], size_t len) {
+    int i;
+    for (i = 0; i < len; ++i) {
+        if (i % 16 == 15)
+            printf("%02x\n", buf[i]);
+        else
+            printf("%02x ", buf[i]);
+    }
+
+    // append trailing newline if there isn't one
+    if (i % 16) {
+        putchar('\n');
+    }
+}
+
+int main() {
+    // Enable UART so we can print
+    stdio_init_all();
+#if !defined(spi_default) || !defined(PICO_DEFAULT_SPI_SCK_PIN) || !defined(PICO_DEFAULT_SPI_TX_PIN) || !defined(PICO_DEFAULT_SPI_RX_PIN) || !defined(PICO_DEFAULT_SPI_CSN_PIN)
+#warning spi/spi_master example requires a board with SPI pins
+    puts("Default SPI pins were not defined");
+#else
+
+    printf("SPI master example\n");
+
+    // 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));
+
+    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("SPI master says: The following buffer will be written to MOSI endlessly:\n");
+    printbuf(out_buf, BUF_LEN);
+
+    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("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
+}