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
Example ¶
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)
}
Output:
Index ¶
Examples ¶
Constants ¶
const (
Q pin.Func = "OW_Q" // Data
)
Well known pin functionality.
Variables ¶
This section is empty.
Functions ¶
func CalcCRC ¶
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.
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 ¶
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 ¶
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) Tx ¶
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 ¶
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 ¶
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 ¶
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())
}
}
Output:
type Pullup ¶
type Pullup bool
Pullup encodes the type of pull-up used at the end of a bus transaction.
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.
Source Files
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. |