i2c

Documentation

Overview

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

As described in https://periph.io/x/conn/v3#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/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/i2c"
	"periph.io/x/conn/v3/i2c/i2creg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.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
  • func (a Addr) String() string
• 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
• Addr (Flag)
• Pins

Constants

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

Well known pin functionality.

Types

type Addr

type Addr uint16

Addr is an I²C slave address.

Example (Flag)

package main

import (
	"flag"

	"periph.io/x/conn/v3/i2c"
)

func main() {
	var addr i2c.Addr
	flag.Var(&addr, "addr", "i2c device address")
	flag.Parse()
}

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.

func (Addr) String

func (a Addr) String() string

String returns an i2c.Addr as a string formated in hexadecimal.

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/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/i2c"
	"periph.io/x/conn/v3/i2c/i2creg"
)

func main() {
	// Make sure periph is initialized.
	// TODO: Use host.Init(). It is not used in this example to prevent circular
	// go package import.
	if _, err := driverreg.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())
	}
}