Documentation

Overview

Package onewire defines the API to communicate with devices over the Dallas Semiconductor / Maxim Integrated 1-wire 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 onewire, 'Port' is not exposed, since once you know the 1-wire device address, there's no unconfigured Port to configure.

Instead, the package includes the adapter 'Dev' to directly convert an 1-wire bus 'onewire.Bus' into a connection 'conn.Conn' by only specifying the device 1-wire address.

See https://en.wikipedia.org/wiki/1-Wire for more information.

References

Overview: https://www.maximintegrated.com/en/app-notes/index.mvp/id/1796

App notes: https://www.maximintegrated.com/en/design/techdocs/app-notes/index.mvp/id/1/c/1-Wire%26reg%3B%20Devices

Example

Code:

package main

import (
	"fmt"
	"log"
	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/onewire"
	"periph.io/x/conn/v3/onewire/onewirereg"
)

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 onewirereg 1-wire bus registry to find the first available 1-wire bus.
	b, err := onewirereg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer b.Close()

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

	// Send a command 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

Examples

Constants

View Source
const (
	Q pin.Func = "OW_Q" // Data
)

Well known pin functionality.

Variables

This section is empty.

Functions

func CalcCRC

func CalcCRC(buf []byte) byte

CalcCRC calculates the 8-bit CRC across the buffer of bytes and returns it.

The Dallas Semi / Maxim Integrated 1-Wire CRC calculation is described in App Note 27: https://www.maximintegrated.com/en/app-notes/index.mvp/id/27.

func CheckCRC

func CheckCRC(buf []byte) bool

CheckCRC verifies that the last byte of the buffer contains the CRC of the previous bytes.

Types

type Address

type Address uint64

Address represents a 1-wire device address in little-endian format.

This means that the family code ends up in the lower byte, the CRC in the top byte, and the variable address part in the middle 6 bytes. E.g. a DS18B20 device, which has a family code of 0x28, might have address 0x7a00000131825228.

func Search(bus BusSearcher, alarmOnly bool) ([]Address, error)

Search performs a "search" cycle on the 1-wire bus and returns the addresses of all devices on the bus if alarmOnly is false and of all devices in alarm state if alarmOnly is true.

If an error occurs during the search the already-discovered devices are returned with the error.

For a description of the search algorithm, see Maxim's AppNote 187 https://www.maximintegrated.com/en/app-notes/index.mvp/id/187

This function is defined here so the implementation of buses that support the BusSearcher interface can call it. Applications should call Bus.Search.

type Bus

type Bus interface {
	String() string
	// Tx performs a bus transaction, sending and receiving bytes, and
	// ending by pulling the bus high either weakly or strongly depending
	// on the value of power.
	//
	// A strong pull-up is typically required to power temperature conversion or
	// EEPROM writes.
	Tx(w, r []byte, power Pullup) error

	// Search performs a "search" cycle on the 1-wire bus and returns the
	// addresses of all devices on the bus if alarmOnly is false and of all
	// devices in alarm state if alarmOnly is true.
	//
	// If an error occurs during the search the already-discovered devices are
	// returned with the error.
	//
	// Bus.Search may be implemented using onewire.Search if the bus implements
	// the BusSearcher interface or it may have a custom implementation, for
	// example a Linux sysfs implementation should return the list of devices
	// already discovered by the driver.
	Search(alarmOnly bool) ([]Address, error)
}

Bus defines the function a concrete driver for a 1-wire bus must implement.

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

type BusCloser

type BusCloser interface {
	Close() error
	Bus
}

BusCloser is a 1-wire bus that can be closed.

It is expected that an implementer of Bus also implement BusCloser, but this is not required.

type BusError

type BusError interface {
	BusError() bool // true if a bus error was detected
}

BusError is an interface that should be implemented by errors that indicate that an error occurred on the bus, for example a CRC error or a non-responding device. These errors often indicate an electrical problem with the bus and may be worth retrying.

BusError also helps to differentiate 1-wire errors from errors accessing the 1-wire bus interface chip or circuitry, which may be located on an I²C bus or gpio pin.

type BusSearcher

type BusSearcher interface {
	Bus
	// SearchTriplet performs a single bit search triplet command on the bus,
	// waits for it to complete and returns the result.
	SearchTriplet(direction byte) (TripletResult, error)
}

BusSearcher provides the basic bus transaction necessary to search a 1-wire bus for devices. Buses that implement this interface can be searched with the Search function.

type Dev

type Dev struct {
	Bus  Bus     // the bus to which the device is connected
	Addr Address // address of the device on the bus
}

Dev is a device on a 1-wire bus.

It implements conn.Conn.

Compared to Bus it saves from repeatedly specifying the device address and implements utility functions.

func (*Dev) Duplex

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

Duplex always return conn.Half for 1-wire.

func (*Dev) String

func (d *Dev) String() string

String prints the bus name followed by the device address in parenthesis.

func (*Dev) Tx

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

Tx performs a "match ROM" command on the bus to select the device and then transmits and receives the specified bytes. It ends by leaving a weak pull-up on the bus.

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

func (*Dev) TxPower

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

TxPower performs a "match ROM" command on the bus to select the device and then transmits and receives the specified bytes. It ends by leaving a strong pull-up on the bus suitable to power devices through an EEPROM write or a temperature conversion.

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

type NoDevicesError

type NoDevicesError interface {
	NoDevices() bool // true if no presence pulse from any device has been detected
}

NoDevicesError is an interface that should be implemented by errors that indicate that no devices responded with a presence pulse after a reset.

type Pins

type Pins interface {
	// Q returns the 1-wire Q (data) pin.
	Q() gpio.PinIO
}

Pins defines the pins that a 1-wire bus interconnect is using on the host.

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

Example

Code:

package main

import (
	"fmt"
	"log"
	"periph.io/x/conn/v3/driver/driverreg"
	"periph.io/x/conn/v3/onewire"
	"periph.io/x/conn/v3/onewire/onewirereg"
)

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 onewirereg 1-wire bus registry to find the first available 1-wire bus.
	b, err := onewirereg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer b.Close()

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

type Pullup

type Pullup bool

Pullup encodes the type of pull-up used at the end of a bus transaction.

const (
	// WeakPullup ends the transaction with weak pull-up
	WeakPullup Pullup = false
	// StrongPullup end the transaction with strong pull-up to power devices
	StrongPullup Pullup = true
)

func (Pullup) String

func (p Pullup) String() string

type ShortedBusError

type ShortedBusError interface {
	IsShorted() bool // true if the bus is electrically shorted
}

ShortedBusError is an interface that should be implemented by errors that indicate that the bus is electrically shorted (Q connected to GND).

Errors that implement ShortedBusError should also implement BusError.

type TripletResult

type TripletResult struct {
	GotZero bool  // a device with a zero in the current bit position responded
	GotOne  bool  // a device with a one in the current bit position responded
	Taken   uint8 // direction taken: 0 or 1
}

TripletResult is the result of a SearchTriplet operation.

Directories

Path Synopsis
onewirereg Package onewirereg defines a registry for onewire buses present on the host.
onewiretest Package onewiretest is meant to be used to test drivers over a fake 1-wire bus.