i2c

Documentation

Overview

Package i2c defines the API to communicate with devices over the I²C protocol.

As described in https://periph.io/x/periph/conn#hdr-Concepts, periph.io uses the concepts of Bus, Port and Conn.

In the package i2c, 'Port' is not exposed, since once you know the I²C device address, there's no unconfigured Port to configure.

Instead, the package includes the adapter 'Dev' to directly convert an I²C bus 'i2c.Bus' into a connection 'conn.Conn' by only specifying the device I²C address.

See https://en.wikipedia.org/wiki/I%C2%B2C for more information.

Example

package main

import (
	"fmt"
	"log"

	"periph.io/x/periph/conn/i2c"
	"periph.io/x/periph/conn/i2c/i2creg"
	"periph.io/x/periph/host"
)

func main() {
	// Make sure periph is initialized.
	if _, err := host.Init(); err != nil {
		log.Fatal(err)
	}

	// Use i2creg I²C bus registry to find the first available I²C bus.
	b, err := i2creg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer b.Close()

	// Dev is a valid conn.Conn.
	d := &i2c.Dev{Addr: 23, Bus: b}

	// Send a command 0x10 and expect a 5 bytes reply.
	write := []byte{0x10}
	read := make([]byte, 5)
	if err := d.Tx(write, read); err != nil {
		log.Fatal(err)
	}
	fmt.Printf("%v\n", read)
}

Index

• Constants
• type Addr
  • func (a *Addr) Set(s string) error
• type Bus
• type BusCloser
• type Dev
  • func (d *Dev) Duplex() conn.Duplex
  • func (d *Dev) String() string
  • func (d *Dev) Tx(w, r []byte) error
  • func (d *Dev) Write(b []byte) (int, error)
• type Pins

Examples

• Package
• Pins

Constants

const (
	SCL pin.Func = "I2C_SCL" // Clock
	SDA pin.Func = "I2C_SDA" // Data
)

Types

type Addr

type Addr uint16

Addr is an I²C slave address.

func (*Addr) Set

func (a *Addr) Set(s string) error

Set sets the Addr to a value represented by the string s. Values maybe in decimal or hexadecimal form. Set implements the flag.Value interface.

type Bus

type Bus interface {
	String() string
	// Tx does a transaction at the specified device address.
	//
	// Write is done first, then read. One of 'w' or 'r' can be omitted for a
	// unidirectional operation.
	Tx(addr uint16, w, r []byte) error
	// SetSpeed changes the bus speed, if supported.
	//
	// On linux due to the way the I²C sysfs driver is exposed in userland,
	// calling this function will likely affect *all* I²C buses on the host.
	SetSpeed(f physic.Frequency) error
}

Bus defines the interface a concrete I²C driver must implement.

This interface is consummed by a device driver for a device sitting on a bus.

This interface doesn't implement conn.Conn since a device address must be specified. Use i2cdev.Dev as an adapter to get a conn.Conn compatible object.

type BusCloser

type BusCloser interface {
	io.Closer
	Bus
}

BusCloser is an I²C bus that can be closed.

This interface is meant to be handled by the application and not the device driver. A device driver doesn't "own" a bus, hence it must operate on a Bus, not a BusCloser.

type Dev

type Dev struct {
	Bus  Bus
	Addr uint16
}

Dev is a device on a I²C bus.

It implements conn.Conn.

It saves from repeatedly specifying the device address.

func (*Dev) Duplex

func (d *Dev) Duplex() conn.Duplex

Duplex always return conn.Half for I²C.

func (*Dev) String

func (d *Dev) String() string

func (*Dev) Tx

func (d *Dev) Tx(w, r []byte) error

Tx does a transaction by adding the device's address to each command.

It's a wrapper for Bus.Tx().

func (*Dev) Write

func (d *Dev) Write(b []byte) (int, error)

Write writes to the I²C bus without reading, implementing io.Writer.

It's a wrapper for Tx()

type Pins

type Pins interface {
	// SCL returns the CLK (clock) pin.
	SCL() gpio.PinIO
	// SDA returns the DATA pin.
	SDA() gpio.PinIO
}

Pins defines the pins that an I²C bus interconnect is using on the host.

It is expected that a implementer of Bus also implement Pins but this is not a requirement.

Example

package main

import (
	"fmt"
	"log"

	"periph.io/x/periph/conn/i2c"
	"periph.io/x/periph/conn/i2c/i2creg"
	"periph.io/x/periph/host"
)

func main() {
	// Make sure periph is initialized.
	if _, err := host.Init(); err != nil {
		log.Fatal(err)
	}

	// Use i2creg I²C port registry to find the first available I²C bus.
	b, err := i2creg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer b.Close()

	// Prints out the gpio pin used.
	if p, ok := b.(i2c.Pins); ok {
		fmt.Printf("SDA: %s", p.SDA())
		fmt.Printf("SCL: %s", p.SCL())
	}
}