documentation changes

README.md

@@ -1,19 +1,99 @@
-# embd [![Build Status](https://travis-ci.org/kidoman/embd.png?branch=master)](https://travis-ci.org/kidoman/embd)
+# embd [![Build Status](https://travis-ci.org/kidoman/embd.png?branch=master)](https://travis-ci.org/kidoman/embd) [![GoDoc](http://godoc.org/github.com/kidoman/embd?status.png)](http://godoc.org/github.com/kidoman/embd)
 
-Golang Embedded Programming Framework
+Supercharged Embedded Programming Framework
 
-## Documentation
+## Platforms supported
-
-[![GoDoc](http://godoc.org/github.com/kidoman/embd?status.png)](http://godoc.org/github.com/kidoman/embd)
-
-## Hosts supported
 
 * [RaspberryPi](http://www.raspberrypi.org/)
 * [BeagleBone Black](http://beagleboard.org/Products/BeagleBone%20Black)
+* [Intel Galileo](http://www.intel.com/content/www/us/en/do-it-yourself/galileo-maker-quark-board.html) **coming soon**
+* [Radxa](http://radxa.com/) **coming soon**
+* [Cubietruck](http://www.cubietruck.com/) **coming soon**
+* Bring Your Own **coming soon**
+
+## How to use
+
+Package embd provides a supercharged hardware abstraction layer for doing embedded programming
+on supported platforms like the Raspberry Pi and BeagleBone Black. Most of the examples below
+will work without change (i.e. the same binary) on all supported platforms. How cool is that?
+
+Although samples are all present in the [samples](https://github.com/kidoman/embd/tree/master/samples) folder,
+we will show a few choice examples here.
+
+Use the LED driver to toggle LEDs on the BBB:
+
+	import "github.com/kidoman/embd"
+	...
+	embd.InitLED()
+	defer embd.CloseLED()
+	...
+	led, err := embd.NewLED("USR3")
+	...
+	led.Toggle()
+
+Even shorter while prototyping:
+
+	import "github.com/kidoman/embd"
+	...
+	embd.InitLED()
+	defer embd.CloseLED()
+	...
+	embd.ToggleLED(3)
+
+Control GPIO pins on the RaspberryPi / BeagleBone Black:
+
+	import "github.com/kidoman/embd"
+	...
+	embd.InitGPIO()
+	defer embd.CloseGPIO()
+	...
+	embd.SetDirection(10, embd.Out)
+	embd.DigitalWrite(10, embd.High)
+
+Could also do:
+
+	import "github.com/kidoman/embd"
+	...
+	embd.InitGPIO()
+	defer embd.CloseGPIO()
+	...
+	pin, err := embd.NewDigitalPin(10)
+	...
+	pin.SetDirection(embd.Out)
+	pin.Write(embd.High)
+
+Or read data from the Bosch BMP085 barometric sensor:
+
+	import "github.com/kidoman/embd"
+	import "github.com/kidoman/embd/sensor/bmp085"
+	...
+	bus := embd.NewI2CBus(1)
+	...
+	baro := bmp085.New(bus)
+	...
+	temp, err := baro.Temperature()
+	altitude, err := baro.Altitude()
+
+Even find out the heading from the LSM303 magnetometer:
+
+	import "github.com/kidoman/embd"
+	import "github.com/kidoman/embd/sensor/lsm303"
+	...
+	bus := embd.NewI2CBus(1)
+	...
+	mag := lsm303.New(bus)
+	...
+	heading, err := mag.Heading()
+
+The above two examples depend on I2C and therefore will work without change on almost all
+platforms.
 
 ## Protocols supported
 
-* **I2C** [Documentation](http://godoc.org/github.com/kidoman/embd/i2c)
+* **Digital GPIO** [Documentation](http://godoc.org/github.com/kidoman/embd#DigitalPin)
+* **Analog GPIO** [Documentation](http://godoc.org/github.com/kidoman/embd#AnalogPin)
+* **I2C** [Documentation](http://godoc.org/github.com/kidoman/embd#I2CBus)
+* **LED** [Documentation](http://godoc.org/github.com/kidoman/embd#LED)
 
 ## Sensors supported
 

controller/pca9685/pca9685.go

@@ -6,6 +6,7 @@ import (
 	"math"
 	"sync"
 	"time"
+
 	"github.com/kidoman/embd"
 	"github.com/kidoman/embd/util"
 )
@@ -155,11 +156,14 @@ func (d *PCA9685) SetPwm(channel, onTime, offTime int) (err error) {
 	return
 }
 
+// SetMicroseconds is a convinience method which allows easy servo control.
 func (d *PCA9685) SetMicroseconds(channel, us int) (err error) {
 	offTime := us * d.Freq * pwmControlPoints / 1000000
 	return d.SetPwm(channel, 0, offTime)
 }
 
+// SetAnalog is a convinience method which allows easy manipulation of the PWM
+// based on a (0-255) range value.
 func (d *PCA9685) SetAnalog(channel int, value byte) (err error) {
 	offTime := util.Map(int64(value), minAnalogValue, maxAnalogValue, 0, pwmControlPoints-1)
 	return d.SetPwm(channel, 0, int(offTime))

doc.go

@@ -1,29 +1,74 @@
 /*
-Package rpi provides modules which will help gophers deal with various sensors.
+	Package embd provides a supercharged hardware abstraction layer for doing embedded programming
+	on supported platforms like the Raspberry Pi and BeagleBone Black. Most of the examples below
+	will work without change (i.e. the same binary) on all supported platforms. How cool is that?
 
-Use the default i2c bus to read/write data:
+	Use the LED driver to toggle LEDs on the BBB:
 
-	import "github.com/kidoman/embd/i2c"
+		import "github.com/kidoman/embd"
 		...
-	value, err := i2c.ReadInt(0x1E, 0x03)
+		embd.InitLED()
+		defer embd.CloseLED()
 		...
-	value := make([]byte, 6)
+		led, err := embd.NewLED("USR3")
-	err := i2c.ReadFromReg(0x77, 0xF6, value)
 		...
-	err := i2c.WriteToReg(0x1E, 0x02, 0x00)
+		led.Toggle()
 
-Read data from the BMP085 sensor:
+	Even shorter while prototyping:
 
+		import "github.com/kidoman/embd"
+		...
+		embd.InitLED()
+		defer embd.CloseLED()
+		...
+		embd.ToggleLED(3)
+
+	Control GPIO pins on the RaspberryPi / BeagleBone Black:
+
+		import "github.com/kidoman/embd"
+		...
+		embd.InitGPIO()
+		defer embd.CloseGPIO()
+		...
+		embd.SetDirection(10, embd.Out)
+		embd.DigitalWrite(10, embd.High)
+
+	Could also do:
+
+		import "github.com/kidoman/embd"
+		...
+		embd.InitGPIO()
+		defer embd.CloseGPIO()
+		...
+		pin, err := embd.NewDigitalPin(10)
+		...
+		pin.SetDirection(embd.Out)
+		pin.Write(embd.High)
+
+	Or read data from the Bosch BMP085 barometric sensor:
+
+		import "github.com/kidoman/embd"
 		import "github.com/kidoman/embd/sensor/bmp085"
 		...
-	temp, err := bmp085.Temperature()
+		bus := embd.NewI2CBus(1)
 		...
-	altitude, err := bmp085.Altitude()
+		baro := bmp085.New(bus)
+		...
+		temp, err := baro.Temperature()
+		altitude, err := baro.Altitude()
 
-Find out the heading from the LSM303 magnetometer:
+	Even find out the heading from the LSM303 magnetometer:
 
+		import "github.com/kidoman/embd"
 		import "github.com/kidoman/embd/sensor/lsm303"
 		...
-	heading, err := lsm303.Heading()
+		bus := embd.NewI2CBus(1)
+		...
+		mag := lsm303.New(bus)
+		...
+		heading, err := mag.Heading()
+
+	The above two examples depend on I2C and therefore will work without change on almost all
+	platforms.
 */
 package embd

samples/led.go

@@ -1,5 +1,7 @@
 // +build ignore
 
+// LED example, works OOTB on a BBB.
+
 package main
 
 import (

samples/ledshort.go

@@ -1,5 +1,7 @@
 // +build ignore
 
+// Short LED example, works OOTB on a BBB.
+
 package main
 
 import (

sensor/bh1750fvi/bh1750fvi.go

@@ -1,4 +1,4 @@
-// Package BH1750FVI allows interfacing with the BH1750FVI ambient light sensor through I2C protocol.
+// Package BH1750FVI allows interfacing with the BH1750FVI ambient light sensor through I2C.
 package bh1750fvi
 
 import (
@@ -25,6 +25,7 @@ const (
 	pollDelay = 150
 )
 
+// BH1750FVI represents a BH1750FVI ambient light sensor.
 type BH1750FVI struct {
 	Bus  embd.I2CBus
 	Poll int
@@ -38,6 +39,7 @@ type BH1750FVI struct {
 	operationCode byte
 }
 
+// New returns a BH1750FVI sensor at the specific resolution mode.
 func New(mode string, bus embd.I2CBus) *BH1750FVI {
 	switch mode {
 	case High:
@@ -49,12 +51,12 @@ func New(mode string, bus embd.I2CBus) *BH1750FVI {
 	}
 }
 
-// NewHighMode returns a BH1750FVI inteface on high resolution mode (1lx resolution)
+// NewHighMode returns a BH1750FVI sensor on high resolution mode (1lx resolution)
 func NewHighMode(bus embd.I2CBus) *BH1750FVI {
 	return New(High, bus)
 }
 
-// NewHighMode returns a BH1750FVI inteface on high resolution mode2 (0.5lx resolution)
+// NewHighMode returns a BH1750FVI sensor on high resolution mode2 (0.5lx resolution)
 func NewHigh2Mode(bus embd.I2CBus) *BH1750FVI {
 	return New(High2, bus)
 }

sensor/bmp085/bmp085.go

@@ -38,6 +38,7 @@ const (
 	pollDelay = 250
 )
 
+// BMP085 represents a Bosch BMP085 barometric sensor.
 type BMP085 struct {
 	Bus  embd.I2CBus
 	Poll int
@@ -59,6 +60,7 @@ type BMP085 struct {
 	quit      chan struct{}
 }
 
+// New returns a handle to a BMP085 sensor.
 func New(bus embd.I2CBus) *BMP085 {
 	return &BMP085{Bus: bus, Poll: pollDelay}
 }

sensor/bmp180/bmp180.go

@@ -38,6 +38,7 @@ const (
 	pollDelay = 250
 )
 
+// BMP180 represents a Bosch BMP180 barometric sensor.
 type BMP180 struct {
 	Bus  embd.I2CBus
 	Poll int
@@ -59,6 +60,7 @@ type BMP180 struct {
 	quit      chan struct{}
 }
 
+// New returns a handle to a BMP180 sensor.
 func New(bus embd.I2CBus) *BMP180 {
 	return &BMP180{Bus: bus, Poll: pollDelay}
 }

sensor/doc.go

@@ -1,2 +1,2 @@
-// Package sensor contains the various sensors modules for use on your Raspberry Pi.
+// Package sensor contains the various sensors modules for use on your platform.
 package sensor

sensor/l3gd20/l3gd20.go

@@ -316,6 +316,7 @@ func (d *L3GD20) Temperature() (temp int, err error) {
 	return
 }
 
+// Orientations returns a channel which will have the current temperature reading.
 func (d *L3GD20) Orientations() (orientations <-chan Orientation, err error) {
 	if err = d.setup(); err != nil {
 		return
@@ -366,6 +367,7 @@ func (d *L3GD20) Start() (err error) {
 	return
 }
 
+// Stop the data acquisition loop.
 func (d *L3GD20) Stop() (err error) {
 	if d.closing != nil {
 		waitc := make(chan struct{})

sensor/lsm303/lsm303.go

@@ -42,6 +42,7 @@ const (
 	pollDelay = 250
 )
 
+// LSM303 represents a LSM303 magnetometer.
 type LSM303 struct {
 	Bus  embd.I2CBus
 	Poll int

sensor/tmp006/tmp006.go

@@ -8,6 +8,7 @@ import (
 	"math"
 	"sync"
 	"time"
+
 	"github.com/kidoman/embd"
 )
 

sensor/watersensor/watersensor.go

@@ -1,4 +1,4 @@
-// Package watersensor allows interfacing with the water sensor
+// Package watersensor allows interfacing with the water sensor.
 package watersensor
 
 import (
@@ -8,6 +8,7 @@ import (
 	"github.com/kidoman/embd"
 )
 
+// WaterSensor represents a water sensor.
 type WaterSensor struct {
 	Pin embd.DigitalPin