From 794e6ddd7e06fbdb541ecd02289a3476b3810352 Mon Sep 17 00:00:00 2001
From: Drahoslav <drahoslav@yo2.cz>
Date: Fri, 5 Oct 2018 17:04:53 +0200
Subject: [PATCH] Improve doc

---
 rpio.go     | 12 +++++++++---
 spi.go      | 39 ++++++++++++++++++++++++---------------
 spi_test.go | 27 +++++++++++++++++----------
 3 files changed, 50 insertions(+), 28 deletions(-)

diff --git a/rpio.go b/rpio.go
index 50017c6..f4aeef3 100644
--- a/rpio.go
+++ b/rpio.go
@@ -8,9 +8,13 @@ Supports simple operations such as:
 	- Pin read (high/low)
 	- Pin edge detection (no/rise/fall/any)
 	- Pull up/down/off
-And clock/pwm related oparations:
+Also clock/pwm related oparations:
 	- Set Clock frequency
 	- Set Duty cycle
+And SPI oparations:
+	- SPI transmit/recieve/exchange bytes
+	- Chip select
+	- Set speed
 
 Example of use:
 
@@ -238,10 +242,12 @@ func (pin Pin) EdgeDetected() bool {
 	return EdgeDetected(pin)
 }
 
-// PinMode sets the mode (direction) of a given pin (Input, Output, Clock or Pwm)
+// PinMode sets the mode of a given pin (Input, Output, Clock, Pwm or Spi)
 //
 // Clock is possible only for pins 4, 5, 6, 20, 21.
 // Pwm is possible only for pins 12, 13, 18, 19.
+//
+// Spi mode should not be set by this directly, use SpiBegin instead.
 func PinMode(pin Pin, mode Mode) {
 
 	// Pin fsel register, 0 or 1 depending on bank
@@ -296,7 +302,7 @@ func PinMode(pin Pin, mode Mode) {
 	memlock.Lock()
 	defer memlock.Unlock()
 
-	const pinMask = 7 // 0b111 - pinmode is 3 bits
+	const pinMask = 7 // 111 - pinmode is 3 bits
 
 	gpioMem[fselReg] = (gpioMem[fselReg] &^ (pinMask << shift)) | (f << shift)
 }
diff --git a/spi.go b/spi.go
index 1e40d01..03368cd 100644
--- a/spi.go
+++ b/spi.go
@@ -1,14 +1,17 @@
-// SPI functionality is implemented here
 package rpio
 
 import (
 	"errors"
 )
 
+type SpiDev int
+
+// SPI devices.
+// Only SPI0 supported for now.
 const (
-	SPI0 = iota // only SPI0 supported for now
-	SPI1        // aux
-	SPI2        // aux
+	Spi0 SpiDev = iota
+	Spi1        // aux
+	Spi2        // aux
 )
 
 const (
@@ -21,10 +24,16 @@ var (
 	SpiMapError = errors.New("SPI registers not mapped correctly - are you root?")
 )
 
-// Sets SPI pins of given device to SPI mode
-// (CE0, CE1, [CE2], SCLK, MOSI, MISO).
+// Sets all pins of given SPI device to SPI mode
+//  dev\pin | CE0 | CE1 | CE2 | SCLK | MOSI | MISO |
+//  Spi0    |   7 |   8 |   - |    9 |   10 |   11 |
+//  Spi1    |  16 |  17 |  18 |   19 |   20 |   21 |
+//  Spi2    |  40 |  41 |  42 |   43 |   44 |   45 |
+//
 // It also resets SPI control register.
-func SpiBegin(dev int) error {
+//
+// Note that you should disable SPI interface in raspi-config first!
+func SpiBegin(dev SpiDev) error {
 	spiMem[csReg] = 0 // reset spi settings to default
 	if spiMem[csReg] == 0 {
 		// this should not read only zeroes after reset -> mem map failed
@@ -40,8 +49,8 @@ func SpiBegin(dev int) error {
 	return nil
 }
 
-// Sets SPI pins of given device to default (Input) mode.
-func SpiEnd(dev int) {
+// Sets SPI pins of given device to default (Input) mode. See SpiBegin.
+func SpiEnd(dev SpiDev) {
 	var pins = getSpiPins(dev)
 	for _, pin := range pins {
 		pin.Mode(Input)
@@ -122,8 +131,8 @@ func SpiExchange(data []byte) {
 }
 
 // set spi clock divider value
-func setSpiDiv(cdiv uint32) {
-	const cdivMask = 1<<16 - 1 - 1 // cdiv have 16 bits and must be odd (for some reason)
+func setSpiDiv(div uint32) {
+	const divMask = 1<<16 - 1 - 1 // cdiv have 16 bits and must be odd (for some reason)
 	spiMem[clkDivReg] = div & divMask
 }
 
@@ -133,14 +142,14 @@ func clearSpiTxRxFifo() {
 	spiMem[csReg] |= clearTxRx
 }
 
-func getSpiPins(dev int) []Pin {
+func getSpiPins(dev SpiDev) []Pin {
 	switch dev {
-	case SPI0:
+	case Spi0:
 		return []Pin{7, 8, 9, 10, 11}
 		// ommit 35, 36, 37, 38, 39 - only one set of SPI0 can be set in Spi mode at a time
-	case SPI1:
+	case Spi1:
 		return []Pin{16, 17, 18, 19, 20, 21}
-	case SPI2:
+	case Spi2:
 		return []Pin{40, 41, 42, 43, 44, 45}
 	default:
 		return []Pin{}
diff --git a/spi_test.go b/spi_test.go
index 8348011..36dae12 100644
--- a/spi_test.go
+++ b/spi_test.go
@@ -2,15 +2,22 @@ package rpio
 
 import ()
 
-func Example_SPI() {
-	SpiBegin(SPI0) // BCM pins 7 to 11
+func ExampleSpiTransmit() {
+	SpiTransmit(0xFF)             // send single byte
+	SpiTransmit(0xDE, 0xAD, 0xBE) // send several bytes
 
-	SpiSpeed(144000) // 144kHz
-	SpiChipSelect(1) // CE1
-
-	SpiTransmit(0xFF)
-	SpiTransmit(0xDE, 0xAD)
-	SpiTransmit(data...)
-
-	SpiEnd(SPI0)
+	data := []byte{'H', 'e', 'l', 'l', 'o', 0}
+	SpiTransmit(data...) // send slice of bytes
+}
+
+func ExampleSpiBegin() {
+	err := SpiBegin(Spi0) // pins 7 to 11
+	if err != nil {
+		panic(err)
+	}
+
+	// any Spi functions must go there...
+	SpiTransmit(42)
+
+	SpiEnd(Spi0)
 }