php-linux-gpio/README.md

Linux Userspace GPIO Library
============================

Current and planned features:

 * Export and Unexport GPIO pins via sysfs
 * Interrupt support (*)
 * Hardware-neutral rewrite of NoccyLabs RaspIO 
 * Compatible with psr/logs LoggerInterface for logging
 * Bit-banged SPI/I2C/1Wire


## Gpio

Without a mapper active, the GPIOs adressed are the direct exported GPIO numbers,
not necessarily in any logical order. Requesting `$gpio[22]` gives you `GPIO22`.

    $gpio = new Gpio();
    $gpio1 = $gpio[1];


### With a Mapper

With a mapper the pins are arranged logically starting at 0. For example, with
the WiringPi mapper, `$gpio[0]` would return `GPIO17` and so on. The `GpioPin#getPin()`
method will still return the actual GPIO (i.e. *17* rather than *0*).

    $gpio = new Gpio();
    $mapper = new WiringPiMapper(2);
    $gpio->setMapper($mapper);

    $gpio17 = $gpio[0];


## Interrupts

*NOTE: Not implemented!*

For interrupts to work, you need to first bind the interrupt handler, and then
make sure to call on `Gpio#refresh()` every cycle to poll the interrupt flag on
the selected pins. This is because the `select()` function is used.

    $gpio = new Gpio();

    // Set the handler on the Gpio object
    $gpio->setInterruptHandler($gpio[4], function() { ... });
    // Or like this on the GpioPin.
    $gpio[4]
        ->setEdge("rising")
        ->setHandler(function() { ... });
    
    while (..) {
        ..
        $gpio->refresh();
    }

You can also be risky and use php ticks and timerfuncs (although that might not
be portable/supported/efficient/a good idea):

    declare(ticks=5);
    
    $gpio = new Gpio();
    
    $gpiotick = new GpioTickHandler();
    $gpiotick->registerGpio($gpio);
    
    // The interrupts will now be polled approx every 5th php vm "tick"


## Parallel addressing of pins

*Implemented in* ***0.1.x***

    $gpio = new Gpio();
    $gpio->setMapper( new WiringPiMapper(2) );

    $par = new BitmappedGpio();
    for($n = 0; $n < 7; $n++) {
	    $pin = $gpio[$n]->setDirection("out");
        $par->setGpioPin($n,$pin);
    }
    $par->write(0x55); // turn on 1, 3, 5, 7.

        
## Buses

*Not yet implemented*

    $bus = new NoccyLabs\Gpio\Bus\SoftwareSpiBus;
    $bus->mosi = $gpio[2];
    $bus->sclk = $gpio[9];
    $bus->write("\0x10\0x20\0x40");
    $r = $bus->read(3);


## Devices

    $lcd = new NoccyLabs\Gpio\Device\Display\Pcd8544Device;
    // Set I/O pins
    $lcd->res = $gpio[4];
    $lcd->dc  = $gpio[8];
    ...
    // Activate the device
    $lcd->activate();
    // Clear and draw text
    $lcd->clear();
    $lcd->writeAt(0,0,"Hello World");
    echo $lcd->getRows(); // 5
    echo $lcd->getCols(); // 19