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
Output:

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
                                  Output:
                                  
                                  

                                  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
                                        Package onewirereg defines a registry for onewire buses present on the host.
                                        Package onewirereg defines a registry for onewire buses present on the host.
                                        Package onewiretest is meant to be used to test drivers over a fake 1-wire bus.
                                        Package onewiretest is meant to be used to test drivers over a fake 1-wire bus.