Added bit banging to README

Volantus · Jan 2, 2018 · 887b359 · 887b359
1 parent 49b9012
commit 887b359
Show file tree

Hide file tree

Showing 2 changed files with 87 additions and 50 deletions.
diff --git a/README.md b/README.md
@@ -14,7 +14,7 @@ Deployment via official DEB repository is planned.
 Download the latest shared object and include it into php.ini:
 ```bash
 cd /usr/lib/php/$(php -v | grep -i 'PHP [57]' | cut -c1-8 | sed s/'PHP '//g | cut -c1-3)
-wget https://github.com/Volantus/berry-spi/releases/download/0.0.2/berry-spi.so
+wget https://github.com/Volantus/berry-spi/releases/download/0.1.0/berry-spi.so
 sudo echo "extension=berry-spi.so" >> /etc/php/7.0/cli/php.ini
 ```
 ## Compile from source
@@ -29,8 +29,11 @@ sudo make install
 
 
 # Usage
-Communication is handled by the RegularInterface class. (Implementation of BitBanging is planned for the near future)
+Communication is handled by the following classes
+* RegularInterface: In case of using the native SPI pins (GPIO 07 - 11)
+* BitBangingInterface: In case of using any other GPIO pins
 
+## Regular interface
 ```PHP
 use Volantus\BerrySpi\RegularInterface;
 
@@ -52,7 +55,7 @@ $interface->write('abc');
 $interface->close();
 ```
 
-## Parameters
+### Parameters
 The constructor accept three parameters
 
 | Parameter     | Description                                                                             |
