uart

Documentation

Overview

Package uart defines the UART 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 uart, 'Bus' is not exposed, as the protocol is primarily point-to-point.

Use Port.Connect() converts the uninitialized Port into a Conn.

TODO(maruel): The Port -> Conn dance is unusual for UART users and feels unnatural.

TODO(maruel): UART users talks in term of bauds, not hertz.

TODO(maruel): The LimitSpeed() function feels weird, as generally it's not the device driver that gets to decide the speed (?) Well it 'depends'.

There's a great implementation at https://github.com/albenik/go-serial but it uses cgo a lot. Maybe making an adaptor and moving this into extra is the best choice here?

Index

• type Flow
  • func MakeXOnXOffFlow(xon, xoff byte) Flow
  • func (f Flow) String() string
• type Parity
• type Pins
• type Port
• type PortCloser
• type Stop

Examples

• Pins

Types

type Flow

type Flow uint32

Flow determines the data flow to use, if any.

const (
	// NoFlow specifies that no flow control is used.
	NoFlow Flow = 0x10000
	// XOnXOff specifies XOn/XOff flow control, also called Software flow control.
	//
	// See https://en.wikipedia.org/wiki/Software_flow_control for more
	// information.
	XOnXOff Flow = 0x20000
	// RTSCTS specifies RTS/CTS flow contro. This uses RTS and CTS lines for flow
	// control, also called Hardware flow control. This enables more reliable
	// communication. The lines are driven Low when they are ready to receive
	// more data.
	RTSCTS Flow = 0x40000
)

func MakeXOnXOffFlow

func MakeXOnXOffFlow(xon, xoff byte) Flow

MakeXOnXOffFlow returns an initialized Flow to enable software based flow control.

func (Flow) String

func (f Flow) String() string

type Parity

type Parity byte

Parity determines the parity bit when transmitting, if any.

const (
	// NoParity means no parity bit.
	NoParity Parity = 'N'
	// Odd means 1 when sum is odd.
	Odd Parity = 'O'
	// Even means 1 when sum is even.
	Even Parity = 'E'
	// Mark means always 1.
	Mark Parity = 'M'
	// Space means always 0.
	Space Parity = 'S'
)

type Pins

type Pins interface {
	// RX returns the receive pin.
	RX() gpio.PinIn
	// TX returns the transmit pin.
	TX() gpio.PinOut
	// RTS returns the request to send pin, if present.
	RTS() gpio.PinOut
	// CTS returns the clear to send pin, if present.
	CTS() gpio.PinIn
}

Pins defines the pins that an UART bus interconnect is using on the host.

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

Example

package main

import (
	"fmt"
	"log"

	"periph.io/x/periph/experimental/conn/uart"
	"periph.io/x/periph/experimental/conn/uart/uartreg"
	"periph.io/x/periph/host"
)

func main() {
	// Make sure periph is initialized.
	if _, err := host.Init(); err != nil {
		log.Fatal(err)
	}

	// Use uartreg UART port registry to find the first available UART port.
	p, err := uartreg.Open("")
	if err != nil {
		log.Fatal(err)
	}
	defer p.Close()

	// Prints out the gpio pin used.
	if p, ok := p.(uart.Pins); ok {
		fmt.Printf("  RX : %s", p.RX())
		fmt.Printf("  TX : %s", p.TX())
		fmt.Printf("  RTS: %s", p.RTS())
		fmt.Printf("  CTS: %s", p.CTS())
	}
}

type Port

type Port interface {
	String() string
	// Connect sets the communication parameters of the connection for use by a
	// device.
	//
	// The device driver must call this function exactly once.
	//
	// f must specify the maximum rated speed by the device's spec. For example
	// if a device is known to not work at over 115200 bauds, it should specify
	// 115200Hz.
	//
	// The lowest speed between the port speed and the device speed is selected.
	//
	// There's rarely a reason to use anything else than One stop bit and 8 bits
	// per character.
	Connect(f physic.Frequency, stopBit Stop, parity Parity, flow Flow, bits int) (conn.Conn, error)
}

Port is the interface to be provided to device drivers.

The device driver, that is the driver for the peripheral connected over this port, calls Connect() to retrieve a configured connection as Conn.

type PortCloser

type PortCloser interface {
	io.Closer
	Port
	// LimitSpeed sets the maximum port speed.
	//
	// It lets an application use a device at a lower speed than the maximum
	// speed as rated by the device driver. This is useful for example when the
	// wires are long or the connection is of poor quality, and you want to try
	// to run at lower speed like 19200 bauds.
	//
	// This function can be called multiple times and resets the previous value.
	// 0 is not a valid value for f. The lowest speed between the port speed and
	// the device speed is selected.
	LimitSpeed(f physic.Frequency) error
}

PortCloser is a UART port that can be closed.

This interface is meant to be handled by the application.

type Stop

type Stop int8

Stop determines what stop bit to use.

const (
	// One is 1 stop bit.
	One Stop = 1
	// OneHalf is 1.5 stop bits.
	OneHalf Stop = 15
	// Two is 2 stop bits.
	Two Stop = 2
)