Home

Awesome

hwio

Introduction

hwio is a Go library for interfacing with hardware I/O, particularly on SoC-based boards such as BeagleBone Black, Raspberry Pi and Odroid-C1. It is loosely modelled on the Arduino programming style, but deviating where that doesn't make sense in Go. It makes use of a thin hardware abstraction via an interface so a program written against the library for say a BeagleBone could be easily compiled to run on a Raspberry Pi, maybe only changing pin references.

To use hwio, you just need to import it into your Go project, initialise modules and pins as required, and then use functions that manipulate the pins.

For more information about the library, including pin diagrams for supported boards and tutorials, see http://stuffwemade.net/hwio.

Digital Reads and Writes (GPIO)

Initialising a pin looks like this:

myPin, err := hwio.GetPin("gpio4")
err = hwio.PinMode(myPin, hwio.OUTPUT)

Or the shorter, more convenient form:

myPin, err := GetPinWithMode("gpio4", hwio.OUTPUT)

Unlike Arduino, where the pins are directly numbered and you just use the number, in hwio you get the pin first, by name. This is necessary as different hardware drivers may provide different pins.

The mode constants include:

(Pull-ups and pull-downs are not currently supported by the drivers, as this is not apparently exposed to file system.)

Writing a value to a pin looks like this:

hwio.DigitalWrite(myPin, hwio.HIGH)

Reading a value from a digital pin looks like this, returning a HIGH or LOW:

value, err := hwio.DigitalRead(myPin)

Analog

Analog pins are available on BeagleBone Black. Unlike Arduino, before using analog pins you need to enable the module. This is because external programs may have them open.

analog, e := hwio.GetAnalogModule()
if e != nil {
	fmt.Printf("could not get analog module: %s\n", e)
	return
}

analog.Enable()

Reading an analog value looks like this:

value, err := hwio.AnalogRead(somePin)

Analog values (on BeagleBone Black at least) are integers typically between 0-1800, which is the number of millivolts. (Note that you cannot drive analog inputs more than 1.8 volts on the BeagleBone, and you should use the analog voltage references it provides).

(Note: the Raspberry Pi does not have analog inputs onboard, and is not covered by the analog functions of hwio. However it is possible to use i2c to read from a compatible device, such as the MCP4725 or ADS1015. Adafruit has breakout boards for these devices.)

Cleaning Up on Exit

At the end of your application, call CloseAll(). This can be done at the end of the main() function with a defer:

defer hwio.CloseAll()

This will ensure that resources allocated (particularly GPIO pins) will be released, even if there is a panic.

If you want to close an individual GPIO pin, you can use:

hwio.ClosePin(pin)

Utility Functions

To delay a number of milliseconds:

hwio.Delay(500)  // delay 500ms

Or to delay by microseconds:

hwio.DelayMicroseconds(1500)  // delay 1500 usec, or 1.5 milliseconds

The Arduino ShiftOut function is supported in a simplified form for 8 bits:

e := hwio.ShiftOut(dataPin, clockPin, 127, hwio.MSBFIRST)   // write 8 bits, MSB first

or in a bigger variant that supports different sizes:

e := hwio.ShiftOutSize(dataPin, clockPin, someValue, hwio.LSBFIRST, 12)  // write 12 bits LSB first

Sometimes you might want to write an unsigned int to a set of digital pins (e.g. a parallel port). This can be done as follows:

somePins := []hwio.Pin{myPin3, myPin2, myPin1, myPin0}
e := hwio.WriteUIntToPins(myValue, somePins)

This will write out the n lowest bits of myValue, with the most significant bit of that value written to myPin3 etc. It uses DigitalWrite so the outputs are not written instantaneously.

There is an implementation of the Arduino map() function:

// map a value in range 0-1800 to new range 0-1023
i := hwio.Map(value, 0, 1800, 0, 1023)

To pulse a GPIO pin (must have been assigned), you can use the Pulse function:

e := hwio.Pulse(somePin, hwio.HIGH, 1500)

The second parameter is the logic level of the active level of the pulse. First the function sets the pin to the inactive state and then to the active state, before waiting the specified number of microseconds, and setting it inactive again.

On-board LEDs

On-board LEDs can be controlled using the helper function Led:

// Turn on usr0 LED
e := hwio.Led("usr0", true)

For BeagleBone, the LEDs are named "usr0", "usr1", "usr2" and "usr3" (case-insensitive). For Raspberry Pi only one of the LEDs is controllable, which is named "OK".

The Led function is a helper that uses the LED module. This provides more options to control what is displayed on each LED.

I2C

I2C is supported on BeagleBone Black and Raspberry Pi. It is accessible through the "i2c" module (BBB i2c2 pins), as follows:

m, e := hwio.GetModule("i2c")
if e != nil {
	fmt.Printf("could not get i2c module: %s\n", e)
	return
}
i2c := m.(hwio.I2CModule)

// Uncomment on Raspberry pi, which doesn't automatically enable i2c bus. BeagleBone does,
// as the default device tree enables it.

// i2c.Enable()
// defer i2c.Disable()

device := i2c.GetDevice(0x68)

