Merge pull request #201 from OnionIoT/content/spi-guide

Updated SPI w/ Python guide with step to choose between hw and sw SPI

Author: greenbreakfast

docs/device-tree-overlay/software-spi.md

@@ -20,7 +20,9 @@ Users that need to use different pins can create their own customized version ba
 
 :::caution **Drawback: Lower Bus Speed**
 
-Since this is a software-based bus, it will not be as fast as a hardware SPI bus. This is adequate for most SPI devices, but it is not recommended for data-intensive use cases like driving a display.
+Since this is a software-based bus, it will not be as fast as a hardware SPI bus. The maximum bus speed is **1.4MHz** if CPU load is low - much slower compared the 40MHz maximum of the hardware SPI bus.
+
+This is adequate for most SPI devices, but it is not recommended for data-intensive use cases like driving a display.
 
 :::
 

docs/guides/hardware-interfaces/assets/spi-writebytes-0.png

@@ -1,5 +1,5 @@
 ---
-title: Using the SPI bus with Python
+title: Using SPI with Python
 ---
 
 import { GiscusDocComment } from '/src/components/GiscusComment';
@@ -35,27 +35,91 @@ opkg update
 opkg install python3-light python3-spidev
 ```
 
-<!-- TODO: add a step where the user chooses between harware SPI or the sw spi? -->
+## Step 2: Choose Between Hardware or Software SPI
 
-## Step 2: Physically Connect an SPI Device
+The Omega2 supports both **hardware SPI** (using a built-in controller) and **software SPI** (bit-banging GPIOs). Before proceeding, choose the SPI bus that best suits your needs.
+
+### Comparison: Hardware SPI vs. Software SPI on the Omega2
+| Feature                 | Hardware SPI (CS1)                     | Software SPI |
+|-------------------------|--------------------------------------|--------------|
+| **Speed**               | Up to **40MHz** (fast)               | Up to **1.4MHz** depending on CPU load - Slower, best for low-data applications |
+| **Full-Duplex Support** | ❌ No                                | ✅ Yes |
+| **SPI Configuration**   | Limited; CS0 is reserved for flash | Flexible; can be configured as needed  |
+| **GPIO Flexibility**    | Fixed SPI pins (see next step)       | Choose from two predefined GPIO sets |
+| **System Load**         | Low (uses dedicated SPI controller) | Higher (CPU handles SPI signals) |
+
+<!-- TODO: see if chart from docs/hardware-interfaces/spi.md can be reused -->
+
+### Option 1: Using the Hardware SPI Bus (CS1)
+The **hardware SPI bus** is pre-configured on the Omega2 and is accessed through `/dev/spidev0.1`. It supports **high-speed** SPI communication but is limited to **half-duplex mode** and uses **the fixed SPI pins**:
+- GPIO6
+- SPI_CLK pin
+- SPI_MOSI pin
+- SPI_MISO pin
+
+If this setup meets your needs, **proceed to [Step 3](#step-3-physically-connect-an-spi-device)** to connect SPI devices. **For most users, this is the quickest option.**
+
+
+### Option 2: Enabling a Software SPI Bus
+If you need **full-duplex SPI**, additional SPI buses, or different GPIO assignments, you can enable a **software SPI bus** by installing one of two available **Software SPI Device Tree Overlay packages**.
+
+
+#### Enabling a Software SPI Bus
+To enable a software SPI bus, install one of the following overlay packages:
+
+**For an SPI bus on GPIOs 14, 15, 16, and 17:**
+```
+opkg update 
+opkg install onion-dt-overlay-sw-spi
+```
+
+**For an SPI bus on GPIOs 0, 1, 2, and 3:**
+```
+opkg update
+opkg install onion-dt-overlay-sw-spi-alt
+```
+
+After installation, the software SPI bus will be accessible at `/dev/spidev1.0`. Note this down for the next steps.
+
+:::tip
+
+Each package predefines the GPIOs that function as SPI signals. For more details, see the [Software SPI Bus article in the Device Tree Overlay chapter](/device-tree-overlay/software-spi).
+
+:::
+
+---
+
+**Next Step:** Once you've chosen your SPI bus, proceed to [Step 3](#step-3-physically-connect-an-spi-device).
+
+
+## Step 3: Physically Connect an SPI Device
 
 Before we can send data, we need to connect an SPI device to the Omega2's SPI bus.
 
 ### Pin Connections
 
-Connect the SPI pins of your external device to the Omega2 according to this table:
+If you decided to use **hardware SPI** in Step 2, connect the SPI pins of your external device to the Omega2 according to this table: 
 
-| SPI Signal  | Omega2 Pin       |
+| SPI Signal  | Omega2 Pin       | 
 |-------------|------------------|
 | Clock / SCK | SPI_CLK / GPIO7  |
 | MOSI        | SPI_MOSI / GPIO8 |
 | MISO        | SPI_MISO / GPIO9 |
 | CS          | SPI_CS1 / GPIO6  |
 
+If you decided to use **software SPI** in Step 2, connect the SPI pins of the external device according to the table below:
+
+| SPI Signal  | Omega2 Pin when using `onion-dt-overlay-sw-spi` | Omega2 Pin when using `onion-dt-overlay-sw-spi-alt` |
+|-------------|---------|--------|
+| Clock / SCK | GPIO14  | GPIO3  |
+| MOSI        | GPIO16  | GPIO1  |
+| MISO        | GPIO15  | GPIO0  |
+| CS          | GPIO17  | GPIO2  |
+
 
 Additionally, make sure the SPI device is supplied with power according to its specifications.
 
-## Step 3: SPI Hello World - Write Bytes to the Device
+## Step 4: SPI Hello World - Write Bytes to the Device
 
 To confirm that the SPI bus is working, we'll run a Python program that **writes 256 bytes of incremental data** over SPI in eight cycles.
 
@@ -69,6 +133,36 @@ cd /root
 wget https://raw.githubusercontent.com/OnionIoT/python-spidev/refs/heads/master/examples/writebytes.py
 ```
 
