Download the PHP package microscrap/spi without Composer

microscrap/spi — Linux SPI / spidev bindings for ScrapyardIO

PHP library that wraps the posi extension with global helpers, enums, and data objects. Every helper delegates to a facade class under Microscrap\Bindings\SPI.

This project provides PHP bindings to the Linux spidev character device API, mirroring the public surface of <linux/spi/spidev.h> (the SPI_IOC_* ioctl family used by spi-tools, Python's spidev, and friends).

Highlights

• Open a spidev device (/dev/spidev0.0, /dev/spidev1.1, etc.) and configure mode, clock speed, and word size in one call
• Half-duplex byte I/O via spi_read / spi_write (uses posix_read / posix_write under the hood)
• Full-duplex, chained transfers via spi_transfer and the SPITransfer data object — packs spi_ioc_transfer and issues SPI_IOC_MESSAGE(n)
• Per-segment overrides: clock speed, bits-per-word, inter-word delay, CS-change, dual/quad lane counts
• Inspect and mutate every spidev attribute — mode, max_speed_hz, bits_per_word, lsb_first
• Typed SPIMode bitmask covers CPOL/CPHA, CS polarity, 3-wire, loopback, no-CS, dual/quad/octal lanes, ready signal
• Automatically prefers a native spi_transfer(int $fd, …) from a low-level extension when one is loaded, otherwise falls back to the ext-posi memory path
• Thin global spi_* helper API — all functions are function_exists-guarded

Requirements

• PHP 8.3+
• Linux kernel with spidev enabled and a populated /dev/spidev* device
• ext-posi ^0.4.0 — install from php-io-extensions/posi; the posi_mem_* helpers are required for spi_transfer unless a native spi_transfer(int $fd, …) is loaded
• microscrap/posix ^0.4.0

Installation

Confirm ext-posi is loaded:

Confirm the spidev device is visible (and that your user can access it, or run as root):

On a Raspberry Pi, enable SPI via raspi-config or by adding dtparam=spi=on to /boot/config.txt.

Composer autoloads src/Helpers/spi-device.php, registering the global spi_* functions.

Usage

SPI transactions are driven through global helper functions (spi_open, spi_read, spi_write, spi_transfer, etc.). All helpers delegate to the Device facade and are only defined once (function_exists guard).

Enums live under Microscrap\Bindings\SPI\Enums. The device handle is Microscrap\Bindings\SPI\DataObjects\SPIDevice, and a single transfer segment is described by Microscrap\Bindings\SPI\DataObjects\SPITransfer.

Example — read a register from an SPI peripheral

Example — chained, multi-segment transfer

spi_transfer accepts any number of SPITransfer segments. Each segment is sent back-to-back as a single SPI_IOC_MESSAGE transaction; CS is held low between segments unless a segment sets csChange: true.

See examples/as3935-autotune.php for a complete AS3935 antenna-autotune script that combines spi_transfer, GPIO edge events, and kernel hardware timestamps.

API Reference

Device lifecycle and I/O

spi_open validates each ioctl as it goes and closes the descriptor on any failure, so a non-null return guarantees the device is configured. The mode parameter is the same SPIMode bitmask the kernel uses (SPI_IOC_WR_MODE32).

Configuration (ioctl)

All setters return 0 on success and -1 on failure. Getters return the raw integer (or bool for lsb_first), and -1 on ioctl failure for the int-returning ones. Mask spi_get_mode against SPIMode cases to test individual mode bits.

Full-duplex transfers

spi_transfer(SPIDevice $dev, SPITransfer ...$transfers): string|false

Issues a single SPI_IOC_MESSAGE(n) ioctl bundling n transfer segments. CS is asserted at the start of the first segment and stays asserted across all segments unless an individual segment requests otherwise via csChange. Returns the concatenated MISO bytes from every segment (length equals the sum of each segment's len), or false if the transaction fails.

Two paths are supported transparently:

1. Native fast path — if a low-level extension exposes spi_transfer(int $fd, …) (note the int first argument), it is used directly.
2. ext-posi fallback — otherwise the call packs each spi_ioc_transfer struct manually using posi_mem_alloc / posi_mem_write / posi_mem_read and issues SPI_IOC_MESSAGE(1) per segment. This is the supported path for plain ext-posi installations.

If neither path is available, spi_transfer returns false.

Data objects

SPIDevice

The mode, speed, and bitsPerWord fields record the values passed to spi_open and are not updated when you later call spi_set_mode / spi_set_speed / spi_set_bits_per_word. Use the matching getter for the live kernel value.

SPITransfer

Notes:

• $tx is right-padded with NUL bytes if shorter than $len, and truncated if longer.
• For read-only segments pass tx: str_repeat("\0", $len) (or any dummy bytes — the slave ignores them on a pure read).
• csChange semantics are inverted from intuition: setting it true requests CS de-assert after this segment, which is what you want for "this is the last byte of a logical message" inside a chain.
• The dual/quad/octal lane fields require a controller and slave that support SPI multi-IO; leave them at 0 for standard single-MOSI/MISO operation.

Enums

All enums are int-backed with SCREAMING_SNAKE_CASE cases that map directly to kernel constants.

SPIMode — mode bitmask (SPI_IOC_WR_MODE32)

The classical "SPI mode 0..3" values are simply CPOL/CPHA combinations:

SPIOpCode — ioctl request numbers (<linux/spi/spidev.h>)

SPIOpCode::messageN(int $n): int computes the variant SPI_IOC_MESSAGE(n) ioctl number for batched transfers:

Quick reference

Notes

• Half-duplex vs full-duplex. spi_read and spi_write operate on the kernel's posix_read / posix_write path, which is half-duplex — the kernel clocks out dummy bytes on a read and ignores MISO on a write. For real full-duplex transactions (where the bytes you receive correspond byte-for-byte to the bytes you transmit), use spi_transfer with one or more SPITransfer segments.
• CS behavior. A single spi_transfer call holds CS low across every segment by default. Set csChange: true on a segment to release CS after it. Use SPIMode::NO_CS if your driver provides CS via a GPIO instead of the controller.
• Word size on Linux. Most spidev drivers only support 8-bit words. Setting bitsPerWord to anything else may return -1 on platforms that don't support it.
• Speed. The configured speed is an upper bound. The kernel rounds down to the closest divider the SPI controller can produce; query spi_get_speed afterwards if exact-rate behavior matters.
• Concurrency. Linux serialises access to a spidev character device per file descriptor. If you need overlapping transactions, open the same device twice — but the kernel will still serialise them on the bus.

License

MIT. See LICENSE.