documentation update

doc.go

@@ -1,2 +1,23 @@
-// Package rpi provides modules which will help gophers deal with various sensors.
+/*
+Package rpi provides modules which will help gophers deal with various sensors.
+
+Use the default i2c bus to read/write data:
+
+	value, err := i2c.ReadInt(0x1E, 0x03)
+	...
+	value := make([]byte, 6)
+	err := i2c.ReadFromReg(0x77, 0xF6, value)
+	...
+	err := i2c.WriteToReg(0x1E, 0x02, 0x00)
+
+Read data from the BMP085 sensor:
+
+	temp, err := bmp085.Temperature()
+	...
+	altitude, err := bmp085.Altitude()
+
+Find out the heading from the LSM303 magnetometer:
+
+	heading, err := lsm303.Heading()
+*/
 package rpi

sensor/bmp085/bmp085.go

@@ -38,14 +38,21 @@ const (
 	pollDelay = 250
 )
 
+// A BMP085 implements access to the Bosch BMP085 sensor.
 type BMP085 interface {
+	// SetPollDelay sets the delay between runs of the data acquisition loop.
 	SetPollDelay(delay int)
 
+	// Temperature returns the current temperature reading.
 	Temperature() (temp float64, err error)
+	// Pressure returns the current pressure reading.
 	Pressure() (pressure int, err error)
+	// Altitude returns the current altitude reading.
 	Altitude() (altitude float64, err error)
 
+	// Run starts the sensor data acquisition loop.
 	Run() error
+	// Close.
 	Close()
 }
 
@@ -69,6 +76,7 @@ type bmp085 struct {
 	debug bool
 }
 
+// Default instance of the BMP085 sensor.
 var Default = New(i2c.Default)
 
 // New creates a new BMP085 interface. The bus variable controls
@@ -220,7 +228,7 @@ func (d *bmp085) measureTemp() (temp uint16, err error) {
 	return
 }
 
