Merge branch 'master' into dev

Conflicts:
	gobot.go
	platforms/opencv/camera_driver.go
	robot.go
	version.go

CHANGELOG.md

@@ -1,3 +1,8 @@
+0.7.1
+---
+  - opencv
+    - Fix pthread_create issue on Mac OS
+
 0.7
 ---
   - Dramatically increased test coverage and documentation

README.md

@@ -98,9 +98,12 @@ Gobot has a extensible system for connecting to hardware devices. The following
   - [Intel Edison](http://www.intel.com/content/www/us/en/do-it-yourself/edison.html) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/intel-iot/edison)
   - [Joystick](http://en.wikipedia.org/wiki/Joystick) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/joystick)
   - [Leap Motion](https://www.leapmotion.com/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/leapmotion)
+  - [MavLink](http://qgroundcontrol.org/mavlink/start) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/mavlinky)
+  - [MQTT](http://mqtt.org/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/mqtt)
   - [Neurosky](http://neurosky.com/products-markets/eeg-biosensors/hardware/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/neurosky)
   - [OpenCV](http://opencv.org/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/opencv)
   - [Pebble](https://www.getpebble.com/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/pebble)
+  - [Raspberry Pi](http://www.raspberrypi.org/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/raspi)
   - [Spark](https://www.spark.io/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/spark)
   - [Sphero](http://www.gosphero.com/) <=> [Library](https://github.com/hybridgroup/gobot/tree/master/platforms/sphero)
 
@@ -125,13 +128,15 @@ drivers provided using the gobot-i2c module:
   - [I2C](https://en.wikipedia.org/wiki/I%C2%B2C) <=> [Drivers](https://github.com/hybridgroup/gobot/tree/master/platforms/i2c)
     - BlinkM
     - HMC6352
+    - MPL1150A2
+    - MPU6050
     - Wii Nunchuck Controller
 
 More platforms and drivers are coming soon...
 
 ## Getting Started
 
-Install Gobot with: `go get -u github.com/hybridgroup/gobot`
+Install Gobot with: `go get -d -u github.com/hybridgroup/gobot/...`
 
 ## API:
 

adaptor.go

@@ -23,7 +23,11 @@ type AdaptorInterface interface {
 	ToJSON() *JSONConnection
 }
 
-// NewAdaptor returns a new Gobot Adaptor
+// NewAdaptor returns a new Adaptor given a name, adaptorType and optionally accepts:
+//
+//	string: Port the adaptor connects to
+//
+// adaptorType is a label used for identification in the api
 func NewAdaptor(name string, adaptorType string, v ...interface{}) *Adaptor {
 	if name == "" {
 		name = fmt.Sprintf("%X", Rand(int(^uint(0)>>1)))
@@ -70,7 +74,7 @@ func (a *Adaptor) Type() string {
 	return a.adaptorType
 }
 
-// Connected returns true if adaptor is connected
+// Connected returns true if the adaptor is connected
 func (a *Adaptor) Connected() bool {
 	return a.connected
 }
@@ -80,7 +84,7 @@ func (a *Adaptor) SetConnected(b bool) {
 	a.connected = b
 }
 
-// ToJSON returns a json representation of adaptor
+// ToJSON returns a json representation of an adaptor
 func (a *Adaptor) ToJSON() *JSONConnection {
 	return &JSONConnection{
 		Name:    a.Name(),

doc.go

@@ -2,14 +2,9 @@
 
 /*
 Package gobot provides a framework for robotics, physical computing and the internet of things.
-It is the main point of entry in your Gobot application. A Gobot
+It is the main point of entry for your Gobot application. A Gobot program
 is typically composed of one or more robots that makes up a project.
 
-Commands are a way to expose your robots functionality with the external world.
-A Gobot can be configured to expose a restful HTTP interface using the api
-package. You can define custom commands on your Gobot and interact with your
-application as a web service.
-
 Basic Setup
 
     package main
@@ -35,71 +30,76 @@ Basic Setup
       gbot.Start()
     }
 
-Web Enabled? You bet!
+Blinking an LED (Hello Eve!)
 
     package main
 
     import (
-    	"fmt"
+    	"time"
 
     	"github.com/hybridgroup/gobot"
-    	"github.com/hybridgroup/gobot/api"
+    	"github.com/hybridgroup/gobot/platforms/firmata"
+    	"github.com/hybridgroup/gobot/platforms/gpio"
     )
 
     func main() {
     	gbot := gobot.NewGobot()
 
-      // Starts the API server on default port 3000
-    	api.NewAPI(gbot).Start()
+    	firmataAdaptor := firmata.NewFirmataAdaptor("arduino", "/dev/ttyACM0")
+    	led := gpio.NewLedDriver(firmataAdaptor, "led", "13")
 
-      // Accessible via http://localhost:3000/api/commands/say_hello
-    	gbot.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
-    		return "Master says hello!"
-    	})
+    	work := func() {
+    		gobot.Every(1*time.Second, func() {
+    			led.Toggle()
+    		})
+    	}
 
-    	hello := gbot.AddRobot(gobot.NewRobot("Eve"))
+    	robot := gobot.NewRobot("Eve",
+    		[]gobot.Connection{firmataAdaptor},
+    		[]gobot.Device{led},
+    		work,
+    	)
 
-      // Accessible via http://localhost:3000/robots/Eve/commands/say_hello
-    	hello.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
-    		return fmt.Sprintf("%v says hello!", hello.Name)
-    	})
+    	gbot.AddRobot(robot)
 
     	gbot.Start()
     }
 
-Blinking teh LED (Hello Eve!)
+Web Enabled? You bet! Gobot can be configured to expose a restful HTTP interface
+using the api package. You can define custom commands on your robots, in addition
+to the built-in device driver commands, and interact with your application as a
+web service.
+
 
     package main
 
     import (
-    	"time"
+    	"fmt"
 
     	"github.com/hybridgroup/gobot"
-    	"github.com/hybridgroup/gobot/platforms/firmata"
-    	"github.com/hybridgroup/gobot/platforms/gpio"
+    	"github.com/hybridgroup/gobot/api"
     )
 
     func main() {
     	gbot := gobot.NewGobot()
 
-    	firmataAdaptor := firmata.NewFirmataAdaptor("arduino", "/dev/ttyACM0")
-    	led := gpio.NewLedDriver(firmataAdaptor, "led", "13")
+      // Starts the API server on default port 3000
+    	api.NewAPI(gbot).Start()
 
-    	work := func() {
-    		gobot.Every(1*time.Second, func() {
-    			led.Toggle()
-    		})
-    	}
+      // Accessible via http://localhost:3000/api/commands/say_hello
+    	gbot.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
+    		return "Master says hello!"
+    	})
 
-    	robot := gobot.NewRobot("Eve",
-    		[]gobot.Connection{firmataAdaptor},
-    		[]gobot.Device{led},
-    		work,
-    	)
+    	hello := gbot.AddRobot(gobot.NewRobot("Eve"))
 
-    	gbot.AddRobot(robot)
+      // Accessible via http://localhost:3000/robots/Eve/commands/say_hello
+    	hello.AddCommand("say_hello", func(params map[string]interface{}) interface{} {
+    		return fmt.Sprintf("%v says hello!", hello.Name)
+    	})
 
     	gbot.Start()
     }
+
 */
 package gobot

driver.go

@@ -36,8 +36,13 @@ type Driver struct {
 	driverType string
 }
 
-// NewDriver returns a Driver with specified parameters
-// and sets driver pin, adaptor and interval
+// NewDriver returns a new Driver given a name, driverType and optionally accepts:
+//
+//	string: Pin the driver connects to
+//	AdaptorInterface: Adaptor the driver connects to
+//	time.Duration: Interval used internally for polling where applicable
+//
+// driverType is a label used for identification in the api
 func NewDriver(name string, driverType string, v ...interface{}) *Driver {
 	if name == "" {
 		name = fmt.Sprintf("%X", Rand(int(^uint(0)>>1)))

event.go

@@ -10,8 +10,7 @@ type Event struct {
 	Callbacks []callback
 }
 
-// NewEvent generates a new event by making a channel
-// and start reading from it
+// NewEvent returns a new event which is then ready for publishing and subscribing.
 func NewEvent() *Event {
 	e := &Event{
 		Chan:      make(chan interface{}, 1),
@@ -25,16 +24,15 @@ func NewEvent() *Event {
 	return e
 }
 
-// Writes sends event data to channel
+// Write writes data to the Event
 func (e *Event) Write(data interface{}) {
 	select {
 	case e.Chan <- data:
 	default:
 	}
 }
 
-// Read waits data from channel and execute callbacks
-// for each event when received
+// Read publishes to all subscribers of e if there is any new data
 func (e *Event) Read() {
 	for s := range e.Chan {
 		tmp := []callback{}

examples_test.go

@@ -0,0 +1,75 @@
+package gobot_test
+
+import (
+	"fmt"
+	"github.com/hybridgroup/gobot"
+	"testing"
+	"time"
+)
+
+func ExampleEvery() {
+	gobot.Every(1*time.Second, func() {
+		fmt.Println("Hello")
+	})
+}
+
+func ExampleAfter() {
+	gobot.After(1*time.Second, func() {
+		fmt.Println("Hello")
+	})
+}
+
+func ExamplePublish() {
+	e := gobot.NewEvent()
+	gobot.Publish(e, 100)
+}
+
+func ExampleOn() {
+	e := gobot.NewEvent()
+	gobot.On(e, func(s interface{}) {
+		fmt.Println(s)
+	})
+	gobot.Publish(e, 100)
+	gobot.Publish(e, 200)
+}
+
+func ExampleOnce() {
+	e := gobot.NewEvent()
+	gobot.Once(e, func(s interface{}) {
+		fmt.Println(s)
+		fmt.Println("I will no longer respond to events")
+	})
+	gobot.Publish(e, 100)
+	gobot.Publish(e, 200)
+}
+
+func ExampleRand() {
+	i := gobot.Rand(100)
+	fmt.Sprintln("%v is > 0 && < 100", i)
+}
+
+func ExampleFromScale() {
+	fmt.Println(gobot.FromScale(5, 0, 10))
+	// Output:
+	// 0.5
+}
+
+func ExampleToScale() {
+	fmt.Println(gobot.ToScale(500, 0, 10))
+	// Output:
+	// 10
+}
+
+func ExampleAssert() {
+	t := &testing.T{}
+	var a int = 100
+	var b int = 100
+	gobot.Assert(t, a, b)
+}
+
+func ExampleRefute() {
+	t := &testing.T{}
+	var a int = 100
+	var b int = 200
+	gobot.Refute(t, a, b)
+}

gobot.go

@@ -19,7 +19,7 @@ type Gobot struct {
 	trap     func(chan os.Signal)
 }
 
-// NewGobot instantiates a new Gobot
+// NewGobot returns a new Gobot
 func NewGobot() *Gobot {
 	return &Gobot{
 		robots:   &robots{},
@@ -45,17 +45,19 @@ func (g *Gobot) AddCommand(name string, f func(map[string]interface{}) interface
 	g.commands[name] = f
 }
 
-// Commands lists all available commands on this Gobot instance.
+// Commands returns all available commands on this Gobot.
 func (g *Gobot) Commands() map[string]func(map[string]interface{}) interface{} {
 	return g.commands
 }
 
-// Command fetch the associated command using the given command name
+// Command reutnrs a command given a name.
 func (g *Gobot) Command(name string) func(map[string]interface{}) interface{} {
 	return g.commands[name]
 }
 
-// Start runs the main Gobot event loop
+// Start calls the Start method on each robot in it's collection of robots, and
+// stops all robots on reception of a SIGINT. Start will block the execution of
+// your main function until it receives the SIGINT.
 func (g *Gobot) Start() (errs []error) {
 	if rerrs := g.robots.Start(); len(rerrs) > 0 {
 		for _, err := range rerrs {
@@ -92,18 +94,19 @@ func (g *Gobot) Start() (errs []error) {
 	return errs
 }
 
-// Robots fetch all robots associated with this Gobot instance.
+// Robots returns all robots associated with this Gobot instance.
 func (g *Gobot) Robots() *robots {
 	return g.robots
 }
 
-// AddRobot adds a new robot to our Gobot instance.
+// AddRobot adds a new robot to the internal collection of robots. Returns the
+// added robot
 func (g *Gobot) AddRobot(r *Robot) *Robot {
 	*g.robots = append(*g.robots, r)
 	return r
 }
 
-// Robot find a robot with a given name.
+// Robot returns a robot given name. Returns nil on no robot.
 func (g *Gobot) Robot(name string) *Robot {
 	for _, robot := range *g.Robots() {
 		if robot.Name == name {
@@ -113,7 +116,7 @@ func (g *Gobot) Robot(name string) *Robot {
 	return nil
 }
 
-// ToJSON retrieves a JSON representation of this Gobot.
+// ToJSON returns a JSON representation of this Gobot.
 func (g *Gobot) ToJSON() *JSONGobot {
 	jsonGobot := &JSONGobot{
 		Robots:   []*JSONRobot{},

platforms/beaglebone/README.md

@@ -6,7 +6,7 @@ This package provides the Gobot adaptor for the [Beaglebone Black](http://beagle
 
 ## Installing
 ```
-go get github.com/hybridgroup/gobot && go install github.com/hybridgroup/platforms/gobot/beaglebone
+go get -d -u github.com/hybridgroup/gobot/... && go install github.com/hybridgroup/gobot/platforms/beaglebone
 ```
 
 ## Cross compiling for the Beaglebone Black