From 0002d02c28ff0c52bcfd4e2e7cb4a02266bd3560 Mon Sep 17 00:00:00 2001 From: Karan Misra Date: Sun, 23 Mar 2014 14:09:31 +0530 Subject: [PATCH] add documentation --- digitalpin.go | 4 ++++ gpio.go | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++ gpiodriver.go | 2 ++ i2c.go | 4 ++-- i2cdriver.go | 2 ++ led.go | 16 ++++++++----- leddriver.go | 3 +++ pin.go | 28 ++++++++++++++++++++++ 8 files changed, 117 insertions(+), 8 deletions(-) diff --git a/digitalpin.go b/digitalpin.go index 6f5bec8..8fffe07 100644 --- a/digitalpin.go +++ b/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 ( diff --git a/gpio.go b/gpio.go index 44b535e..7281bd3 100644 --- a/gpio.go +++ b/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 { diff --git a/gpiodriver.go b/gpiodriver.go index 4121a2b..e8b45ce 100644 --- a/gpiodriver.go +++ b/gpiodriver.go @@ -1,3 +1,5 @@ +// Generic GPIO driver. + package embd import ( diff --git a/i2c.go b/i2c.go index 152cf96..d3d5ae1 100644 --- a/i2c.go +++ b/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) } diff --git a/i2cdriver.go b/i2cdriver.go index 2995bbe..2a23a46 100644 --- a/i2cdriver.go +++ b/i2cdriver.go @@ -1,3 +1,5 @@ +// Generic I2C driver. + package embd import ( diff --git a/led.go b/led.go index bb222f6..b18423e 100644 --- a/led.go +++ b/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 -// represented by key. +// NewLED returns a LED interface which allows control over the LED. 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 { diff --git a/leddriver.go b/leddriver.go index 513901d..db7d5cb 100644 --- a/leddriver.go +++ b/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 { diff --git a/pin.go b/pin.go index bc135d9..af4d62e 100644 --- a/pin.go +++ b/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) {