Update README.md

Cleaned up and clarified, mostly in the Usage section, and added a section on using SPI (closes #62).

README.md

@@ -6,8 +6,7 @@ For support, comments, questions, etc please join the WiringPi Discord channel:
 
 # WiringPi for Python
 
-WiringPi: An implementation of most of the Arduino Wiring
+WiringPi: An implementation of most of the Arduino Wiring functions for the Raspberry Pi.
-	functions for the Raspberry Pi
 
 WiringPi implements new functions for managing IO expanders.
 
@@ -17,66 +16,93 @@ WiringPi implements new functions for managing IO expanders.
 
 # Usage
 
-	import wiringpi
+```python
+import wiringpi
 
-	wiringpi.wiringPiSetup() # For sequential pin numbering, one of these MUST be called before using IO functions
+# One of the following MUST be called before using IO functions:
-	# OR
+wiringpi.wiringPiSetup()      # For sequential pin numbering
-	wiringpi.wiringPiSetupSys() # For /sys/class/gpio with GPIO pin numbering
+# OR
-	# OR
+wiringpi.wiringPiSetupSys()   # For /sys/class/gpio with GPIO pin numbering
-	wiringpi.wiringPiSetupGpio() # For GPIO pin numbering
+# OR
-
+wiringpi.wiringPiSetupGpio()  # For GPIO pin numbering
-
+```
-Setting up IO expanders (This example was tested on a quick2wire board with one digital IO expansion board connected via I2C):
-
-	wiringpi.mcp23017Setup(65,0x20)
-	wiringpi.pinMode(65,1)
-	wiringpi.digitalWrite(65,1)
 
 **General IO:**
 
-	wiringpi.pinMode(6,1) # Set pin 6 to 1 ( OUTPUT )
+```python
-	wiringpi.digitalWrite(6,1) # Write 1 ( HIGH ) to pin 6
+wiringpi.pinMode(6, 1)       # Set pin 6 to 1 ( OUTPUT )
-	wiringpi.digitalRead(6) # Read pin 6
+wiringpi.digitalWrite(6, 1)  # Write 1 ( HIGH ) to pin 6
+wiringpi.digitalRead(6)      # Read pin 6
+```
 
 **Setting up a peripheral:**
-WiringPi2 supports expanding your range of available "pins" by setting up a port expander. The implementation details of
+
-your port expander will be handled transparently, and you can write to the additional pins ( starting from PIN_OFFSET >= 64 )
+WiringPi supports expanding your range of available "pins" by setting up a port expander. The implementation details of
+your port expander will be handled transparently, and you can write to the additional pins (starting from PIN_OFFSET >= 64)
 as if they were normal pins on the Pi.
 
-	wiringpi.mcp23017Setup(PIN_OFFSET,I2C_ADDR)
+```python
+wiringpi.mcp23017Setup(PIN_OFFSET, I2C_ADDR)
+```
+
+This example was tested on a quick2wire board with one digital IO expansion board connected via I2C:
+
+```python
+wiringpi.mcp23017Setup(65, 0x20)
+wiringpi.pinMode(65, 1)
+wiringpi.digitalWrite(65, 1)
+```
 
-**Soft Tone**
+**Soft Tone:**
 
 Hook a speaker up to your Pi and generate music with softTone. Also useful for generating frequencies for other uses such as modulating A/C.
 
-	wiringpi.softToneCreate(PIN)
+```python
-	wiringpi.softToneWrite(PIN,FREQUENCY)
+wiringpi.softToneCreate(PIN)
+wiringpi.softToneWrite(PIN, FREQUENCY)
+```
 
 **Bit shifting:**
 
-	wiringpi.shiftOut(1,2,0,123) # Shift out 123 (b1110110, byte 0-255) to data pin 1, clock pin 2
+```python
+wiringpi.shiftOut(1, 2, 0, 123)  # Shift out 123 (b1110110, byte 0-255) to data pin 1, clock pin 2
+```
 
 **Serial:**
 
-	serial = wiringpi.serialOpen('/dev/ttyAMA0',9600) # Requires device/baud and returns an ID
+```python
-	wiringpi.serialPuts(serial,"hello")
+serial = wiringpi.serialOpen('/dev/ttyAMA0', 9600)  # Requires device/baud and returns an ID
-	wiringpi.serialClose(serial) # Pass in ID
+wiringpi.serialPuts(serial, "hello")
+wiringpi.serialClose(serial)  # Pass in ID
+```
+
+**SPI:**
 
-**Full details at:**
+The `wiringPiSPIDataRW()` function needs to be passed a `bytes` object in Python 3.  In Python 2, it takes a string.  The following should work in either Python 2 or 3:
+```python
+wiringpi.wiringPiSPISetup(channel, speed)
+buf = bytes([your data here])
+retlen, retdata = wiringpi.wiringPiSPIDataRW(0, buf)
+```
+Now, `retlen` will contain the number of bytes received/read by the call.  `retdata` will contain the data itself, and in Python 3, `buf` will have been modified to contain it as well (that won't happen in Python 2, because then `buf` is a string, and strings are immutable).
+
+**Full details of the API at:**
 http://www.wiringpi.com
 
 # Manual Build
 
 ## Get/setup repo
+
 ```bash
 git clone --recursive https://github.com/WiringPi/WiringPi-Python.git
 cd WiringPi-Python
 ```
+Don't forget the `--recursive`; it is required to also pull in the WiringPi C code from its own repository.
 
 ## Prerequisites
-To rebuild the bindings
+
-you **must** first have python-dev, python-setuptools and swig installed. Wiring Pi should also be installed system-wide
+To rebuild the bindings you **must** first have installed `swig`, `python-dev`, and `python-setuptools` (or their `python3-` equivalents).
-for access to the `gpio` tool.
+WiringPi should also be installed system-wide for access to the `gpio` tool.
 ```bash
 sudo apt-get install python-dev python-setuptools swig wiringpi
 ```