Once you have a device, you can use Write, WriteBytes, Read or ReadBytes to set or get data from the i2c device.

e.g.

device.WriteByte(controlRegister, someValue)

While you can use the i2c types to directly talk to i2c devices, the specific device may already have higher-level support in the hwio/devices package, so check there first, as the hard work may be done already.

PWM

PWM support for BeagleBone Black has been added. To use a PWM pin, you need to fetch the module that the PWM belongs to, enable the PWM module and pin, and then you can manipulate the period and duty cycle. e.g.

// Get the module
m, e := hwio.GetModule("pwm2")
if e != nil {
	fmt.Printf("could not get pwm2 module: %s\n", e)
	return
}

pwm := m.(hwio.PWMModule)

// Enable it.
pwm.Enable()

// Get the PWM pin
pwm8_13, _ := hwio.GetPin("P8.13")
e = pwm.EnablePin(pwm8_13, true)
if e != nil {
	fmt.Printf("Error enabling pin: %s\n", e)
	return
}

// Set the period and duty cycle, in nanoseconds. This is a 1/10th second cycle
pwm.SetPeriod(pwm8_13, 100000000)
pwm.SetDuty(pwm8_13, 90000000)

On BeagleBone Black, there are 3 PWM modules, "pwm0", "pwm1" and "pwm2". I am not sure if "pwm1" pins can be assigned, as they are pre-allocated in the default device tree config, but in theory it should be possible to use them. By default, these pins can be used:

This is a preliminary implementation; only P8.13 (pwm2) has been tested. PWM pins are not present in default device tree. The module will add them dynamically as necessary to bonemgr/slots; this will override defaults.

Servo

There is a servo implementation in the hwio/servo package. See README.md in that package.

Devices

There are sub-packages under 'devices' that have been made to work with hwio. The currently supported devices include:

See README.md files in respective directories.

CPU Info

The helper function CpuInfo can tell you properties about your device. This is based on /proc/cpuinfo.

e.g. model := hwio.CpuInfo(0, "model name")

The properties available from device to device. Processor 0 is always present.

Driver Selection

The intention of the hwio library is to use uname to attempt to detect the platform and select an appropriate driver (see drivers section below), so for some platforms this may auto-detect. However, with the variety of boards around and the variety of operating systems, you may find that autodetection doesn't work. If you need to set the driver automatically, you can do:

hwio.SetDriver(new(BeagleBoneBlackDriver))

This needs to be done before any other hwio calls.

BIG SHINY DISCLAIMER

REALLY IMPORTANT THINGS TO KNOW ABOUT THIS ABOUT THIS LIBRARY:

Board Support

Currently there are 3 drivers:

Old pre-kernel-3.7 drivers for BeagleBone and Raspberry Pi have been deprecated as I have no test beds for these. If you want to use these, you can check out the 'legacy' branch that contains the older drivers, but no new features will be added.

BeagleBoneBlackDriver

This driver accesses hardware via the device interfaces exposed in the file system on linux kernels 3.8 or higher, where device tree is mandated. This should be a robust driver as the hardware access is maintained by device driver authors, but is likely to be not as fast as direct memory I/O to the hardware as there is file system overhead.

Status:

RaspberryPiDTDriver

This driver is very similar to the BeagleBone Black driver in that it uses the modules compiled into the kernel and configured using device tree. It uses the same GPIO and i2c implementatons, just with different pins.

Current status:

GetPin references on this driver return the pin numbers that are on the headers. Pin 0 is unimplemented.

Note: before using this, check your kernel is 3.7 or higher. There are a number of pre-3.7 distributions still in use, and this driver does not support pre-3.7.

OdroidC1Driver

This driver accesses hardware via the device interfaces exposed in the file system on linux kernels 3.8 or higher, where device tree is mandated. This should be a robust driver as the hardware access is maintained by device driver authors, but is likely to be not as fast as direct memory I/O to the hardware as there is file system overhead.

Status:

I2C is not loaded by default on this device. You need to either:

 modprobe aml_i2c

or to enable on each boot:

sudo echo "aml_i2c" >> /etc/modules

This makes the necessary /dev/i2c* files appear.

Implementation Notes

Some general principles the library attempts to adhere to include:

Pins

Pins are logical representation of physical pins on the hardware. To provide some abstraction, pins are numbered, much like on an Arduino. Unlike Arduino, there is no single mapping to hardware pins - this is done by the hardware driver. To make it easier to work with, drivers can give one or more names to a pin, and you can use GetPin to get a reference to the pin by one of those names.

Each driver must implement a method that defines the mapping from logical pins to physical pins as understood by that piece of hardware. Additionally, the driver also publishes the modules that the hardware configuration supports, so that hwio can ensure that constraints of the hardware are met. For example, if a pin implements PWM and GPIO in hardware, it is associated with two modules. When the PWM module is enabled, it will assign the pin to itself. Because each pin can have a different set of capabilities, there is no distinction between analog and digital pins as there is in Arduino; there is one set of pins, which may support any number of capabilities including digital and analog.

The caller generally works with logical pin numbers retrieved by GetPin.

Things to be done