embd

package module
v0.0.0-...-9401acd Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 9, 2014 License: MIT Imports: 10 Imported by: 0

README

embd Build Status GoDoc

embd is a hardware abstraction layer (HAL) for embedded systems.

It allows you to start your hardware hack on easily available hobby boards (like the Raspberry Pi, BeagleBone Black, etc.) by giving you staight forward access to the board's capabilities as well as a plethora of sensors (like accelerometers, gyroscopes, thermometers, etc.) and controllers (PWM generators, digital-to-analog convertors) for which we have written drivers. And when things get serious, you dont have to throw away the code. You carry forward the effort onto more custom designed boards where the HAL abstraction of EMBD will save you precious time.

Development supported and sponsored by ThoughtWorks

Also, you might be interested in: Why Golang?

Blog post introducing EMBD

Getting Started

After installing Go* and setting up your GOPATH, create your first .go file. We'll call it simpleblinker.go.

package main

import (
	"time"

	"github.com/kidoman/embd"
	_ "github.com/kidoman/embd/host/rpi" // This loads the RPi driver
)

func main() {
	for {
		embd.LEDToggle("LED0")
		time.Sleep(250 * time.Millisecond)
	}
}

Then install the EMBD package (go1.2 and greater is required):

$ go get github.com/kidoman/embd

Build the binary*:

$ export GOOS=linux
$ export GOARCH=arm
$ go build simpleblinker.go

Copy the cross-compiled binary to your RaspberryPi*:

$ scp simpleblinker pi@192.168.2.2:~

Then run the program with sudo*:

$ sudo ./simpleblinker

You will now see the green LED (next to the always on power LED) blink every 1/4 sec.

* Notes

  • Please install the cross compilers. Mac users: brew install go --cross-compile-common. goxc can be a big help as well
  • We are instructing the go compiler to create a binary which will run on the RaspberryPi processor
  • Assuming your RaspberryPi has an IP address of 192.168.2.2. Substitute as necessary
  • sudo (root) permission is required as we are controlling the hardware by writing to special files
  • This sample program is optimized for brevity and does not clean up after itself. Click here to see the full version

Getting Help

Join the mailing list

Platforms Supported

The command line tool

go get github.com/kidoman/embd/embd

will install a command line utility embd which will allow you to quickly get started with prototyping. The binary should be available in your $GOPATH/bin. However, to be able to run this on a ARM based device, you will need to build it with GOOS=linux and GOARCH=arm environment variables set.

But, since I am feeling so generous, a prebuilt/tested version is available for direct download and deployment here.

For example, if you run embd detect on a BeagleBone Black:

root@beaglebone:~# embd detect

detected host BeagleBone Black (rev 0)

Run embd without any arguments to discover the various commands supported by the utility.

How to use the framework

Package embd provides a 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 folder, we will show a few choice examples here.

Use the LED driver to toggle LEDs on the BBB:

import "github.com/kidoman/embd"
import _ "github.com/kidoman/embd/host/all"
...
embd.InitLED()
defer embd.CloseLED()
...
led, err := embd.NewLED(3)
...
led.Toggle()

Even shorter when quickly trying things out:

import "github.com/kidoman/embd"
import _ "github.com/kidoman/embd/host/all"
...
embd.InitLED()
defer embd.CloseLED()
...
embd.ToggleLED(3)

3 is the same as USR3 for all intents and purposes. The driver is smart enough to figure all this out.

BBB + PWM:

import "github.com/kidoman/embd"
import _ "github.com/kidoman/embd/host/all"
...
embd.InitGPIO()
defer embd.CloseGPIO()
...
pwm, _ := embd.NewPWMPin("P9_14")
defer pwm.Close()
...
pwm.SetDuty(1000)

Control GPIO pins on the RaspberryPi / BeagleBone Black:

import "github.com/kidoman/embd"
import _ "github.com/kidoman/embd/host/all"
...
embd.InitGPIO()
defer embd.CloseGPIO()
...
embd.SetDirection(10, embd.Out)
embd.DigitalWrite(10, embd.High)

Could also do:

import "github.com/kidoman/embd"
import _ "github.com/kidoman/embd/host/all"
...
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"
import _ "github.com/kidoman/embd/host/all"
...
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"
import _ "github.com/kidoman/embd/host/all"
...
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

Sensors Supported

Interfaces

Controllers

Convertors

  • MCP3008 8-channel, 10-bit ADC with SPI protocol, Datasheet