-// Return temperature reading.
+// Temperature returns the current temperature reading.
 func (d *bmp085) Temperature() (temp float64, err error) {
 
 	select {
@@ -340,7 +348,7 @@ func (d *bmp085) measurePressureAndAltitude() (pressure int32, altitude float64,
 	return
 }
 
-// Return pressure reading.
+// Pressure returns the current pressure reading.
 func (d *bmp085) Pressure() (pressure int, err error) {
 	if err = d.calibrate(); err != nil {
 		return
@@ -364,7 +372,7 @@ func (d *bmp085) Pressure() (pressure int, err error) {
 	}
 }
 
-// Return altitude reading.
+// Altitude returns the current altitude reading.
 func (d *bmp085) Altitude() (altitude float64, err error) {
 	if err = d.calibrate(); err != nil {
 		return
@@ -385,7 +393,7 @@ func (d *bmp085) Altitude() (altitude float64, err error) {
 	}
 }
 
-// Start the sensor data acquisition loop.
+// Run starts the sensor data acquisition loop.
 func (d *bmp085) Run() (err error) {
 	go func() {
 		d.quit = make(chan struct{})
@@ -436,22 +444,27 @@ func (d *bmp085) Close() {
 	}
 }
 
-// Return temperature reading.
+// SetPollDelay sets the delay between runs of the data acquisition loop.
+func SetPollDelay(delay int) {
+	Default.SetPollDelay(delay)
+}
+
+// Temperature returns the current temperature reading.
 func Temperature() (temp float64, err error) {
 	return Default.Temperature()
 }
 
-// Return pressure reading.
+// Pressure returns the current pressure reading.
 func Pressure() (pressure int, err error) {
 	return Default.Pressure()
 }
 
-// Return altitude reading.
+// Altitude returns the current altitude reading.
 func Altitude() (altitude float64, err error) {
 	return Default.Altitude()
 }
 
-// Start the sensor data acquisition loop.
+// Run starts the sensor data acquisition loop.
 func Run() (err error) {
 	return Default.Run()
 }

sensor/lsm303/lsm303.go

@@ -15,25 +15,25 @@ const (
 
 	magConfigRegA = 0x00
 
-	MagHz75         = 0x00
-	Mag1Hz5         = 0x04
-	Mag3Hz          = 0x08
-	Mag7Hz5         = 0x0C
-	Mag15Hz         = 0x10
-	Mag30Hz         = 0x14
-	Mag75Hz         = 0x18
-	MagNormal       = 0x00
-	MagPositiveBias = 0x01
-	MagNegativeBias = 0x02
+	MagHz75         = 0x00 // ODR = 0.75 Hz
+	Mag1Hz5         = 0x04 // ODR = 1.5 Hz
+	Mag3Hz          = 0x08 // ODR = 3 Hz
+	Mag7Hz5         = 0x0C // ODR = 7.5 Hz
+	Mag15Hz         = 0x10 // ODR = 15 Hz
+	Mag30Hz         = 0x14 // ODR = 30 Hz
+	Mag75Hz         = 0x18 // ODR = 75 Hz
+	MagNormal       = 0x00 // Normal mode
+	MagPositiveBias = 0x01 // Positive bias mode
+	MagNegativeBias = 0x02 // Negative bias mode
 
-	MagCRADefault = Mag15Hz | MagNormal
+	MagCRADefault = Mag15Hz | MagNormal // 15 Hz and normal mode is the default
 
 	magModeReg = 0x02
 
-	MagContinuous = 0x00
-	MagSleep      = 0x03
+	MagContinuous = 0x00 // Continuous conversion mode
+	MagSleep      = 0x03 // Sleep mode
 
-	MagMRDefault = MagContinuous
+	MagMRDefault = MagContinuous // Continuous conversion is the default
 
 	magDataSignal = 0x02
 	magData       = 0x03
@@ -41,12 +41,17 @@ const (
 	pollDelay = 250
 )
 
+// A LSM303 implements access to a LSM303 sensor.
 type LSM303 interface {
+	// SetPollDelay sets the delay between runs of the data acquisition loop.
 	SetPollDelay(delay int)
 
+	// Heading returns the current heading [0, 360).
 	Heading() (heading float64, err error)
 
+	// Run starts the sensor data acquisition loop.
 	Run() error
+	// Close closes the sensor data acquisition loop and put the LSM303 into sleep mode.
 	Close() error
 }
 
@@ -64,6 +69,7 @@ type lsm303 struct {
 	debug bool
 }
 
+// Default instance of the LSM303 sensor.
 var Default = New(i2c.Default)
 
 // New creates a new LSM303 interface. The bus variable controls
@@ -126,7 +132,7 @@ func (d *lsm303) measureHeading() (heading float64, err error) {
 	return
 }
 
-// Return heading [0, 360).
+// Heading returns the current heading [0, 360).
 func (d *lsm303) Heading() (heading float64, err error) {
 	select {
 	case heading = <-d.headings:
@@ -139,7 +145,7 @@ func (d *lsm303) Heading() (heading float64, err error) {
 	}
 }
 
-// Start the sensor data acquisition loop.
+// Run starts the sensor data acquisition loop.
 func (d *lsm303) Run() (err error) {
 	go func() {
 		d.quit = make(chan struct{})
@@ -179,17 +185,22 @@ func (d *lsm303) Close() (err error) {
 	return
 }
 
-// Return heading [0, 360).
+// SetPollDelay sets the delay between runs of the data acquisition loop.
+func SetPollDelay(delay int) {
+	Default.SetPollDelay(delay)
+}
+
+// Heading returns the current heading [0, 360).
 func Heading() (heading float64, err error) {
 	return Default.Heading()
 }
 
-// Start the sensor data acquisition loop.
+// Run starts the sensor data acquisition loop.
 func Run() (err error) {
 	return Default.Run()
 }
 
-// Close the sensor data acquisition loop and put the LSM303 into sleep mode.
+// Close closes the sensor data acquisition loop and put the LSM303 into sleep mode.
 func Close() (err error) {
 	return Default.Close()
 }