+### Software SPI: Change SPI bus in script
+
+If you decided to use a software SPI bus in step 2, the script needs to be updated to use the correct device.
+
+Use the `vi` editor to modify the change
+
+```
+spi = spidev.SpiDev(0,1)
+```
+
+to 
+
+```
+spi = spidev.SpiDev(1,0)
+```
+
+:::tip Using the vi Editor
+
+If you're not familiar, the `vi` text editor is included on the Omega by default. To make the change:
+1. Run `vi /root/writebytes.py`
+1. Enter insert mode by pressing `i`
+1. Make the changes
+1. Return to command mode by pressing `esc` once
+1. Save and close the file by typing `:wq` and pressing enter
+
+Learn more about the small but powerful `vi` editor [online](https://www.redhat.com/en/blog/introduction-vi-editor).
+
+:::
+
+
 ### Run the Program 
 
 Now, let’s run the script to send data over SPI:
@@ -77,11 +171,16 @@ Now, let’s run the script to send data over SPI:
 python writebytes.py
 ```
 
-This will send 256 bytes of incremental data (`0x00`, `0x01`, `0x02`, ...) over SPI, repeating 8 times. If you have a logic analyzer or oscilloscope connected, you should see activity.
+This will send 256 bytes of incremental data (`0x00`, `0x01`, `0x02`, ...) over SPI, repeating 8 times. If you have a logic analyzer or oscilloscope connected, you should see activity:
+
+![logic analyzer showing 8 SPI transmissions](./assets/spi-writebytes-0.png)
+*Logic analyzer showing eight blocks of SPI writes*
 
-<!-- TODO: add screenhot output of logic analyzer? -->
+Zooming in, we can confirm the data being sent is incremental:
+ 
+![logic analyzer showing incremental data being transmitted](./assets/spi-writebytes-1.png)
 
-## Step 4: Half-Duplex SPI Transmission
+## Step 5: Half-Duplex SPI Transmission
 
 Next, let's run a Python script that performs a half-duplex SPI transaction—meaning it writes a byte and immediately reads a specified number of bytes in return. This is useful for reading registers on an SPI device.
 
@@ -116,6 +215,35 @@ This kind of transaction is useful when interacting with SPI devices that store
 
 To exit the vi editor without saving changes, type `:q!` and press Enter.
 
+### Software SPI: Change SPI bus in script
+
+If you decided to use a software SPI bus in step 2, the script needs to be updated to use the correct device.
+
+Use the `vi` editor to modify the change
+
+```
+spi = spidev.SpiDev(0,1)
+```
+
+to 
+
+```
+spi = spidev.SpiDev(1,0)
+```
+
+:::tip Using the vi Editor
+
+If you're not familiar, the `vi` text editor is included on the Omega by default. To make the change:
+1. Run `vi /root/xfer3.py`
+1. Enter insert mode by pressing `i`
+1. Make the changes
+1. Return to command mode by pressing `esc` once
+1. Save and close the file by typing `:wq` and pressing enter
+
+Learn more about the small but powerful `vi` editor [online](https://www.redhat.com/en/blog/introduction-vi-editor).
+
+:::
+
 ### Run the Program 
 
 How, execute the script:
@@ -128,14 +256,12 @@ python xfer3.py
 The program will display the received bytes on the terminal:
 
 ```
-root@Omega-FB94://# python xfer3.py
+root@Omega-FB94:~# python xfer3.py
 Half-duplex transmission: writing 1 byte, reading 2 bytes
-Read: 0x11, 0x9a
+Read: [4, 2]
 Done
 ```
 
-<!-- TODO: confirm above output -->
-
 This confirms that the SPI device is responding to commands and returning data.
 
 

docs/guides/hardware-interfaces/assets/spi-writebytes-1.png

@@ -41,6 +41,8 @@ The Omega2 has one hardware SPI interface available:
 
 The Omega2 does not support full-duplex SPI transmissions. This is due to a hardware bug in the underlying MT7688 SoC used in the Omega2.
 
+For use cases where full-duplex SPI is a requirement, consider using a [software-based SPI bus](#software-based-spi-bus).
+
 :::
 
 The SPI and CS1 pins are highlighted on the Omega2/2S diagrams below.
@@ -72,7 +74,7 @@ Unlike hardware SPI, which uses a dedicated controller to handle communication,
 
 | Feature                 | Hardware SPI (CS1)                     | Software SPI |
 |-------------------------|--------------------------------------|--------------|
-| **Speed**               | Up to **40MHz** (fast)               | Slower, best for low-data applications |
+| **Speed**               | Up to **40MHz** (fast)               | Up to **1.4MHz** - Slower, best for low-data applications |
 | **Full-Duplex Support** | ❌ No on Omega2                                | ✅ Yes |
 | **SPI Configuration**   | Limited; CS0 is reserved for flash | Flexible; can be configured as needed |
 | **GPIO Flexibility**    | Fixed to SPI pins                   | Any GPIOs can be used |