add documentation

digitalpin.go

@@ -1,3 +1,7 @@
+// Digital IO support.
+// This driver requires kernel version 3.8+ and should work uniformly
+// across all supported devices.
+
 package embd
 
 import (

gpio.go

@@ -1,50 +1,84 @@
+// GPIO support.
+
 package embd
 
+// The Direction type indicates the direction of a GPIO pin.
 type Direction int
 
 const (
+	// In represents read mode.
 	In Direction = iota
+
+	// Out represents write mode.
 	Out
 )
 
 const (
+	// Low represents 0.
 	Low int = iota
+
+	// High represents 1.
 	High
 )
 
+// DigitalPin implements access to a digital IO capable GPIO pin.
 type DigitalPin interface {
+	// N returns the logical GPIO number.
 	N() int
 
+	// Write writes the provided value to the pin.
 	Write(val int) error
+
+	// Read reads the value from the pin.
 	Read() (int, error)
 
+	// SetDirection sets the direction of the pin (in/out).
 	SetDirection(dir Direction) error
+
+	// ActiveLow makes the pin active low. A low logical state is represented by
+	// a high state on the physical pin, and vice-versa.
 	ActiveLow(b bool) error
 
+	// PullUp pulls the pin up.
 	PullUp() error
+
+	// PullDown pulls the pin down.
 	PullDown() error
 
+	// Close releases the resources associated with the pin.
 	Close() error
 }
 
+// AnalogPin implements access to a analog IO capable GPIO pin.
 type AnalogPin interface {
+	// N returns the logical GPIO number.
 	N() int
 
+	// Write writes the provided value to the pin.
 	Write(val int) error
+
+	// Read reads the value from the pin.
 	Read() (int, error)
 
+	// Close releases the resources associated with the pin.
 	Close() error
 }
 
+// GPIODriver implements a generic GPIO driver.
 type GPIODriver interface {
+	// DigitalPin returns a pin capable of doing digital IO.
 	DigitalPin(key interface{}) (DigitalPin, error)
+
+	// AnalogPin returns a pin capable of doing analog IO.
 	AnalogPin(key interface{}) (AnalogPin, error)
 
+	// Close releases the resources associated with the driver.
 	Close() error
 }
 
 var gpioDriverInstance GPIODriver
 
+// InitGPIO initializes the GPIO driver.
 func InitGPIO() error {
 	desc, err := DescribeHost()
 	if err != nil {
@@ -60,14 +94,18 @@ func InitGPIO() error {
 	return nil
 }
 
+// CloseGPIO releases resources associated with the GPIO driver.
 func CloseGPIO() error {
 	return gpioDriverInstance.Close()
 }
 
+// NewDigitalPin returns a DigitalPin interface which allows control over
+// the digital GPIO pin.
 func NewDigitalPin(key interface{}) (DigitalPin, error) {
 	return gpioDriverInstance.DigitalPin(key)
 }
 
+// DigitalWrite writes val to the pin.
 func DigitalWrite(key interface{}, val int) error {
 	pin, err := NewDigitalPin(key)
 	if err != nil {
@@ -77,6 +115,7 @@ func DigitalWrite(key interface{}, val int) error {
 	return pin.Write(val)
 }
 
+// DigitalRead reads a value from the pin.
 func DigitalRead(key interface{}) (int, error) {
 	pin, err := NewDigitalPin(key)
 	if err != nil {
@@ -86,6 +125,7 @@ func DigitalRead(key interface{}) (int, error) {
 	return pin.Read()
 }
 
+// SetDirection sets the direction of the pin (in/out).
 func SetDirection(key interface{}, dir Direction) error {
 	pin, err := NewDigitalPin(key)
 	if err != nil {
@@ -95,6 +135,8 @@ func SetDirection(key interface{}, dir Direction) error {
 	return pin.SetDirection(dir)
 }
 
+// ActiveLow makes the pin active low. A low logical state is represented by
+// a high state on the physical pin, and vice-versa.
 func ActiveLow(key interface{}, b bool) error {
 	pin, err := NewDigitalPin(key)
 	if err != nil {
@@ -104,10 +146,33 @@ func ActiveLow(key interface{}, b bool) error {
 	return pin.ActiveLow(b)
 }
 
+// PullUp pulls the pin up.
+func PullUp(key interface{}) error {
+	pin, err := NewDigitalPin(key)
+	if err != nil {
+		return err
+	}
+
+	return pin.PullUp()
+}
+
+// PullDown pulls the pin down.
+func PullDown(key interface{}) error {
+	pin, err := NewDigitalPin(key)
+	if err != nil {
+		return err
+	}
+
+	return pin.PullDown()
+}
+
+// NewAnalogPin returns a AnalogPin interface which allows control over
+// the analog GPIO pin.
 func NewAnalogPin(key interface{}) (AnalogPin, error) {
 	return gpioDriverInstance.AnalogPin(key)
 }
 
+// AnalogWrite writes the provided value to the pin.
 func AnalogWrite(key interface{}, val int) error {
 	pin, err := NewAnalogPin(key)
 	if err != nil {
@@ -117,6 +182,7 @@ func AnalogWrite(key interface{}, val int) error {
 	return pin.Write(val)
 }
 
+// AnalogWrite reads a value from the pin.
 func AnalogRead(key interface{}) (int, error) {
 	pin, err := NewAnalogPin(key)
 	if err != nil {

gpiodriver.go

@@ -1,3 +1,5 @@
+// Generic GPIO driver.
+
 package embd
 
 import (

i2c.go

@@ -52,12 +52,12 @@ func InitI2C() error {
 	return nil
 }
 
-// CloseI2C gracefully closes the I2C driver.
+// CloseI2C releases resources associated with the I2C driver.
 func CloseI2C() error {
 	return i2cDriverInstance.Close()
 }
 
-// NewI2CBus returns a I2CBus corresponding to the provided address.
+// NewI2CBus returns a I2CBus.
 func NewI2CBus(l byte) I2CBus {
 	return i2cDriverInstance.Bus(l)
 }

i2cdriver.go

@@ -1,3 +1,5 @@
+// Generic I2C driver.
+
 package embd
 
 import (

led.go

@@ -4,11 +4,16 @@ package embd
 
 // The LED interface is used to control a led on the prototyping board.
 type LED interface {
+	// On switches the LED on.
 	On() error
+
+	// Off switches the LED off.
 	Off() error
 
+	// Toggle toggles the LED.
 	Toggle() error
 
+	// Close releases resources associated with the LED.
 	Close() error
 }
 
@@ -38,18 +43,17 @@ func InitLED() error {
 	return nil
 }
 
-// CloseLED gracefully closes the LED driver.
+// CloseLED releases resources associated with the LED driver.
 func CloseLED() error {
 	return ledDriverInstance.Close()
 }
 
-// NewLED returns a LED interface which allows control over the LED
+// NewLED returns a LED interface which allows control over the LED.
-// represented by key.
 func NewLED(key interface{}) (LED, error) {
 	return ledDriverInstance.LED(key)
 }
 
-// LEDOn switches the corresponding LED on.
+// LEDOn switches the LED on.
 func LEDOn(key interface{}) error {
 	led, err := NewLED(key)
 	if err != nil {
@@ -59,7 +63,7 @@ func LEDOn(key interface{}) error {
 	return led.On()
 }
 
-// LEDOff switches the corresponding LED off.
+// LEDOff switches the LED off.
 func LEDOff(key interface{}) error {
 	led, err := NewLED(key)
 	if err != nil {
@@ -69,7 +73,7 @@ func LEDOff(key interface{}) error {
 	return led.Off()
 }
 
-// LEDToggle toggles the corresponding LED.
+// LEDToggle toggles the LED.
 func LEDToggle(key interface{}) error {
 	led, err := NewLED(key)
 	if err != nil {

leddriver.go

@@ -1,3 +1,5 @@
+// Generic LED driver.
+
 package embd
 
 import (
@@ -9,6 +11,7 @@ import (
 	"strings"
 )
 
+// LEDMap type represents a LED mapping for a host.
 type LEDMap map[string][]string
 
 type ledDriver struct {

pin.go

@@ -1,3 +1,5 @@
+// Pin mapping support.
+
 package embd
 
 import (
@@ -6,16 +8,32 @@ import (
 )
 
 const (
+	// CapNormal represents the digital IO capability.
 	CapNormal int = 1 << iota
+
+	// CapI2C represents pins with the I2C capability.
 	CapI2C
+
+	// CapUART represents pins with the UART capability.
 	CapUART
+
+	// CapSPI represents pins with the SPI capability.
 	CapSPI
+
+	// CapGPMS represents pins with the GPMC capability.
 	CapGPMC
+
+	// CapLCD represents pins used to carry LCD data.
 	CapLCD
+
+	// CapPWM represents pins with PWM capability.
 	CapPWM
+
+	// CapAnalog represents pins with analog IO capability.
 	CapAnalog
 )
 
+// PinDesc represents a pin descriptor.
 type PinDesc struct {
 	ID      string
 	Aliases []string
@@ -25,8 +43,18 @@ type PinDesc struct {
 	AnalogLogical  int
 }
 
+// PinMap type represents a collection of pin descriptors.
 type PinMap []*PinDesc
 
+// Lookup returns a pin descriptor matching the provided key and capability
+// combination. This allows the same keys to be used across pins with differing
+// capabilities. For example, it is perfectly fine to have:
+//
+//	pin1: {Aliases: [10, GPIO10], Cap: CapNormal}
+//	pin2: {Aliases: [10, AIN0], Cap: CapAnalog}
+//
+// Searching for 10 with CapNormal will return pin1 and searching for
+// 10 with CapAnalog will return pin2. This makes for a very pleasant to use API.
 func (m PinMap) Lookup(k interface{}, cap int) (*PinDesc, bool) {
 	var ks string
 	switch key := k.(type) {