i2creg

Documentation

Overview

Package i2creg defines I²C bus registry to list buses present on the host.

Example

package main

import (
	"flag"
	"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)
	}

	// A command line tool may let the user choose a I²C port, yet default to the
	// first port known.
	name := flag.String("i2c", "", "I²C bus to use")
	flag.Parse()
	b, err := i2creg.Open(*name)
	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

• func Open(name string) (i2c.BusCloser, error)
• func Register(name string, aliases []string, number int, o Opener) error
• func Unregister(name string) error
• type Opener
• type Ref
  • func All() []*Ref

Examples

• Package
• All
• Open

Functions

func Open

func Open(name string) (i2c.BusCloser, error)

Open opens an I²C bus by its name, an alias or its number and returns an handle to it.

Specify the empty string "" to get the first available bus. This is the recommended default value unless an application knows the exact bus to use.

Each bus can register multiple aliases, each leading to the same bus handle.

"Bus number" is a generic concept that is highly dependent on the platform and OS. On some platform, the first bus may have the number 0, 1 or higher. Bus numbers are not necessarily continuous and may not start at 0. It was observed that the bus number as reported by the OS may change across OS revisions.

When the I²C bus is provided by an off board plug and play bus like USB via a FT232H USB device, there can be no associated number.

Example

package main

import (
	"log"

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

	// On Linux, the following calls will likely open the same bus.
	_, _ = i2creg.Open("/dev/i2c-1")
	_, _ = i2creg.Open("I2C1")
	_, _ = i2creg.Open("1")

	// Opens the first default I²C bus found:
	_, _ = i2creg.Open("")

	// Wondering what to do with the opened i2c.BusCloser? Look at the package's
	// example above.
}

func Register

func Register(name string, aliases []string, number int, o Opener) error

Register registers an I²C bus.

Registering the same bus name twice is an error, e.g. o.Name(). o.Number() can be -1 to signify that the bus doesn't have an inherent "bus number". A good example is a bus provided over a FT232H device connected on an USB bus. In this case, the bus name should be created from the serial number of the device for unique identification.

func Unregister

func Unregister(name string) error

Unregister removes a previously registered I²C bus.

This can happen when an I²C bus is exposed via an USB device and the device is unplugged.

Types

type Opener

type Opener func() (i2c.BusCloser, error)

Opener opens an handle to a bus.

It is provided by the actual bus driver.

type Ref

type Ref struct {
	// Name of the bus.
	//
	// It must not be a sole number. It must be unique across the host.
	Name string
	// Aliases are the alternative names that can be used to reference this bus.
	Aliases []string
	// Number of the bus or -1 if the bus doesn't have any "native" number.
	//
	// Buses provided by the CPU normally have a 0 based number. Buses provided
	// via an addon (like over USB) generally are not numbered.
	Number int
	// Open is the factory to open an handle to this I²C bus.
	Open Opener
}

Ref references an I²C bus.

It is returned by All() to enumerate all registered buses.

func All

func All() []*Ref

All returns a copy of all the registered references to all know I²C buses available on this host.

The list is sorted by the bus name.

Example

package main

import (
	"fmt"
	"log"
	"strings"

	"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)
	}

	// Enumerate all I²C buses available and the corresponding pins.
	fmt.Print("I²C buses available:\n")
	for _, ref := range i2creg.All() {
		fmt.Printf("- %s\n", ref.Name)
		if ref.Number != -1 {
			fmt.Printf("  %d\n", ref.Number)
		}
		if len(ref.Aliases) != 0 {
			fmt.Printf("  %s\n", strings.Join(ref.Aliases, " "))
		}

		b, err := ref.Open()
		if err != nil {
			fmt.Printf("  Failed to open: %v", err)
		}
		if p, ok := b.(i2c.Pins); ok {
			fmt.Printf("  SDA: %s", p.SDA())
			fmt.Printf("  SCL: %s", p.SCL())
		}
		if err := b.Close(); err != nil {
			fmt.Printf("  Failed to close: %v", err)
		}
	}
}