@@ -62,45 +65,55 @@ The constructor accept three parameters
 |               | 32K-125M (values above 30M are unlikely to work)                                        |
 | flags         | Additional configuration, see [details](http://abyz.me.uk/rpi/pigpio/cif.html#spiOpen)  |
 
+### Bit banging interface
+```PHP
+use Volantus\BerrySpi\BitBangingInterface;
+
+$interface = new BitBangingInterface(12, 16, 20, 21, 512, 0);
+
+// Opening the connection
+$interface->open();
+
+// Sending + retrieving data simustanisly
+$retrievedData = $interface->transfer(0x1269493);
+
+// Don't forget to close the connection
+$interface->close();
+```
+
+### Parameters
+The constructor accept three parameters
+
+| Parameter     | Description                                                                              |
+| ------------- |------------------------------------------------------------------------------------------|
+| csPin         | The GPIO (0-31) used for the slave select signal *¹                                      |
+| misoPin       | The GPIO (0-31) used for the MISO signal *²                                              |
+| mosiPin       | The GPIO (0-31) used for the MOSI signal *²                                              |
+| sclkPin       | The GPIO (0-31) used for the SCLK signal *²                                              |
+| speed         | Baud speed in bits per second                                                            |
+|               | 50-250k                                                                                  |
+| flags         | Additional configuration, see [details](http://abyz.me.uk/rpi/pigpio/cif.html#bbSpiOpen) |
+
+*¹ This pin has to be unique for each device
+
+*² This pin can be shared with multiple slave devices, if no parallel data transfer is required
+
 ## Error handling
-All errors are wrapped in exceptions within the namespace Volantus\BerrySpi
-### RegularInterface::__construct
-* Volantus\BerrySpi\InvalidArgumentException
-  * Negative value for channel, speed or flag given
-* Volantus\BerrySpi\GpioInitFailureException
-  * Pigpio library initialization failed (e.g. insufficient permissions)
-
-### RegularInterface::open
-* Volantus\BerrySpi\InvalidArgumentException
-  * Invalid channel, speed or flag parameter (reported by pigpio library) or no aux available
-* Volantus\BerrySpi\LogicException
-  * Device already opened
-* Volantus\BerrySpi\RuntimeException
-  * In case of deeper unknown errors
-
-### RegularInterface::close
-* Volantus\BerrySpi\LogicException
-  * Device not open
-* Volantus\BerrySpi\RuntimeException
-  * In case of deeper unknown errors
-
-### RegularInterface::transfer
-* Volantus\BerrySpi\LogicException
-  * Device not open
-* Volantus\BerrySpi\RuntimeException
-  * In case of deeper unknown errors (e.g. PI_BAD_SPI_COUNT)
-
-### RegularInterface::read
-* Volantus\BerrySpi\LogicException
-  * Device not open
-* Volantus\BerrySpi\RuntimeException
-  * In case of deeper unknown errors (e.g. PI_BAD_SPI_COUNT)
-
-### RegularInterface::write
-* Volantus\BerrySpi\LogicException
-  * Device not open
-* Volantus\BerrySpi\RuntimeException
-  * In case of deeper unknown errors (e.g. PI_BAD_SPI_COUNT)
+All errors are wrapped in exceptions within the namespace Volantus\BerrySpi.
+To see which method throws which exception please consult the stubs.
+
+### Volantus\BerrySpi\InvalidArgumentException
+In case of invalid parameters (e.g. negative channel or bad speed).
+
+### Volantus\BerrySpi\GpioInitFailureException
+Pigpio library initialization failed (e.g. insufficient permissions).
+
+### Volantus\BerrySpi\LogicException
+In case of logically incorrect behaviour (e.g. trying to send data by an non-open connection).
+
+### Volantus\BerrySpi\RuntimeException
+In case of deeper problems (e.g. internal failure).
+
 
 # Contribution
 Contribution in form of bug reports, suggestions or pull requests is highly welcome!

diff --git a/stubs/_ide_helper.php b/stubs/_ide_helper.php
@@ -15,20 +15,30 @@ class RegularInterface
      * @param int $speed   Baud speed in bits per second
      *                     32K-125M (values above 30M are unlikely to work)
      * @param int $flags   Additional flags
+     *
+     * @throws InvalidArgumentException
+     * @throws GpioInitException
      */
     public function __construct(int $channel, int $speed, int $flags)
     {
     }
 
     /**
      * @return void
+     *
+     * @throws InvalidArgumentException
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function open()
     {
     }
 
     /**
      * @return void
+     *
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function close()
     {
@@ -69,6 +79,9 @@ public function isOpen(): bool
      * @param string $data Data to send to device
      *
      * @return string data received by the SPI device
+     *
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function transfer(string $data): string
     {
@@ -80,6 +93,10 @@ public function transfer(string $data): string
      * @param int $count Count of bytes to read
      *
      * @return string data read by the SPI device
+     *
+     * @throws InvalidArgumentException
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function read(int $count): string
     {
@@ -89,6 +106,9 @@ public function read(int $count): string
      * Sends data to the SPI device
      *
      * @param string $data
+     *
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function write(string $data)
     {
@@ -113,6 +133,9 @@ class BitBangingInterface
      * @param int $flags   Additional flags
      *
      * @internal param int $channel Regular SPI channel (0 or 1)
+     *
+     * @throws InvalidArgumentException
+     * @throws GpioInitException
      */
     public function __construct(int $csPin, int $misoPin, int $mosiPin, int $sclkPin, int $speed, int $flags)
     {
@@ -124,13 +147,20 @@ public function __construct(int $csPin, int $misoPin, int $mosiPin, int $sclkPin
 
     /**
      * @return void
+     *
+     * @throws InvalidArgumentException
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function open()
     {
     }
 
     /**
      * @return void
+     *
+     * @throws LogicException
+     * @throws RuntimeException
      */
     public function close()
     {
@@ -192,6 +222,9 @@ public function isOpen(): bool
      * @param string $data Data to send to device
      *
      * @return string data received by the SPI device
+     *
+     * @throws RuntimeException
+     * @throws LogicException
      */
     public function transfer(string $data): string
     {
@@ -225,15 +258,6 @@ class LogicException extends \Exception
 {
 }
 
-/**
- * Class GpioFailureException
- *
- * @package Volantus\BerrySpi
- */
-class GpioFailureException extends \Exception
-{
-}
-
 /**
  * Class GpioFailureException
  *