diff --git a/README.md b/README.md index 0ced5a8..7e5b5ed 100644 --- a/README.md +++ b/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 - -[![GoDoc](http://godoc.org/github.com/kidoman/embd?status.png)](http://godoc.org/github.com/kidoman/embd) - -## Hosts supported +## Platforms 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 diff --git a/controller/pca9685/pca9685.go b/controller/pca9685/pca9685.go index 751dbe0..0235472 100644 --- a/controller/pca9685/pca9685.go +++ b/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)) diff --git a/doc.go b/doc.go index f5a8daf..a0930c6 100644 --- a/doc.go +++ b/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" - ... - value, err := i2c.ReadInt(0x1E, 0x03) - ... - value := make([]byte, 6) - err := i2c.ReadFromReg(0x77, 0xF6, value) - ... - err := i2c.WriteToReg(0x1E, 0x02, 0x00) + import "github.com/kidoman/embd" + ... + embd.InitLED() + defer embd.CloseLED() + ... + led, err := embd.NewLED("USR3") + ... + led.Toggle() -Read data from the BMP085 sensor: + Even shorter while prototyping: - import "github.com/kidoman/embd/sensor/bmp085" - ... - temp, err := bmp085.Temperature() - ... - altitude, err := bmp085.Altitude() + import "github.com/kidoman/embd" + ... + embd.InitLED() + defer embd.CloseLED() + ... + embd.ToggleLED(3) -Find out the heading from the LSM303 magnetometer: + Control GPIO pins on the RaspberryPi / BeagleBone Black: - import "github.com/kidoman/embd/sensor/lsm303" - ... - heading, err := lsm303.Heading() + 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. */ package embd diff --git a/samples/led.go b/samples/led.go index 1c1d68f..f3358cc 100644 --- a/samples/led.go +++ b/samples/led.go @@ -1,5 +1,7 @@ // +build ignore +// LED example, works OOTB on a BBB. + package main import ( diff --git a/samples/ledshort.go b/samples/ledshort.go index eb1b0f2..e3ee618 100644 --- a/samples/ledshort.go +++ b/samples/ledshort.go @@ -1,5 +1,7 @@ // +build ignore +// Short LED example, works OOTB on a BBB. + package main import ( diff --git a/sensor/bh1750fvi/bh1750fvi.go b/sensor/bh1750fvi/bh1750fvi.go index ba17186..3d88159 100644 --- a/sensor/bh1750fvi/bh1750fvi.go +++ b/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) } diff --git a/sensor/bmp085/bmp085.go b/sensor/bmp085/bmp085.go index 5955f54..fc4d6d1 100644 --- a/sensor/bmp085/bmp085.go +++ b/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} } diff --git a/sensor/bmp180/bmp180.go b/sensor/bmp180/bmp180.go index ec1bbcd..5c805a5 100644 --- a/sensor/bmp180/bmp180.go +++ b/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} } diff --git a/sensor/doc.go b/sensor/doc.go index fa5d195..0bb3fd3 100644 --- a/sensor/doc.go +++ b/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 diff --git a/sensor/l3gd20/l3gd20.go b/sensor/l3gd20/l3gd20.go index 1ce4434..d3ceab9 100644 --- a/sensor/l3gd20/l3gd20.go +++ b/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{}) diff --git a/sensor/lsm303/lsm303.go b/sensor/lsm303/lsm303.go index f31788c..b4f5fce 100644 --- a/sensor/lsm303/lsm303.go +++ b/sensor/lsm303/lsm303.go @@ -42,6 +42,7 @@ const ( pollDelay = 250 ) +// LSM303 represents a LSM303 magnetometer. type LSM303 struct { Bus embd.I2CBus Poll int diff --git a/sensor/tmp006/tmp006.go b/sensor/tmp006/tmp006.go index 5e11839..d0137b4 100644 --- a/sensor/tmp006/tmp006.go +++ b/sensor/tmp006/tmp006.go @@ -8,6 +8,7 @@ import ( "math" "sync" "time" + "github.com/kidoman/embd" ) diff --git a/sensor/watersensor/watersensor.go b/sensor/watersensor/watersensor.go index 2b2109c..7c66fe8 100644 --- a/sensor/watersensor/watersensor.go +++ b/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