drivers

README

TinyGo Drivers

This package provides a collection of over 100 different hardware drivers for devices such as sensors, displays, wireless adaptors, and actuators, that can be used together with TinyGo.

For the complete list, please see: https://tinygo.org/docs/reference/devices/

Installing

go get tinygo.org/x/drivers

How to use

Here is an example in TinyGo that uses the BMP180 digital barometer. This example should work on any board that supports I2C:

package main

import (
    "time"

    "machine"

    "tinygo.org/x/drivers/bmp180"
)

func main() {
    machine.I2C0.Configure(machine.I2CConfig{})
    sensor := bmp180.New(machine.I2C0)
    sensor.Configure()

    connected := sensor.Connected()
    if !connected {
        println("BMP180 not detected")
        return
    }
    println("BMP180 detected")

    for {
        temp, _ := sensor.ReadTemperature()
        println("Temperature:", float32(temp)/1000, "°C")

        pressure, _ := sensor.ReadPressure()
        println("Pressure", float32(pressure)/100000, "hPa")

        time.Sleep(2 * time.Second)
    }
}

Examples Using GPIO or SPI

If compiling these examples directly you are likely to need to make minor changes to the defined variables to map the pins for the board you are using. For example, this block in main.go:

var (
        spi   = machine.SPI0
        csPin = machine.D5
)

It might not be obvious, but you need to change these to match how you wired your specific board. Constants are defined for each supported microcontroller.

For example, to change the definitions for use on a Raspberry Pi Pico using typical wiring, you might need to do this:

var (
        spi   = machine.SPI0
        csPin = machine.GP17
)

Contributing

Your contributions are welcome!

Please take a look at our CONTRIBUTING.md document for details.

License

This project is licensed under the BSD 3-clause license, just like the Go project itself.

Documentation

Overview

Package drivers provides a collection of hardware drivers for TinyGo (https://tinygo.org) for devices such as sensors and displays.

Here is an example in TinyGo that uses the BMP180 digital barometer:

package main

import (
	"time"
	"machine"

	"tinygo.org/x/drivers/bmp180"
)

func main() {
	machine.I2C0.Configure(machine.I2CConfig{})
	sensor := bmp180.New(machine.I2C0)
	sensor.Configure()

	connected := sensor.Connected()
	if !connected {
		println("BMP180 not detected")
		return
	}
	println("BMP180 detected")

	for {
		temp, _ := sensor.ReadTemperature()
		println("Temperature:", float32(temp)/1000, "°C")

		pressure, _ := sensor.ReadPressure()
		println("Pressure", float32(pressure)/100000, "hPa")

		time.Sleep(2 * time.Second)
	}
}

Each individual driver is contained within its own sub-package within this package and there are no interdependencies in order to minimize the final size of compiled code that uses any of these drivers.

Index

• Constants
• type Displayer
• type I2C
• type Measurement
• type Rotation
• type SPI
• type Sensor
• type UART

Constants

const (
	Rotation0 = iota
	Rotation90
	Rotation180
	Rotation270
	Rotation0Mirror
	Rotation90Mirror
	Rotation180Mirror
	Rotation270Mirror
)

Clockwise rotation of the screen.

const Version = "0.29.0"

Version returns a user-readable string showing the version of the drivers package for support purposes. Update this value before release of new version of software.

Types

type Displayer

type Displayer interface {
	// Size returns the current size of the display.
	Size() (x, y int16)

	// SetPizel modifies the internal buffer.
	SetPixel(x, y int16, c color.RGBA)

	// Display sends the buffer (if any) to the screen.
	Display() error
}

type I2C

type I2C interface {
	// Tx performs a [I²C] transaction with address addr.
	// Most I2C peripherals have some sort of register mapping scheme to allow
	// users to interact with them:
	//
	//  bus.Tx(addr, []byte{reg}, buf) // Reads register reg into buf.
	//  bus.Tx(addr, append([]byte{reg}, buf...), nil) // Writes buf into register reg.
	//
	// The semantics of most I2C transactions require that the w write buffer be non-empty.
	//
	// [I²C]: https://en.wikipedia.org/wiki/I%C2%B2C
	Tx(addr uint16, w, r []byte) error
}

I2C represents an I2C bus. It is notably implemented by the machine.I2C type.

type Measurement

type Measurement uint32

Measurement specifies a type of measurement, for example: temperature, acceleration, pressure.

const (
	Voltage Measurement = 1 << iota
	Temperature
	Humidity
	Pressure
	Distance
	Acceleration
	AngularVelocity
	MagneticField
	Luminosity
	Time
	// Gas or liquid concentration, usually measured in ppm (parts per million).
	Concentration

	// AllMeasurements is the OR of all Measurement values. It ensures all measurements are done.
	AllMeasurements Measurement = (1 << 32) - 1
)

Sensor measurements

type Rotation

type Rotation uint8

Rotation is how much a display has been rotated. Displays can be rotated, and sometimes also mirrored.

type SPI

type SPI interface {
	// Tx transmits the given buffer w and receives at the same time the buffer r.
	// The two buffers must be the same length. The only exception is when w or r are nil,
	// in which case Tx only transmits (without receiving) or only receives (while sending 0 bytes).
	Tx(w, r []byte) error

	// Transfer writes a single byte out on the SPI bus and receives a byte at the same time.
	// If you want to transfer multiple bytes, it is more efficient to use Tx instead.
	Transfer(b byte) (byte, error)
}

SPI represents a SPI bus. It is implemented by the machine.SPI type.

type Sensor

type Sensor interface {
	// Update performs IO to update the measurements of a sensor.
	// It shall return error only when the sensor encounters an error that prevents it from
	// storing all or part of the measurements it was called to do.
	Update(which Measurement) error
}

Sensor represents an object capable of making one or more measurements. A sensor will then have methods which read the last updated measurements.

Many Sensors may be collected into one Sensor interface to synchronize measurements.

type UART

type UART interface {
	io.Reader
	io.Writer

	Buffered() int
}

UART represents a UART connection. It is implemented by the machine.UART type.