# jamesbowman/spidriver architecture
> Architecture diagram of the GitHub repository jamesbowman/spidriver, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.
- Interactive diagram: https://gitdiagram.com/jamesbowman/spidriver
- Repository: https://github.com/jamesbowman/spidriver
## Overview
1. **Overall shape**
SPIDriver is a two-sided system: a USB-connected hardware probe that acts as an SPI master, and a set of host-side libraries/tools that talk to it over a simple serial protocol. The key architectural boundary is the USB serial link; everything above it is host software, everything below it is device firmware and board design.
2. **Device-side hardware**
The `hardware/` directory contains the PCB design for the SPIDriver board (`spidriver1.kicad_pcb`) plus a small build/helper script. This is the physical layer that exposes SPI signals to external devices and connects them to the USB-capable controller on the board.
3. **Firmware on the device**
`firmware/main.fs` and `firmware/st7735.fs` are the embedded runtime logic for the board. This code interprets incoming serial commands and translates them into SPI transactions. The `st7735*` files show that the firmware also supports driving an ST7735 display over SPI, so the firmware is not just a thin pass-through; it includes device-specific SPI helpers.
4. **Wire protocol contract**
`protocol.md` is the architectural contract between host and device. It defines the serial command set that all host bindings implement, which keeps the hardware/firmware independent from the host language used. This protocol is the main interoperability boundary in the repo.
5. **Python host library**
`python/spidriver.py` is the primary high-level host API for scripting and automation. The `python/samples/` directory demonstrates real use cases such as flashing, image loading, GUI control, device confirmation, and SPI traffic generation. This layer is the easiest entry point for application code that needs SPI access.
6. **C host library and platform backends**
The `c/common/` code provides shared SPI-driver logic, while `c/linux/spi.c` and `c/win32/spi.c` implement platform-specific serial/SPI plumbing. The `Makefile`s in `c/linux/` and `c/win32/` indicate separate build targets per OS. This is the low-level native binding layer for C/C++ applications.
7. **Windows GUI and serial-port abstraction**
`c/win32gui/` is a standalone GUI application subtree with headers, source files, and Windows resource files. It includes its own serial-port abstraction (`serialport.c/.h`) and example code, showing that the GUI is built on top of the same serial protocol rather than talking directly to hardware. That makes the GUI another client of the protocol, not a separate control path.
8. **Build/packaging structure**
The repo is multi-language and multi-target, so build logic is split by platform: Python packaging in `python/setup.py`, native build files in the C subtrees, and root-level tooling such as `testall`. This suggests the project is organized around reusable protocol-driven components rather than one monolithic application.
9. **Test and validation assets**
`flashtest/` contains a dedicated board/schematic pair, which likely exists to validate flashing or SPI behavior against known hardware. Together with the sample programs under `python/samples/`, these assets serve as integration tests for the hardware, firmware, and host bindings.
10. **Documentation and distribution**
`README.md`, `protocol.md`, and `python/docs/` form the public documentation layer. The docs are important architecturally because they describe the protocol and usage patterns that all language bindings must follow. External hosting/build badges in the README show the project is documented and continuously validated, but the core architecture remains centered on the serial protocol boundary.
11. **How data flows end-to-end**
A host application opens the SPIDriver as a USB serial device, sends protocol commands, the firmware decodes them, performs SPI I/O on the attached target device, and returns read data or status back over serial. Optional paths include SPI-driven peripherals like the ST7735 display and flashing workflows demonstrated by the samples.
12. **What to diagram**
The most important diagram boundaries are: host applications/bindings, the serial protocol, device firmware, and the hardware PCB/SPI bus to target peripherals. Around those, show platform-specific host backends for Python and C, plus the GUI, samples, and documentation as consumers of the same protocol.
Main entry points: [`protocol.md`](https://github.com/jamesbowman/spidriver/blob/master/protocol.md) (Protocol), [`firmware/main.fs`](https://github.com/jamesbowman/spidriver/blob/master/firmware/main.fs) (Firmware), [`hardware/spidriver1.kicad_pcb`](https://github.com/jamesbowman/spidriver/blob/master/hardware/spidriver1.kicad_pcb) (PCB design), [`python/spidriver.py`](https://github.com/jamesbowman/spidriver/blob/master/python/spidriver.py) (Python API)
## Diagram (Mermaid)
```mermaid
flowchart TD
subgraph group_host["Host side"]
node_py_api["Python API
host library
[spidriver.py]"]
node_py_samples["Python samples
examples"]
node_c_common["C core
host library
[spidriver.c]"]
node_c_linux["Linux backend
platform backend
[spi.c]"]
node_c_win32["Windows backend
platform backend
[spi.c]"]
node_gui_app["Win32 GUI
desktop app"]
node_serialport["Serial port
abstraction
[serialport.c]"]
node_c_packaging["C packaging
build/installer
[spidriver.nsi]"]
node_py_setup["Python package
build config
[setup.py]"]
end
subgraph group_device["Device side"]
node_firmware["Firmware
embedded runtime
[main.fs]"]
node_st7735["ST7735 SPI
device helper
[st7735.fs]"]
node_board["PCB design
hardware board"]
node_hardware_build["Board build
helper script
[make.py]"]
end
subgraph group_support["Support"]
node_protocol["Protocol
serial contract
[protocol.md]"]
node_flash_hw["Flash test
validation board
[flashtest.sch]"]
node_py_docs["Python docs
documentation"]
node_readme["README
overview docs
[README.md]"]
node_root_testall["testall
validation tool"]
end
node_py_api -->|"implements"| node_protocol
node_py_samples -->|"uses"| node_py_api
node_c_common -->|"implements"| node_protocol
node_c_common -->|"platforms"| node_c_linux
node_c_common -->|"platforms"| node_c_win32
node_gui_app -->|"uses"| node_serialport
node_gui_app -->|"implements"| node_protocol
node_firmware -->|"speaks"| node_protocol
node_st7735 -->|"extends"| node_firmware
node_firmware -->|"drives"| node_board
node_board -.->|"validated by"| node_flash_hw
node_hardware_build -->|"builds"| node_board
node_py_setup -->|"packages"| node_py_api
node_py_docs -->|"documents"| node_py_api
node_readme -->|"describes"| node_protocol
node_root_testall -.->|"checks"| node_py_samples
node_root_testall -.->|"checks"| node_flash_hw
node_protocol -->|"boundary"| node_firmware
node_board -->|"runs on"| node_firmware
click node_protocol "https://github.com/jamesbowman/spidriver/blob/master/protocol.md"
click node_py_api "https://github.com/jamesbowman/spidriver/blob/master/python/spidriver.py"
click node_py_samples "https://github.com/jamesbowman/spidriver/tree/master/python/samples"
click node_c_common "https://github.com/jamesbowman/spidriver/blob/master/c/common/spidriver.c"
click node_c_linux "https://github.com/jamesbowman/spidriver/blob/master/c/linux/spi.c"
click node_c_win32 "https://github.com/jamesbowman/spidriver/blob/master/c/win32/spi.c"
click node_gui_app "https://github.com/jamesbowman/spidriver/tree/master/c/win32gui"
click node_serialport "https://github.com/jamesbowman/spidriver/blob/master/c/win32gui/src/serialport.c"
click node_firmware "https://github.com/jamesbowman/spidriver/blob/master/firmware/main.fs"
click node_st7735 "https://github.com/jamesbowman/spidriver/blob/master/firmware/st7735.fs"
click node_board "https://github.com/jamesbowman/spidriver/blob/master/hardware/spidriver1.kicad_pcb"
click node_flash_hw "https://github.com/jamesbowman/spidriver/blob/master/flashtest/flashtest.sch"
click node_hardware_build "https://github.com/jamesbowman/spidriver/blob/master/hardware/make.py"
click node_py_docs "https://github.com/jamesbowman/spidriver/tree/master/python/docs"
click node_readme "https://github.com/jamesbowman/spidriver/blob/master/README.md"
click node_root_testall "https://github.com/jamesbowman/spidriver/tree/master/testall"
click node_c_packaging "https://github.com/jamesbowman/spidriver/blob/master/c/spidriver.nsi"
click node_py_setup "https://github.com/jamesbowman/spidriver/blob/master/python/setup.py"
classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_api,node_py_samples,node_c_common,node_c_linux,node_c_win32,node_gui_app,node_serialport,node_c_packaging,node_py_setup toneBlue
class node_firmware,node_st7735,node_board,node_hardware_build toneAmber
class node_protocol,node_flash_hw,node_py_docs,node_readme,node_root_testall toneMint
```
## Components
### Host side
Libraries and tools that talk to the device over the serial protocol.
- [Python API](https://github.com/jamesbowman/spidriver/blob/master/python/spidriver.py): host library · Primary Python interface for scripting and automation. · `python/spidriver.py`
- [Python samples](https://github.com/jamesbowman/spidriver/tree/master/python/samples): examples · Usage examples for flashing, GUI control, image loading, and SPI traffic. · `python/samples`
- [C core](https://github.com/jamesbowman/spidriver/blob/master/c/common/spidriver.c): host library · Shared C-side driver logic used by native bindings. · `c/common/spidriver.c`
- [Linux backend](https://github.com/jamesbowman/spidriver/blob/master/c/linux/spi.c): platform backend · Linux-specific serial and SPI plumbing for the C binding. · `c/linux/spi.c`
- [Windows backend](https://github.com/jamesbowman/spidriver/blob/master/c/win32/spi.c): platform backend · Windows-specific serial and SPI plumbing for the C binding. · `c/win32/spi.c`
- [Win32 GUI](https://github.com/jamesbowman/spidriver/tree/master/c/win32gui): desktop app · Standalone Windows GUI client built on the same protocol and serial layer. · `c/win32gui`
- [Serial port](https://github.com/jamesbowman/spidriver/blob/master/c/win32gui/src/serialport.c): abstraction · Windows serial-port wrapper used by the GUI application. · `c/win32gui/src/serialport.c`
- [C packaging](https://github.com/jamesbowman/spidriver/blob/master/c/spidriver.nsi): build/installer · Native packaging and platform build orchestration for the C subtree. · `c/spidriver.nsi`
- [Python package](https://github.com/jamesbowman/spidriver/blob/master/python/setup.py): build config · Python packaging entry point for the host library. · `python/setup.py`
### Device side
Firmware and board design that implement the SPI probe.
- [Firmware](https://github.com/jamesbowman/spidriver/blob/master/firmware/main.fs): embedded runtime · Device-side command interpreter and SPI execution logic. · `firmware/main.fs`
- [ST7735 SPI](https://github.com/jamesbowman/spidriver/blob/master/firmware/st7735.fs): device helper · Firmware support for driving an ST7735 display over SPI. · `firmware/st7735.fs`
- [PCB design](https://github.com/jamesbowman/spidriver/blob/master/hardware/spidriver1.kicad_pcb): hardware board · SPIDriver board layout and physical interface to the USB-capable controller and SPI pins. · `hardware/spidriver1.kicad_pcb`
- [Board build](https://github.com/jamesbowman/spidriver/blob/master/hardware/make.py): helper script · Hardware build/helper script for the PCB subtree. · `hardware/make.py`
### Support
Documentation, samples, and validation assets around the core system.
- [Protocol](https://github.com/jamesbowman/spidriver/blob/master/protocol.md): serial contract · Wire protocol shared by every host binding and the device firmware. · `protocol.md`
- [Flash test](https://github.com/jamesbowman/spidriver/blob/master/flashtest/flashtest.sch): validation board · Dedicated board/schematic pair for flashing and SPI behavior validation. · `flashtest/flashtest.sch`
- [Python docs](https://github.com/jamesbowman/spidriver/tree/master/python/docs): documentation · Sphinx documentation for the Python binding and usage patterns. · `python/docs`
- [README](https://github.com/jamesbowman/spidriver/blob/master/README.md): overview docs · Top-level project overview and public entry point. · `README.md`
- [testall](https://github.com/jamesbowman/spidriver/tree/master/testall): validation tool · Root-level tooling for running project-wide checks. · `testall`
## Connections
- Python API → Protocol: implements · Python binding encodes and decodes the shared command set.
- Python samples → Python API: uses · Examples exercise the high-level Python interface.
- C core → Protocol: implements · Shared C driver logic follows the same wire contract.
- C core → Linux backend: platforms · Linux backend provides the OS-specific transport.
- C core → Windows backend: platforms · Windows backend provides the OS-specific transport.
- Win32 GUI → Serial port: uses · GUI talks through its serial-port abstraction.
- Win32 GUI → Protocol: implements · GUI is another client of the shared serial protocol.
- Firmware → Protocol: speaks · Embedded runtime interprets the host command stream.
- ST7735 SPI → Firmware: extends · Display support is part of the device firmware stack.
- Firmware → PCB design: drives · Firmware controls the board's SPI-capable hardware interface.
- PCB design → Flash test: validated by · Dedicated test hardware checks flashing and SPI behavior.
- Board build → PCB design: builds · Helper script supports the PCB design workflow.
- Python package → Python API: packages · Python packaging publishes the host library.
- Python docs → Python API: documents · Docs explain usage of the Python binding.
- README → Protocol: describes · Top-level docs explain the central host-device contract.
- testall → Python samples: checks · Project validation includes sample and integration workflows.
- testall → Flash test: checks · Validation tooling likely covers hardware or flashing tests.
- Protocol → Firmware: boundary · Protocol is the interface between host software and device firmware.
- PCB design → Firmware: runs on · Firmware executes on the controller connected to the PCB.