How jamesbowman/spidriver works
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 Makefiles 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 Protocol · main.fs Firmware · spidriver1.kicad_pcb PCB design · spidriver.py Python API
Components 18
Host side
Libraries and tools that talk to the device over the serial protocol.
- Python API · Primary Python interface for scripting and automation.
python/spidriver.py - Python samples · Usage examples for flashing, GUI control, image loading, and SPI traffic.
python/samples - C core · Shared C-side driver logic used by native bindings.
c/common/spidriver.c - Linux backend · Linux-specific serial and SPI plumbing for the C binding.
c/linux/spi.c - Windows backend · Windows-specific serial and SPI plumbing for the C binding.
c/win32/spi.c - Win32 GUI · Standalone Windows GUI client built on the same protocol and serial layer.
c/win32gui - Serial port · Windows serial-port wrapper used by the GUI application.
c/win32gui/src/serialport.c - C packaging · Native packaging and platform build orchestration for the C subtree.
c/spidriver.nsi - Python package · Python packaging entry point for the host library.
python/setup.py
Device side
Firmware and board design that implement the SPI probe.
- Firmware · Device-side command interpreter and SPI execution logic.
firmware/main.fs - ST7735 SPI · Firmware support for driving an ST7735 display over SPI.
firmware/st7735.fs - PCB design · SPIDriver board layout and physical interface to the USB-capable controller and SPI pins.
hardware/spidriver1.kicad_pcb - Board build · Hardware build/helper script for the PCB subtree.
hardware/make.py
Support
Documentation, samples, and validation assets around the core system.
- Protocol · Wire protocol shared by every host binding and the device firmware.
protocol.md - Flash test · Dedicated board/schematic pair for flashing and SPI behavior validation.
flashtest/flashtest.sch - Python docs · Sphinx documentation for the Python binding and usage patterns.
python/docs - README · Top-level project overview and public entry point.
README.md - testall · Root-level tooling for running project-wide checks.
testall
Connections 19
- 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.