PHPackages                             microscrap/native-drivers - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. microscrap/native-drivers

ActiveLibrary

microscrap/native-drivers
=========================

The Official ScrapyardIO Native Drivers package.

0.5.0(1mo ago)00MITPHP ^8.3

Since Jul 12Compare

[ Source](https://github.com/microscrap/scrapyard-native-drivers)[ Packagist](https://packagist.org/packages/microscrap/native-drivers)[ Docs](https://scrapyard-io.projectsaturnstudios.com)[ RSS](/packages/microscrap-native-drivers/feed)WikiDiscussions Synced 1mo ago

READMEChangelogDependencies (3)Versions (4)Used By (0)

microscrap/native-drivers - The Official ScrapyardIO Native Drivers package
===========================================================================

[](#microscrapnative-drivers---the-official-scrapyardio-native-drivers-package)

PHP driver package that provides the `native` carrier for the [ScrapyardIO framework](https://github.com/ScrapyardIO/framework) GPIO stack. It drives **hardware PWM** on Linux single-board computers through the kernel sysfs PWM interface (`/sys/class/pwm/pwmchipN`) using ordinary PHP file I/O — no `ext-posi`, `ext-ftdi`, or Microscrap binding package is required for PWM itself.

This package includes:

- The `ScrapyardIONativeManager` carrier manager, auto-discovered by the framework via the `#[CarrierDriver('native')]` attribute
- A sysfs-backed PWM driver (`NativePWMDriver`) that exports channels, reads/writes `period` / `duty_cycle` / `enable` / `polarity`, and unexports cleanly on close
- Multi-channel support — open several channels on the same pwmchip and get a `MultiplePWMChannels` bus back

**Digital GPIO, SPI, I²C, and UART are not part of this package.** On Linux SBCs those protocols use [`microscrap/posix-drivers`](https://github.com/microscrap/scrapyard-posix-drivers) (`GPIO::*('posix')`). USB/FTDI adapters use [`microscrap/usb-drivers`](https://github.com/microscrap/scrapyard-usb-drivers).

### Which carrier should I use?

[](#which-carrier-should-i-use)

CarrierPackageUse when`native`this packageHardware PWM via `/sys/class/pwm` only`posix`[`microscrap/posix-drivers`](https://github.com/microscrap/scrapyard-posix-drivers)Linux SBC digital / SPI / I²C / UART`usb`[`microscrap/usb-drivers`](https://github.com/microscrap/scrapyard-usb-drivers)FTDI adapters over MPSSE / serialOlder docs sometimes call the Linux bus stack `native`. For digital / SPI / I²C / UART on an SBC today, use **`posix`**. Use **`native` only for PWM**.

Requirements
------------

[](#requirements)

- PHP 8.3+
- A Linux machine that exposes `/sys/class/pwm` (hardware PWM capable — Raspberry Pi, many other SBCs)
- Write access to the pwmchip sysfs nodes (often root, or membership in a group that udev grants access to after export)
- [`waveforms/common`](https://github.com/ScrapyardIO/framework) ^0.5.0, [`waveforms/contracts`](https://github.com/ScrapyardIO/framework) ^0.5.0, and [`scrapyard-io/nuts-and-bolts`](https://github.com/ScrapyardIO/framework) ^0.5.0 — direct Composer requirements of this package
- [`waveforms/pwm`](https://github.com/ScrapyardIO/framework) ^0.5.0 (or the full [`scrapyard-io/framework`](https://github.com/ScrapyardIO/framework) metapackage) in the consuming app — required by `NativePWMDriver` / `NativePWMHandle` (`GPIO\PWM\*`) and by the `GPIO::pwm(...)` factory shown below

### Device addressing

[](#device-addressing)

Factory callMeaningSysfs path`->device(0)`pwmchip **number** `0``/sys/class/pwm/pwmchip0``->device('0')`numeric string chip number (same as `0`)`/sys/class/pwm/pwmchip0``->device('pwmchip0')` or `->device('/sys/class/pwm/pwmchip0')`trailing `pwmchipN` is parsed`/sys/class/pwm/pwmchip0``->channel(2)`channel offset on that chip…`/pwm2` after exportConfirm available chips with `ls /sys/class/pwm/`. On a Raspberry Pi 5, `pwmchip0` channel `2` is a common hobby-servo / fan PWM path once the board's PWM overlay / pinmux is enabled.

### Units and polarity

[](#units-and-polarity)

Kernel PWM sysfs attributes use **nanoseconds**:

- `setPeriod($ns)` / `getPeriod()` — full waveform period in ns (e.g. `20_000_000` for 50 Hz / 20 ms)
- `setDutyCycle($ns)` / `getDutyCycle()` — high time in ns (must be ≤ period)
- `setPolarity('normal'|'inversed')` — any other string throws `NativePWMException::invalidPolarity`

Set the period **before** raising the duty cycle when starting from a fresh export; the kernel rejects a duty larger than the current period.

Installation
------------

[](#installation)

```
composer require microscrap/native-drivers
```

Confirm the host exposes PWM:

```
ls /sys/class/pwm
```

If `/sys/class/pwm` is missing, the manager throws a `GPIOException` when a PWM driver is requested: *"The Native driver requires native support to work with PWM."*

How it works
------------

[](#how-it-works)

The framework resolves the `native` carrier through attribute-based discovery — no manual registration:

```
GPIO::pwm('native')->…->create()
  └─ PWMConnectionFactory               (scrapyard-io/framework)
       └─ GPIOCarriers::native('pwm')
            └─ ScrapyardIONativeManager  (#[CarrierDriver('native')], this package)
                 └─ NativePWMDriver
                      └─ /sys/class/pwm/pwmchip{N}/export → pwm{M}/{period,duty_cycle,enable,polarity}

```

ProtocolDriverBackend`pwm``NativePWMDriver`Linux PWM sysfs (`pwmchip` export / attribute files)On `create()`, the driver exports the channel if needed, then waits up to ~500 ms for udev to make `period` writable before returning a `PWMChannel`. On `close()`, it writes `enable=0` and unexports the channel.

Usage
-----

[](#usage)

All examples go through the framework's `GPIO` facade with the `native` driver.

### Single PWM channel

[](#single-pwm-channel)

```