Contributing

We look forward to your pull requests, but contributions which abide by the guidelines will get a free beer!

File an issue, open a pull request. We are waiting.

About

EMBD is affectionately designed/developed by Karan Misra (kidoman), Kunal Powar (kunalpowar) and FRIENDS. We also have a list of CONTRIBUTORS.

Documentation

Overview

Package embd provides a 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 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)

BBB + PWM: 

import "github.com/kidoman/embd"
...
embd.InitGPIO()
defer embd.CloseGPIO()
...
pwm, _ := embd.NewPWMPin("P9_14")
defer pwm.Close()
...
pwm.SetDuty(1000)

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.

Index

Constants

View Source 
const (
	// HostNull reprents a null host.
	HostNull Host = ""

	// HostRPi represents the RaspberryPi.
	HostRPi = "Raspberry Pi"

	// HostBBB represents the BeagleBone Black.
	HostBBB = "BeagleBone Black"

	// HostGalileo represents the Intel Galileo board.
	HostGalileo = "Intel Galileo"

	// HostCubieTruck represents the Cubie Truck.
	HostCubieTruck = "CubieTruck"

	// HostRadxa represents the Radxa board.
	HostRadxa = "Radxa"
)
View Source 
const (
	// Low represents 0.
	Low int = iota

	// High represents 1.
	High
)
View Source 
const (
	// CapDigital represents the digital IO capability.
	CapDigital int = 1 << iota

	// CapI2C represents pins with the I2C capability.
	CapI2C

	// CapUART represents pins with the UART capability.
	CapUART

	// CapSPI represents pins with the SPI capability.
	CapSPI

	// CapGPMS represents pins with the GPMC capability.
	CapGPMC

	// CapLCD represents pins used to carry LCD data.
	CapLCD

	// CapPWM represents pins with PWM capability.
	CapPWM

	// CapAnalog represents pins with analog IO capability.
	CapAnalog
)
View Source 
const (

	// SPIMode0 represents the mode0 operation (CPOL=0 CPHA=0) of spi.
	SPIMode0 = (0 | 0)

	// SPIMode1 represents the mode0 operation (CPOL=0 CPHA=1) of spi.
	SPIMode1 = (0 | spiCpha)

	// SPIMode2 represents the mode0 operation (CPOL=1 CPHA=0) of spi.
	SPIMode2 = (spiCpol | 0)

	// SPIMode3 represents the mode0 operation (CPOL=1 CPHA=1) of spi.
	SPIMode3 = (spiCpol | spiCpha)
)

Variables

View Source 
var ErrFeatureNotImplemented = errors.New("embd: requested feature is not implemented")

ErrFeatureNotImplemented is returned when a particular feature is supported by the host but not implemented yet.

View Source 
var ErrFeatureNotSupported = errors.New("embd: requested feature is not supported")

ErrFeatureNotSupported is returned when the host does not support a particular feature.

Functions

func ActiveLow 

func ActiveLow(key interface{}, b bool) error

ActiveLow makes the pin active low. A low logical state is represented by a high state on the physical pin, and vice-versa.

func AnalogRead 

func AnalogRead(key interface{}) (int, error)

AnalogWrite reads a value from the pin.

func CloseGPIO 

func CloseGPIO() error

CloseGPIO releases resources associated with the GPIO driver.

func CloseI2C 

func CloseI2C() error

CloseI2C releases resources associated with the I2C driver.

func CloseLED 

func CloseLED() error

CloseLED releases resources associated with the LED driver.

func CloseSPI 

func CloseSPI() error

CloseSPI releases resources associated with the SPI driver.

func DigitalRead 

func DigitalRead(key interface{}) (int, error)

DigitalRead reads a value from the pin.

func DigitalWrite 

func DigitalWrite(key interface{}, val int) error

DigitalWrite writes val to the pin.

func FindFirstMatchingFile 

func FindFirstMatchingFile(glob string) (string, error)

FindFirstMatchingFile finds the first glob match in the filesystem. Inspiration: https://github.com/mrmorphic/hwio/blob/master/hwio.go#L451

func InitGPIO 

func InitGPIO() error

InitGPIO initializes the GPIO driver.

func InitI2C 

func InitI2C() error

InitI2C initializes the I2C driver.

func InitLED 

func InitLED() error

InitLED initializes the LED driver.

func InitSPI 

func InitSPI() error

InitSPI initializes the SPI driver.

func LEDOff 

