serial

Documentation

Overview

Goserial is a simple go package to allow you to read and write from the serial port as a stream of bytes.

It aims to have the same API on all platforms, including windows. As an added bonus, the windows package does not use cgo, so you can cross compile for windows from another platform. Unfortunately goinstall does not currently let you cross compile so you will have to do it manually:

GOOS=windows make clean install

Currently there is very little in the way of configurability. You can set the baud rate. Then you can Read(), Write(), or Close() the connection. Read() will block until at least one byte is returned. Write is the same. There is currently no exposed way to set the timeouts, though patches are welcome.

Currently all ports are opened with 8 data bits, 1 stop bit, no parity, no hardware flow control, and no software flow control. This works fine for many real devices and many faux serial devices including usb-to-serial converters and bluetooth serial ports.

You may Read() and Write() simulantiously on the same connection (from different goroutines).

Example usage:

package main

import (
      "github.com/tarm/serial"
      "log"
)

func main() {
      c := &serial.Config{Name: "COM5", Baud: 115200}
      s, err := serial.OpenPort(c)
      if err != nil {
              log.Fatal(err)
      }

      n, err := s.Write([]byte("test"))
      if err != nil {
              log.Fatal(err)
      }

      buf := make([]byte, 128)
      n, err = s.Read(buf)
      if err != nil {
              log.Fatal(err)
      }
      log.Print("%q", buf[:n])
}

Index

• Constants
• Variables
• func AddrFromConfig(cfg *Config) string
• func NewConn(port io.ReadWriteCloser, addr net.Addr, cancel context.CancelFunc) net.Conn
• func OpenPort(c *Config) (io.ReadWriteCloser, error)
• type Addr
  • func (a *Addr) Network() string
  • func (a *Addr) String() string
• type Config
  • func ParseConfigFromAddr(addr string) *Config
• type Parity
• type Port
  • func (p *Port) Close() (err error)
  • func (p *Port) Flush() error
  • func (p *Port) Read(b []byte) (n int, err error)
  • func (p *Port) Write(b []byte) (n int, err error)
• type StopBits

Constants

const (
	DefaultPort     = "COM1"
	DefaultBaudRate = 9600
)

const DefaultSize = 8 // Default value for Config.Size

Variables

var ErrBadParity error = errors.New("unsupported parity setting")

ErrBadParity is returned if the parity is not supported.

var ErrBadSize error = errors.New("unsupported serial data size")

ErrBadSize is returned if Size is not supported.

var ErrBadStopBits error = errors.New("unsupported stop bit setting")

ErrBadStopBits is returned if the specified StopBits setting not supported.

Functions

func AddrFromConfig

func AddrFromConfig(cfg *Config) string

func NewConn

func NewConn(port io.ReadWriteCloser, addr net.Addr, cancel context.CancelFunc) net.Conn

func OpenPort

func OpenPort(c *Config) (io.ReadWriteCloser, error)

OpenPort opens a serial port with the specified configuration

Types

type Addr

type Addr struct {
	Port string
}

func (*Addr) Network

func (a *Addr) Network() string

func (*Addr) String

func (a *Addr) String() string

type Config

type Config struct {
	Name        string
	Baud        int
	ReadTimeout time.Duration // Total timeout

	// Size is the number of data bits. If 0, DefaultSize is used.
	Size byte

	// Parity is the bit to use and defaults to ParityNone (no parity bit).
	Parity Parity

	// Number of stop bits to use. Default is 1 (1 stop bit).
	StopBits StopBits
}

Config contains the information needed to open a serial port.

Currently few options are implemented, but more may be added in the future (patches welcome), so it is recommended that you create a new config addressing the fields by name rather than by order.

For example:

c0 := &serial.Config{Name: "COM45", Baud: 115200, ReadTimeout: time.Millisecond * 500}

or

c1 := new(serial.Config)
c1.Name = "/dev/tty.usbserial"
c1.Baud = 115200
c1.ReadTimeout = time.Millisecond * 500

func ParseConfigFromAddr

func ParseConfigFromAddr(addr string) *Config

COM1,9600,odd

type Parity

type Parity byte

const (
	ParityNone  Parity = 'N'
	ParityOdd   Parity = 'O'
	ParityEven  Parity = 'E'
	ParityMark  Parity = 'M' // parity bit is always 1
	ParitySpace Parity = 'S' // parity bit is always 0
)

type Port

type Port struct {
	// contains filtered or unexported fields
}

func (*Port) Close

func (p *Port) Close() (err error)

func (*Port) Flush

func (p *Port) Flush() error

Discards data written to the port but not transmitted, or data received but not read

func (*Port) Read

func (p *Port) Read(b []byte) (n int, err error)

func (*Port) Write

func (p *Port) Write(b []byte) (n int, err error)

type StopBits

type StopBits byte

const (
	Stop1     StopBits = 1
	Stop1Half StopBits = 15
	Stop2     StopBits = 2
)