gobot

README

Gobot (http://gobot.io/) is a framework using the Go programming language (http://golang.org/) for robotics, physical computing, and the Internet of Things.

It provides a simple, yet powerful way to create solutions that incorporate multiple, different hardware devices at the same time.

Want to use Javascript robotics? Check out our sister project Cylon.js (http://cylonjs.com/)

Want to use Ruby on robots? Check out our sister project Artoo (http://artoo.io)

Getting Started

Get the Gobot source with: go get -d -u gobot.io/x/gobot/...

Examples

Gobot with Arduino

package main

import (
	"time"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/drivers/gpio"
	"gobot.io/x/gobot/platforms/firmata"
)

func main() {
	firmataAdaptor := firmata.NewAdaptor("/dev/ttyACM0")
	led := gpio.NewLedDriver(firmataAdaptor, "13")

	work := func() {
		gobot.Every(1*time.Second, func() {
			led.Toggle()
		})
	}

	robot := gobot.NewRobot("bot",
		[]gobot.Connection{firmataAdaptor},
		[]gobot.Device{led},
		work,
	)

	robot.Start()
}

Gobot with Sphero

package main

import (
	"fmt"
	"time"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/platforms/sphero"
)

func main() {
	adaptor := sphero.NewAdaptor("/dev/rfcomm0")
	driver := sphero.NewSpheroDriver(adaptor)

	work := func() {
		gobot.Every(3*time.Second, func() {
			driver.Roll(30, uint16(gobot.Rand(360)))
		})
	}

	robot := gobot.NewRobot("sphero",
		[]gobot.Connection{adaptor},
		[]gobot.Device{driver},
		work,
	)

	robot.Start()
}

"Metal" Gobot

You can use the entire Gobot framework as shown in the examples above ("Classic" Gobot), or you can pick and choose from the various Gobot packages to control hardware with nothing but pure idiomatic Golang code ("Metal" Gobot). For example:

package main

import (
	"gobot.io/x/gobot/drivers/gpio"
	"gobot.io/x/gobot/platforms/intel-iot/edison"
	"time"
)

func main() {
	e := edison.NewAdaptor()
	e.Connect()

	led := gpio.NewLedDriver(e, "13")
	led.Start()

	for {
		led.Toggle()
		time.Sleep(1000 * time.Millisecond)
	}
}

"Master" Gobot

You can also use the full capabilities of the framework aka "Master Gobot" to control swarms of robots or other features such as the built-in API server. For example:

package main

import (
	"fmt"
	"time"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/api"
	"gobot.io/x/gobot/platforms/sphero"
)

func NewSwarmBot(port string) *gobot.Robot {
	spheroAdaptor := sphero.NewAdaptor(port)
	spheroDriver := sphero.NewSpheroDriver(spheroAdaptor)
	spheroDriver.SetName("Sphero" + port)

	work := func() {
		spheroDriver.Stop()

		spheroDriver.On(sphero.Collision, func(data interface{}) {
			fmt.Println("Collision Detected!")
		})

		gobot.Every(1*time.Second, func() {
			spheroDriver.Roll(100, uint16(gobot.Rand(360)))
		})
		gobot.Every(3*time.Second, func() {
			spheroDriver.SetRGB(uint8(gobot.Rand(255)),
				uint8(gobot.Rand(255)),
				uint8(gobot.Rand(255)),
			)
		})
	}

	robot := gobot.NewRobot("sphero",
		[]gobot.Connection{spheroAdaptor},
		[]gobot.Device{spheroDriver},
		work,
	)

	return robot
}

func main() {
	master := gobot.NewMaster()
	api.NewAPI(master).Start()

	spheros := []string{
		"/dev/rfcomm0",
		"/dev/rfcomm1",
		"/dev/rfcomm2",
		"/dev/rfcomm3",
	}

	for _, port := range spheros {
		master.AddRobot(NewSwarmBot(port))
	}

	master.Start()
}

Hardware Support

Gobot has a extensible system for connecting to hardware devices. The following robotics and physical computing platforms are currently supported:

• Arduino <=> Package
• Audio <=> Package
• Beaglebone Black <=> Package
• Bluetooth LE <=> Package
• C.H.I.P <=> Package
• Digispark <=> Package
• DragonBoard <=> Package
• ESP8266 <=> Package
• Intel Edison <=> Package
• Intel Joule <=> Package
• Joystick <=> Package
• Keyboard <=> Package
• Leap Motion <=> Package
• MavLink <=> Package
• MegaPi <=> Package
• Microbit <=> Package
• MQTT <=> Package
• NATS <=> Package
• Neurosky <=> Package
• OpenCV <=> Package
• Particle <=> Package
• Parrot ARDrone 2.0 <=> Package
• Parrot Bebop <=> Package
• Parrot Minidrone <=> Package
• Pebble <=> Package
• Raspberry Pi <=> Package
• Sphero <=> Package
• Sphero BB-8 <=> Package
• Sphero Ollie <=> Package

Support for many devices that use General Purpose Input/Output (GPIO) have a shared set of drivers provided using the gobot/drivers/gpio package:

• GPIO <=> Drivers
  • Button
  • Buzzer
  • Direct Pin
  • Grove Button
  • Grove Buzzer
  • Grove LED
  • Grove Magnetic Switch
  • Grove Relay
  • Grove Touch Sensor
  • LED
  • Makey Button
  • Motor
  • Proximity Infra Red (PIR) Motion Sensor
  • Relay
  • RGB LED
  • Servo

Support for many devices that use Analog Input/Output (AIO) have a shared set of drivers provided using the gobot/drivers/aio package:

• AIO <=> Drivers
  • Analog Sensor
  • Grove Light Sensor
  • Grove Piezo Vibration Sensor
  • Grove Rotary Dial
  • Grove Sound Sensor
  • Grove Temperature Sensor

Support for devices that use Inter-Integrated Circuit (I2C) have a shared set of drivers provided using the gobot/drivers/i2c package:

• I2C <=> Drivers
  • Adafruit Motor Hat
  • BlinkM LED
  • BMP180 Barometric Pressure/Temperature/Altitude Sensor
  • DRV2605L Haptic Controller
  • Grove Digital Accelerometer
  • Grove RGB LCD
  • HMC6352 Compass
  • JHD1313M1 LCD Display w/RGB Backlight
  • L3GD20H 3-Axis Gyroscope
  • LIDAR-Lite
  • MCP23017 Port Expander
  • MMA7660 3-Axis Accelerometer
  • MPL115A2 Barometer
  • MPU6050 Accelerometer/Gyroscope
  • SHT3x-D Temperature/Humidity
  • TSL2561 Digital Luminosity/Lux/Light Sensor
  • Wii Nunchuck Controller

More platforms and drivers are coming soon...

API:

Gobot includes a RESTful API to query the status of any robot running within a group, including the connection and device status, and execute device commands.

To activate the API, import the gobot.io/x/gobot/api package and instantiate the API like this:

  master := gobot.NewMaster()
  api.NewAPI(master).Start()

You can also specify the api host and port, and turn on authentication:

  master := gobot.NewMaster()
  server := api.NewAPI(master)
  server.Port = "4000"
  server.AddHandler(api.BasicAuth("gort", "klatuu"))
  server.Start()

You may access the robeaux React.js interface with Gobot by navigating to http://localhost:3000/index.html.

CLI

Gobot uses the Gort http://gort.io Command Line Interface (CLI) so you can access important features right from the command line. We call it "RobotOps", aka "DevOps For Robotics". You can scan, connect, update device firmware, and more!

Gobot also has its own CLI to generate new platforms, adaptors, and drivers. You can check it out in the /cli directory.

Documentation

We're busy adding documentation to our web site at http://gobot.io/ please check there as we continue to work on Gobot

Thank you!

Need help?

• Join our mailing list: https://groups.google.com/forum/#!forum/gobotio
• Issues: https://github.com/hybridgroup/gobot/issues
• twitter: @gobotio

Contributing

For our contribution guidelines, please go to https://github.com/hybridgroup/gobot/blob/master/CONTRIBUTING.md .

Gobot is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. You can read about it here.

License

Copyright (c) 2013-2017 The Hybrid Group. Licensed under the Apache 2.0 license.

The Contributor Covenant is released under the Creative Commons Attribution 4.0 International Public License, which requires that attribution be included.

Documentation

Overview

Package gobot is the primary entrypoint for Gobot (http://gobot.io), a framework for robotics, physical computing, and the Internet of Things written using the Go programming language .

It provides a simple, yet powerful way to create solutions that incorporate multiple, different hardware devices at the same time.

Classic Gobot

Here is a "Classic Gobot" program that blinks an LED using an Arduino:

package main

import (
	"time"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/drivers/gpio"
	"gobot.io/x/gobot/platforms/firmata"
)

func main() {
	firmataAdaptor := firmata.NewAdaptor("/dev/ttyACM0")
	led := gpio.NewLedDriver(firmataAdaptor, "13")

	work := func() {
		gobot.Every(1*time.Second, func() {
			led.Toggle()
		})
	}

	robot := gobot.NewRobot("bot",
		[]gobot.Connection{firmataAdaptor},
		[]gobot.Device{led},
		work,
	)

	robot.Start()
}

Metal Gobot

You can also use Metal Gobot and pick and choose from the various Gobot packages to control hardware with nothing but pure idiomatic Golang code. For example:

package main

import (
	"gobot.io/x/gobot/drivers/gpio"
	"gobot.io/x/gobot/platforms/intel-iot/edison"
	"time"
)

func main() {
	e := edison.NewAdaptor()
	e.Connect()

	led := gpio.NewLedDriver(e, "13")
	led.Start()

	for {
		led.Toggle()
		time.Sleep(1000 * time.Millisecond)
	}
}

Master Gobot

Finally, you can use Master Gobot to add the complete Gobot API or control swarms of Robots:

package main

import (
	"fmt"
	"time"

	"gobot.io/x/gobot"
	"gobot.io/x/gobot/api"
	"gobot.io/x/gobot/platforms/sphero"
)

func NewSwarmBot(port string) *gobot.Robot {
	spheroAdaptor := sphero.NewAdaptor(port)
	spheroDriver := sphero.NewSpheroDriver(spheroAdaptor)
	spheroDriver.SetName("Sphero" + port)

	work := func() {
		spheroDriver.Stop()

		spheroDriver.On(sphero.Collision, func(data interface{}) {
			fmt.Println("Collision Detected!")
		})

		gobot.Every(1*time.Second, func() {
			spheroDriver.Roll(100, uint16(gobot.Rand(360)))
		})
		gobot.Every(3*time.Second, func() {
			spheroDriver.SetRGB(uint8(gobot.Rand(255)),
				uint8(gobot.Rand(255)),
				uint8(gobot.Rand(255)),
			)
		})
	}

	robot := gobot.NewRobot("sphero",
		[]gobot.Connection{spheroAdaptor},
		[]gobot.Device{spheroDriver},
		work,
	)

	return robot
}

func main() {
	master := gobot.NewMaster()
	api.NewAPI(master).Start()

	spheros := []string{
		"/dev/rfcomm0",
		"/dev/rfcomm1",
		"/dev/rfcomm2",
		"/dev/rfcomm3",
	}

	for _, port := range spheros {
		master.AddRobot(NewSwarmBot(port))
	}

	master.Start()
}

Copyright (c) 2013-2017 The Hybrid Group. Licensed under the Apache 2.0 license.

Index

• func After(t time.Duration, f func())
• func DefaultName(name string) string
• func Every(t time.Duration, f func()) *time.Ticker
• func FromScale(input, min, max float64) float64
• func Rand(max int) int
• func ToScale(input, min, max float64) float64
• func Version() string
• type Adaptor
• type Commander
  • func NewCommander() Commander
• type Connection
• type Connections
  • func (c *Connections) Each(f func(Connection))
  • func (c *Connections) Finalize() (err error)
  • func (c *Connections) Len() int
  • func (c *Connections) Start() (err error)
• type Device
• type Devices
  • func (d *Devices) Each(f func(Device))
  • func (d *Devices) Halt() (err error)
  • func (d *Devices) Len() int
  • func (d *Devices) Start() (err error)
• type Driver
• type Event
  • func NewEvent(name string, data interface{}) *Event
• type Eventer
  • func NewEventer() Eventer
• type JSONConnection
  • func NewJSONConnection(connection Connection) *JSONConnection
• type JSONDevice
  • func NewJSONDevice(device Device) *JSONDevice
• type JSONMaster
  • func NewJSONMaster(gobot *Master) *JSONMaster
• type JSONRobot
  • func NewJSONRobot(robot *Robot) *JSONRobot
• type Master
  • func NewMaster() *Master
  • func (g *Master) AddRobot(r *Robot) *Robot
  • func (g *Master) Robot(name string) *Robot
  • func (g *Master) Robots() *Robots
  • func (g *Master) Start() (err error)
  • func (g *Master) Stop() (err error)
• type Pinner
• type Porter
• type Robot
  • func NewRobot(v ...interface{}) *Robot
  • func (r *Robot) AddConnection(c Connection) Connection
  • func (r *Robot) AddDevice(d Device) Device
  • func (r *Robot) Connection(name string) Connection
  • func (r *Robot) Connections() *Connections
  • func (r *Robot) Device(name string) Device
  • func (r *Robot) Devices() *Devices
  • func (r *Robot) Start(args ...interface{}) (err error)
  • func (r *Robot) Stop() error
• type Robots
  • func (r *Robots) Each(f func(*Robot))
  • func (r *Robots) Len() int
  • func (r *Robots) Start(args ...interface{}) (err error)
  • func (r *Robots) Stop() (err error)

Examples

• After
• Every
• FromScale
• Rand
• ToScale

Functions

func After

func After(t time.Duration, f func())

After triggers f after t duration.

Example

package main

import (
	"fmt"
	"time"

	"gobot.io/x/gobot"
)

func main() {
	gobot.After(1*time.Second, func() {
		fmt.Println("Hello")
	})
}

func DefaultName

func DefaultName(name string) string

DefaultName returns a sensible random default name for a robot, adaptor or driver

func Every

func Every(t time.Duration, f func()) *time.Ticker

Every triggers f every t time.Duration until the end of days, or when a Stop() is called on the Ticker that is returned by the Every function. It does not wait for the previous execution of f to finish before it fires the next f.

Example

package main

import (
	"fmt"
	"time"

	"gobot.io/x/gobot"
)

func main() {
	gobot.Every(1*time.Second, func() {
		fmt.Println("Hello")
	})
}

func FromScale

func FromScale(input, min, max float64) float64

FromScale returns a converted input from min, max to 0.0...1.0.

Example

package main

import (
	"fmt"

	"gobot.io/x/gobot"
)

func main() {
	fmt.Println(gobot.FromScale(5, 0, 10))
}

Output:

0.5

func Rand

func Rand(max int) int

Rand returns a positive random int up to max

Example

package main

import (
	"fmt"

	"gobot.io/x/gobot"
)

func main() {
	i := gobot.Rand(100)
	fmt.Printf("%v is > 0 && < 100", i)
}

func ToScale

func ToScale(input, min, max float64) float64

ToScale returns a converted input from 0...1 to min...max scale. If input is less than min then ToScale returns min. If input is greater than max then ToScale returns max

Example

package main

import (
	"fmt"

	"gobot.io/x/gobot"
)

func main() {
	fmt.Println(gobot.ToScale(500, 0, 10))
}

Output:

10

func Version

func Version() string

Version returns the current Gobot version

Types

type Adaptor

type Adaptor interface {
	// Name returns the label for the Adaptor
	Name() string
	// SetName sets the label for the Adaptor
	SetName(n string)
	// Connect initiates the Adaptor
	Connect() error
	// Finalize terminates the Adaptor
	Finalize() error
}

Adaptor is the interface that describes an adaptor in gobot

type Commander

type Commander interface {
	// Command returns a command given a name. Returns nil if the command is not found.
	Command(string) (command func(map[string]interface{}) interface{})
	// Commands returns a map of commands.
	Commands() (commands map[string]func(map[string]interface{}) interface{})
	// AddCommand adds a command given a name.
	AddCommand(name string, command func(map[string]interface{}) interface{})
}

Commander is the interface which describes the behaviour for a Driver or Adaptor which exposes API commands.

func NewCommander

func NewCommander() Commander

NewCommander returns a new Commander.

type Connection

type Connection Adaptor

A Connection is an instance of an Adaptor

type Connections

type Connections []Connection

Connections represents a collection of Connection

func (*Connections) Each

func (c *Connections) Each(f func(Connection))

Each enumerates through the Connections and calls specified callback function.

func (*Connections) Finalize

func (c *Connections) Finalize() (err error)

Finalize calls Finalize on each Connection in c

func (*Connections) Len

func (c *Connections) Len() int

Len returns connections length

func (*Connections) Start

func (c *Connections) Start() (err error)

Start calls Connect on each Connection in c

type Device

type Device Driver

A Device is an instnace of a Driver

type Devices

type Devices []Device

Devices represents a collection of Device

func (*Devices) Each

func (d *Devices) Each(f func(Device))

Each enumerates through the Devices and calls specified callback function.

func (*Devices) Halt

func (d *Devices) Halt() (err error)

Halt calls Halt on each Device in d

func (*Devices) Len

func (d *Devices) Len() int

Len returns devices length

func (*Devices) Start

func (d *Devices) Start() (err error)

Start calls Start on each Device in d

type Driver

type Driver interface {
	// Name returns the label for the Driver
	Name() string
	// SetName sets the label for the Driver
	SetName(s string)
	// Start initiates the Driver
	Start() error
	// Halt terminates the Driver
	Halt() error
	// Connection returns the Connection assiciated with the Driver
	Connection() Connection
}

Driver is the interface that describes a driver in gobot

type Event

type Event struct {
	Name string
	Data interface{}
}

Event represents when something asyncronous happens in a Driver or Adaptor

func NewEvent

func NewEvent(name string, data interface{}) *Event

NewEvent returns a new Event and its associated data.

type Eventer

type Eventer interface {
	// Events returns the map of valid Event names.
	Events() (eventnames map[string]string)

	// Event returns an Event string from map of valid Event names.
	// Mostly used to validate that an Event name is valid.
	Event(name string) string

	// AddEvent registers a new Event name.
	AddEvent(name string)

	// DeleteEvent removes a previously registered Event name.
	DeleteEvent(name string)

	// Publish new events to any subscriber
	Publish(name string, data interface{})

	// Subscribe to events
	Subscribe() (events eventChannel)

	// Unsubscribe from an event channel
	Unsubscribe(events eventChannel)

	// Event handler
	On(name string, f func(s interface{})) (err error)

	// Event handler, only executes one time
	Once(name string, f func(s interface{})) (err error)
}

Eventer is the interface which describes how a Driver or Adaptor handles events.

func NewEventer

func NewEventer() Eventer

NewEventer returns a new Eventer.

type JSONConnection

type JSONConnection struct {
	Name    string `json:"name"`
	Adaptor string `json:"adaptor"`
}

JSONConnection is a JSON representation of a Connection.

func NewJSONConnection

func NewJSONConnection(connection Connection) *JSONConnection

NewJSONConnection returns a JSONConnection given a Connection.

type JSONDevice

type JSONDevice struct {
	Name       string   `json:"name"`
	Driver     string   `json:"driver"`
	Connection string   `json:"connection"`
	Commands   []string `json:"commands"`
}

JSONDevice is a JSON representation of a Device.

func NewJSONDevice

func NewJSONDevice(device Device) *JSONDevice

NewJSONDevice returns a JSONDevice given a Device.

type JSONMaster

type JSONMaster struct {
	Robots   []*JSONRobot `json:"robots"`
	Commands []string     `json:"commands"`
}

JSONMaster is a JSON representation of a Gobot Master.

func NewJSONMaster

func NewJSONMaster(gobot *Master) *JSONMaster

NewJSONMaster returns a JSONMaster given a Gobot Master.

type JSONRobot

type JSONRobot struct {
	Name        string            `json:"name"`
	Commands    []string          `json:"commands"`
	Connections []*JSONConnection `json:"connections"`
	Devices     []*JSONDevice     `json:"devices"`
}

JSONRobot a JSON representation of a Robot.

func NewJSONRobot

func NewJSONRobot(robot *Robot) *JSONRobot

NewJSONRobot returns a JSONRobot given a Robot.

type Master

type Master struct {
	AutoRun bool
	Commander
	Eventer
	// contains filtered or unexported fields
}

Master is the main type of your Gobot application and contains a collection of Robots, API commands that apply to the Master, and Events that apply to the Master.

func NewMaster

func NewMaster() *Master

NewMaster returns a new Gobot Master

func (*Master) AddRobot

func (g *Master) AddRobot(r *Robot) *Robot

AddRobot adds a new robot to the internal collection of robots. Returns the added robot

func (*Master) Robot

func (g *Master) Robot(name string) *Robot

Robot returns a robot given name. Returns nil if the Robot does not exist.

func (*Master) Robots

func (g *Master) Robots() *Robots

Robots returns all robots associated with this Gobot Master.

func (*Master) Start

func (g *Master) Start() (err error)

Start calls the Start method on each robot in its collection of robots. On error, call Stop to ensure that all robots are returned to a sane, stopped state.

func (*Master) Stop

func (g *Master) Stop() (err error)

Stop calls the Stop method on each robot in its collection of robots.

type Pinner

type Pinner interface {
	Pin() string
}

Pinner is the interface that describes a driver's pin

type Porter

type Porter interface {
	Port() string
}

Porter is the interface that describes an adaptor's port

type Robot

type Robot struct {
	Name string
	Work func()

	AutoRun bool

	Commander
	Eventer
	// contains filtered or unexported fields
}

Robot is a named entity that manages a collection of connections and devices. It contains its own work routine and a collection of custom commands to control a robot remotely via the Gobot api.

func NewRobot

func NewRobot(v ...interface{}) *Robot

NewRobot returns a new Robot. It supports the following optional params:

	name:	string with the name of the Robot. A name will be automatically generated if no name is supplied.
[]Connection: Connections which are automatically started and stopped with the robot
	[]Device: Devices which are automatically started and stopped with the robot
	func(): The work routine the robot will execute once all devices and connections have been initialized and started

func (*Robot) AddConnection

func (r *Robot) AddConnection(c Connection) Connection

AddConnection adds a new connection to the robots collection of connections. Returns the added connection.

func (*Robot) AddDevice

func (r *Robot) AddDevice(d Device) Device

AddDevice adds a new Device to the robots collection of devices. Returns the added device.

func (*Robot) Connection

func (r *Robot) Connection(name string) Connection

Connection returns a connection given a name. Returns nil if the Connection does not exist.

func (*Robot) Connections

func (r *Robot) Connections() *Connections

Connections returns all connections associated with this robot.

func (*Robot) Device

func (r *Robot) Device(name string) Device

Device returns a device given a name. Returns nil if the Device does not exist.

func (*Robot) Devices

func (r *Robot) Devices() *Devices

Devices returns all devices associated with this Robot.

func (*Robot) Start

func (r *Robot) Start(args ...interface{}) (err error)

Start a Robot's Connections, Devices, and work.

func (*Robot) Stop

func (r *Robot) Stop() error

Stop stops a Robot's connections and Devices

type Robots

type Robots []*Robot

Robots is a collection of Robot

func (*Robots) Each

func (r *Robots) Each(f func(*Robot))

Each enumerates through the Robots and calls specified callback function.

func (*Robots) Len

func (r *Robots) Len() int

Len returns the amount of Robots in the collection.

func (*Robots) Start

func (r *Robots) Start(args ...interface{}) (err error)

Start calls the Start method of each Robot in the collection

func (*Robots) Stop

func (r *Robots) Stop() (err error)

Stop calls the Stop method of each Robot in the collection