func LEDOff(key interface{}) error

LEDOff switches the LED off.

func LEDOn 

func LEDOn(key interface{}) error

LEDOn switches the LED on.

func LEDToggle 

func LEDToggle(key interface{}) error

LEDToggle toggles the LED.

func PullDown 

func PullDown(key interface{}) error

PullDown pulls the pin down.

func PullUp 

func PullUp(key interface{}) error

PullUp pulls the pin up.

func Register 

func Register(host Host, describer Describer)

Register makes a host describer available by the provided host key. If Register is called twice with the same host or if describer is nil, it panics.

func SetDirection 

func SetDirection(key interface{}, dir Direction) error

SetDirection sets the direction of the pin (in/out).

func SetHost 

func SetHost(host Host, rev int)

SetHost overrides the host and revision no.

Types

type AnalogPin 

type AnalogPin interface {
	// N returns the logical GPIO number.
	N() int

	// Read reads the value from the pin.
	Read() (int, error)

	// Close releases the resources associated with the pin.
	Close() error
}

AnalogPin implements access to a analog IO capable GPIO pin.

func NewAnalogPin 

func NewAnalogPin(key interface{}) (AnalogPin, error)

NewAnalogPin returns a AnalogPin interface which allows control over the analog GPIO pin.

type Describer 

type Describer func(rev int) *Descriptor

The Describer type is a Descriptor provider.

type Descriptor 

type Descriptor struct {
	GPIODriver func() GPIODriver
	I2CDriver  func() I2CDriver
	LEDDriver  func() LEDDriver
	SPIDriver  func() SPIDriver
}

Descriptor represents a host descriptor.

func DescribeHost 

func DescribeHost() (*Descriptor, error)

DescribeHost returns the detected host descriptor. Can be overriden by calling SetHost though.

type DigitalPin 

type DigitalPin interface {
	// N returns the logical GPIO number.
	N() int

	// Write writes the provided value to the pin.
	Write(val int) error

	// Read reads the value from the pin.
	Read() (int, error)

	// TimePulse measures the duration of a pulse on the pin.
	TimePulse(state int) (time.Duration, error)

	// SetDirection sets the direction of the pin (in/out).
	SetDirection(dir Direction) error

	// ActiveLow makes the pin active low. A low logical state is represented by
	// a high state on the physical pin, and vice-versa.
	ActiveLow(b bool) error

	// PullUp pulls the pin up.
	PullUp() error

	// PullDown pulls the pin down.
	PullDown() error

	// Close releases the resources associated with the pin.
	Close() error
}

DigitalPin implements access to a digital IO capable GPIO pin.

func NewDigitalPin 

func NewDigitalPin(key interface{}) (DigitalPin, error)

NewDigitalPin returns a DigitalPin interface which allows control over the digital GPIO pin.

type Direction 

type Direction int

The Direction type indicates the direction of a GPIO pin. 

const (
	// In represents read mode.
	In Direction = iota

	// Out represents write mode.
	Out
)

type GPIODriver 

type GPIODriver interface {
	// Unregister unregisters the pin from the driver. Should be called when the pin is closed.
	Unregister(string) error

	// DigitalPin returns a pin capable of doing digital IO.
	DigitalPin(key interface{}) (DigitalPin, error)

	// AnalogPin returns a pin capable of doing analog IO.
	AnalogPin(key interface{}) (AnalogPin, error)

	// PWMPin returns a pin capable of generating PWM.
	PWMPin(key interface{}) (PWMPin, error)

	// Close releases the resources associated with the driver.
	Close() error
}

GPIODriver implements a generic GPIO driver.

func NewGPIODriver 

func NewGPIODriver(pinMap PinMap, dpf digitalPinFactory, apf analogPinFactory, ppf pwmPinFactory) GPIODriver

NewGPIODriver returns a GPIODriver interface which allows control over the GPIO subsystem.

type Host 

type Host string

The Host type represents all the supported host types.

func DetectHost 

func DetectHost() (Host, int, error)

DetectHost returns the detected host and its revision number.

type I2CBus 

