Documentation ¶
Overview ¶
Package embd provides a hardware abstraction layer for doing embedded programming on supported platforms like the Raspberry Pi, BeagleBone Black and CHIP. Most of the examples below will work without change (i.e. the same binary) on all supported platforms.
== Overall structure
It's best to think of the top-level embd package as a switchboard that doesn't implement anything on its own but rather relies on sub-packages for hosts drivers and devices and stitches them together. The exports in the top-level package serve a number of different purposes, which can be confusing at first: - it defines a number of driver interfaces, such as the GPIODriver, this is the interface that the driver for each specific platform must implement and is not something of concern to the typical user. - it defines the main low-level hardware interface types: analog pins, digital pins, interrupt pins, I2Cbuses, SPI buses, PWM pins and LEDs. Each type has a New function to instantiate one of these pins or buses. - it defines a number of InitXXX functions that initialize the various drivers, however, these are called by the coresponding NewXXX functions, so can be ignored. - it defines a number of top-level convenience functions, such as DigitalWrite, that can be called as 1-liners instead of first instantiating a DigitalPin and then writing to it
To get started a host driver needs to be registered with the top-level embd package. This is most easily accomplished by doing an "underscore import" on of the sub-packages of embd/host, e.g., `import _ "github.com/kidoman/embd/host/chip"`. An `Init()` function in the host driver registers all the individual drivers with embd.
After getting the host driver the next step might be to instantiate a GPIO pin using `NewDigitalPin` or an I2CBus using `NewI2CBus`. Such a pin or bus can be used directly but often it is passed into the initializer of a sensor, controller or other user-level driver which provides a high-level interface to some device. For example, the New function for the BMP180 type in the `embd/sensor/bmp180` package takes an I2CBus as argument, which it will use to reach the sensor.
== Samples
This section shows a few choice samples, more are available in the samples folder.
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
- Variables
- func ActiveLow(key interface{}, b bool) error
- func AnalogRead(key interface{}) (int, error)
- func CloseGPIO() error
- func CloseI2C() error
- func CloseLED() error
- func CloseSPI() error
- func DigitalRead(key interface{}) (int, error)
- func DigitalWrite(key interface{}, val int) error
- func FindFirstMatchingFile(glob string) (string, error)
- func InitGPIO() error
- func InitI2C() error
- func InitLED() error
- func InitSPI() error
- func LEDOff(key interface{}) error
- func LEDOn(key interface{}) error
- func LEDToggle(key interface{}) error
- func PullDown(key interface{}) error
- func PullUp(key interface{}) error
- func Register(host Host, describer Describer)
- func SetDirection(key interface{}, dir Direction) error
- func SetHost(host Host, rev int)
- type AnalogPin
- type Describer
- type Descriptor
- type DigitalPin
- type Direction
- type Edge
- type GPIODriver
- type Host
- type I2CBus
- type I2CDriver
- type InterruptPin
- type LED
- type LEDDriver
- type LEDMap
- type PWMPin
- type PinDesc
- type PinMap
- type Polarity
- type SPIBus
- type SPIDriver
Constants ¶
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" // HostCHIP represents the NextThing C.H.I.P. HostCHIP = "CHIP" )
const ( // Low represents 0. Low int = iota // High represents 1. High )
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 )
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 ¶
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.
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 ¶
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 ¶
AnalogWrite reads a value from the pin.
func CloseGPIO ¶
func CloseGPIO() error
CloseGPIO releases resources associated with the GPIO driver.
func DigitalRead ¶
DigitalRead reads a value from the pin.
func DigitalWrite ¶
DigitalWrite writes val to the pin.
func FindFirstMatchingFile ¶
FindFirstMatchingFile finds the first glob match in the filesystem. Inspiration: https://github.com/mrmorphic/hwio/blob/master/hwio.go#L451
func Register ¶
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 ¶
SetDirection sets the direction of the pin (in/out).
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 ¶
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 { InterruptPin // 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 GPIODriver ¶
type GPIODriver interface { // PinMap returns the pinmap for this driver. PinMap() PinMap // 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 ¶
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) // ReadBytes reads a slice of bytes from the given address. ReadBytes(addr byte, num int) (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.
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 InterruptPin ¶
type InterruptPin interface { // Start watching this pin for interrupt Watch(edge Edge, handler func(DigitalPin)) error // Stop watching this pin for interrupt StopWatching() error }
InterruptPin implements access to an interrupt capable GPIO pin. The basic capability provided is to watch for a transition on the pin and generate a callback to a handler when a transition occurs. On Linux the underlying implementation generally uses epoll to receive the interrupts at user-level.
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.
type LEDDriver ¶
LEDDriver interface interacts with the host descriptors to allow us control of the LEDs.
func NewLEDDriver ¶
NewLEDDriver returns a LEDDriver interface which allows control over the LED subsystem.
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.
type PinMap ¶
type PinMap []*PinDesc
PinMap type represents a collection of pin descriptors.
func (PinMap) Lookup ¶
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 SPIBus ¶
type SPIBus interface { io.Writer // TransferAndReceiveData transmits data in a buffer(slice) and receives into it. TransferAndReceiveData(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.
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 ¶
NewSPIDriver returns a SPIDriver interface which allows control over the SPI bus.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package controller is a container for the various device controllers supported by EMBD.
|
Package controller is a container for the various device controllers supported by EMBD. |
hd44780
Package hd44780 allows controlling an HD44780-compatible character LCD controller.
|
Package hd44780 allows controlling an HD44780-compatible character LCD 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 Digital I/O I²C LED control They are used by the hosts to satiate the HAL.
|
Package generic provides generic (to Linux) drivers for functionalities like Digital I/O I²C LED control They are used by the hosts to satiate the HAL. |
rpi
Package rpi provides Raspberry Pi (including A+/B+) support.
|
Package rpi provides Raspberry Pi (including A+/B+) support. |
interface
|
|
display/characterdisplay
Package characterdisplay provides an ease-of-use layer on top of a character display controller.
|
Package characterdisplay provides an ease-of-use layer on top of a character display controller. |
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. |