periph: periph.io/x/periph/conn/onewire Index | Examples | Files | Directories

package onewire

import "periph.io/x/periph/conn/onewire"

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/periph/conn#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

Code:

// Make sure periph is initialized.
if _, err := host.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

Package Files

crc.go func.go onewire.go search.go

Constants

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

Well known pin functionality.

func CalcCRC Uses

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 Uses

func CheckCRC(buf []byte) bool

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

type Address Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

Duplex always return conn.Half for 1-wire.

func (*Dev) String Uses

func (d *Dev) String() string

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

func (*Dev) Tx Uses

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 Uses

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 Uses

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 Uses

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.

Code:

// Make sure periph is initialized.
if _, err := host.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 Uses

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 Uses

func (p Pullup) String() string

type ShortedBusError Uses

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 Uses

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

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

Package onewire imports 5 packages (graph) and is imported by 11 packages. Updated 2019-05-23. Refresh now. Tools for package owners.