type I2CBus interface {
	// ReadByte reads a byte from the given address.
	ReadByte(addr byte) (value byte, err error)
	// WriteByte writes a byte to the given address.
	WriteByte(addr, value byte) error
	// WriteBytes writes a slice bytes to the given address.
	WriteBytes(addr byte, value []byte) error

	// ReadFromReg reads n (len(value)) bytes from the given address and register.
	ReadFromReg(addr, reg byte, value []byte) error
	// ReadByteFromReg reads a byte from the given address and register.
	ReadByteFromReg(addr, reg byte) (value byte, err error)
	// ReadU16FromReg reads a unsigned 16 bit integer from the given address and register.
	ReadWordFromReg(addr, reg byte) (value uint16, err error)

	// WriteToReg writes len(value) bytes to the given address and register.
	WriteToReg(addr, reg byte, value []byte) error
	// WriteByteToReg writes a byte to the given address and register.
	WriteByteToReg(addr, reg, value byte) error
	// WriteU16ToReg
	WriteWordToReg(addr, reg byte, value uint16) error

	// Close releases the resources associated with the bus.
	Close() error
}

I2CBus interface is used to interact with the I2C bus.

func NewI2CBus 

func NewI2CBus(l byte) I2CBus

NewI2CBus returns a I2CBus.

type I2CDriver 

type I2CDriver interface {
	Bus(l byte) I2CBus

	// Close releases the resources associated with the driver.
	Close() error
}

I2CDriver interface interacts with the host descriptors to allow us control of I2C communication.

func NewI2CDriver 

func NewI2CDriver(ibf i2cBusFactory) I2CDriver

NewI2CDriver returns a I2CDriver interface which allows control over the I²C subsystem.

type LED 

type LED interface {
	// On switches the LED on.
	On() error

	// Off switches the LED off.
	Off() error

	// Toggle toggles the LED.
	Toggle() error

	// Close releases resources associated with the LED.
	Close() error
}

The LED interface is used to control a led on the prototyping board.

func NewLED 

func NewLED(key interface{}) (LED, error)

NewLED returns a LED interface which allows control over the LED.

type LEDDriver 

type LEDDriver interface {
	LED(key interface{}) (LED, error)

	Close() error
}

LEDDriver interface interacts with the host descriptors to allow us control of the LEDs.

func NewLEDDriver 

func NewLEDDriver(ledMap LEDMap, lf ledFactory) LEDDriver

NewLEDDriver returns a LEDDriver interface which allows control over the LED subsystem.

type LEDMap 

type LEDMap map[string][]string

LEDMap type represents a LED mapping for a host.

type PWMPin 

type PWMPin interface {
	// N returns the logical PWM id.
	N() string

	// SetPeriod sets the period of a pwm pin.
	SetPeriod(ns int) error

	// SetDuty sets the duty of a pwm pin.
	SetDuty(ns int) error

	// SetPolarity sets the polarity of a pwm pin.
	SetPolarity(pol Polarity) error

	// SetMicroseconds sends a command to the PWM driver to generate a us wide pulse.
	SetMicroseconds(us int) error

	// SetAnalog allows easy manipulation of the PWM based on a (0-255) range value.
	SetAnalog(value byte) error

	// Close releases the resources associated with the pin.
	Close() error
}

PWMPin implements access to a pwm capable GPIO pin.

func NewPWMPin 

func NewPWMPin(key interface{}) (PWMPin, error)

NewPWMPin returns a PWMPin interface which allows PWM signal generation over a the PWM pin.

type PinDesc 

type PinDesc struct {
	ID      string
	Aliases []string
	Caps    int

	DigitalLogical int
	AnalogLogical  int
}

PinDesc represents a pin descriptor.

type PinMap 

type PinMap []*PinDesc

PinMap type represents a collection of pin descriptors.

func (PinMap) Lookup 

func (m PinMap) Lookup(k interface{}, cap int) (*PinDesc, bool)

Lookup returns a pin descriptor matching the provided key and capability combination. This allows the same keys to be used across pins with differing capabilities. For example, it is perfectly fine to have: 

pin1: {Aliases: [10, GPIO10], Cap: CapDigital}
pin2: {Aliases: [10, AIN0], Cap: CapAnalog}

Searching for 10 with CapDigital will return pin1 and searching for 10 with CapAnalog will return pin2. This makes for a very pleasant to use API.

type Polarity 

type Polarity int

The Polarity type indicates the polarity of a pwm pin. 

const (
	// Positive represents (default) positive polarity.
	Positive Polarity = iota

	// Negative represents negative polarity.
	Negative
)

type SPIBus 

type SPIBus interface {
	// TransferAndRecieveData transmits data in a buffer(slice) and receives into it.
	TransferAndRecieveData(dataBuffer []uint8) error

	// ReceiveData receives data of length len into a slice.
	ReceiveData(len int) ([]uint8, error)

	// TransferAndReceiveByte transmits a byte data and receives a byte.
	TransferAndReceiveByte(data byte) (byte, error)

	// ReceiveByte receives a byte data.
	ReceiveByte() (byte, error)

	// Close releases the resources associated with the bus.
	Close() error
}

SPIBus interface allows interaction with the SPI bus.

func NewSPIBus 

func NewSPIBus(mode, channel byte, speed, bpw, delay int) SPIBus

NewSPIBus returns a SPIBus.

type SPIDriver 

type SPIDriver interface {
	// Bus returns a SPIBus interface which allows us to use spi functionalities
	Bus(byte, byte, int, int, int) SPIBus

	// Close cleans up all the initialized SPIbus
	Close() error
}

SPIDriver interface interacts with the host descriptors to allow us control of SPI communication.

func NewSPIDriver 

func NewSPIDriver(spiDevMinor byte, sbf spiBusFactory, i func() error) SPIDriver

NewSPIDriver returns a SPIDriver interface which allows control over the SPI bus.

Source Files

View all Source files

Directories

Path Synopsis
controller
mcp4725
Package mcp4725 allows interfacing with the MCP4725 DAC.
 Package mcp4725 allows interfacing with the MCP4725 DAC.
pca9685
Package pca9685 allows interfacing with the pca9685 16-channel, 12-bit PWM Controller through I2C protocol.
 Package pca9685 allows interfacing with the pca9685 16-channel, 12-bit PWM Controller through I2C protocol.
servoblaster
Package servoblaster allows interfacing with the software servoblaster driver.
 Package servoblaster allows interfacing with the software servoblaster driver.
Package convertors contains the various convertor modules for use on your platform.
 Package convertors contains the various convertor modules for use on your platform.
mcp3008
Package mcp3008 allows interfacing with the mcp3008 8-channel, 10-bit ADC through SPI protocol.
 Package mcp3008 allows interfacing with the mcp3008 8-channel, 10-bit ADC through SPI protocol.
Package host is a container for the various hosts supported by EMBD.
 Package host is a container for the various hosts supported by EMBD.
all
Package all conviniently loads all the inbuilt/supported host drivers.
 Package all conviniently loads all the inbuilt/supported host drivers.
bbb
Package bbb provides BeagleBone Black support.
 Package bbb provides BeagleBone Black support.
generic
Package generic provides generic (to Linux) drivers for functionalities like
 Package generic provides generic (to Linux) drivers for functionalities like
rpi
Package rpi provides Raspberry Pi support.
 Package rpi provides Raspberry Pi support.
interface
keypad/matrix4x3
Package matrix4x3 allows interfacing 4x3 keypad with Raspberry pi.
 Package matrix4x3 allows interfacing 4x3 keypad with Raspberry pi.
motion
servo
Package servo allows control of servos using a PWM controller.
 Package servo allows control of servos using a PWM controller.
Package sensor contains the various sensors modules for use on your platform.
 Package sensor contains the various sensors modules for use on your platform.
bh1750fvi
Package BH1750FVI allows interfacing with the BH1750FVI ambient light sensor through I2C.
 Package BH1750FVI allows interfacing with the BH1750FVI ambient light sensor through I2C.
bmp085
Package bmp085 allows interfacing with Bosch BMP085 barometric pressure sensor.
 Package bmp085 allows interfacing with Bosch BMP085 barometric pressure sensor.
bmp180
Package bmp180 allows interfacing with Bosch BMP180 barometric pressure sensor.
 Package bmp180 allows interfacing with Bosch BMP180 barometric pressure sensor.
l3gd20
Package l3gd20 allows interacting with L3GD20 gyroscoping sensor.
 Package l3gd20 allows interacting with L3GD20 gyroscoping sensor.
lsm303
Package lsm303 allows interfacing with the LSM303 magnetometer.
 Package lsm303 allows interfacing with the LSM303 magnetometer.
tmp006
Package tmp006 allows interfacing with the TMP006 thermopile.
 Package tmp006 allows interfacing with the TMP006 thermopile.
us020
Package us020 allows interfacing with the US020 ultrasonic range finder.
 Package us020 allows interfacing with the US020 ultrasonic range finder.
watersensor
Package watersensor allows interfacing with the water sensor.
 Package watersensor allows interfacing with the water sensor.
Package util contains utility functions.
 Package util contains utility functions.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.