serport

README

Serport is a Go package providing access to serial ports on Linux and Windows. Its sub-package serenum helps finding serial ports on a system.

In the following example a serial port is selected and opened by serport.Choose, using 115200 baud, and obeying CTS (RTS gets activated per default). If there is more than one serial port present on a system, Choose will display a list of ports it has found and ask the user to select one. If there is only one serial port present on a system, Choose will try to use this port directly.

package main

import (
	"fmt"
	"log"

	"github.com/knieriem/serport"
)

func main() {
	port, name, err := serport.Choose("", "b115200 m1")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("# connected to", name)

	// do something with `port'
	buf := make([]byte, 4096)
	n, err := port.Read(buf)
	fmt.Println(n, err)
}

For a more complex example, see cmd/sercom.

For the syntax of control strings (for configuring baudrate, line control, ...) see uart(3).

Documentation

Overview

Package serport provides access to local serial ports on Linux and Windows.

Besides a number of SetXY() methods that allow modification of single parameters, a method named Ctl() is available that processes a string containing one or more commands as described in https://plan9.io/magic/man2html/3/uart. The following subset is supported:

	bn	Set the baud rate to n.

 	dn	Set DTR if n is non-zero; else clear it.

	kn	Send a break lasting n milliseconds.

	ln	Set number of bits per byte to n. Legal values are 5,
		6, 7, or 8.

	mn	Obey modem CTS signal if n is non-zero; else clear it.

	pc	Set parity to odd if c is o, to even if c is e; else
		set no parity.

	rn	Set RTS if n is non-zero; else clear it.

	sn	Set number of stop bits to n. Legal values are 1 or 2.

Additional commands, that haven't been present in Plan 9:

Ln	Low latency mode (available on Linux when using
	drivers that support ASYNC_LOW_LATENCY)

Dn	Delay execution for n milli-seconds

Wn	Write a byte with value n

{	Postpone execution of commands until '}' is sent.

}	Execute pending commands

When using RS-485 transceivers, additional commands can be used to configure Linux' serial_rs485 struct. The commands have been assigned to a separate namespace; an extended command syntax exists to call commands of a specific namespace:

extended_command = [ "." [ namespace_id ] "." ] command_char arg

The namespace_id is "rs485", and it may be ommitted if specified previously. Example:

.rs485.s1  ..[0 ..]1 ..a0 ..e0

RS-485 specific commands:

sn	Set logical level of RTS when sending.

an	Set logical level of RTS after sending.

[n	After adjusting RTS, delay send by n milliseconds.

]n	After sending, delay RTS adjustment by n milliseconds.

en	Receive during transmission (local echo).

tn	Enable bus termination (if supported).

See https://www.kernel.org/doc/Documentation/serial/serial-rs485.txt for details on the corresponding flags and fields of struct serial_rs485.

For remote access to serial ports, see sub-package serial9p.

Index

• func SetEncapsulatingPort(dest, p Port)
• type Device
• type LineState
• type Port
  • func Choose(expr string, inictl string) (port Port, name string, err error)
  • func Open(filename string, inictl string) (port Port, err error)

Functions

func SetEncapsulatingPort

func SetEncapsulatingPort(dest, p Port)

Types

type Device

type Device interface {
	Ctl(cmds ...string) error // accepts commands similar to Plan 9's eia#ctl

	io.ReadWriteCloser
}

type LineState

type LineState struct {
	Csr  bool
	Dsr  bool
	Ring bool
	Dcd  bool
}

type Port

type Port interface {
	SetBaudrate(int) error
	SetParity(byte) error  // odd: 'o', even: 'e', otherwise none
	SetWordlen(int) error  // 5, 6, 7, or 8
	SetStopbits(int) error // 1 or 2

	SetDtr(bool) error
	SetRts(bool) error
	SetRtsCts(bool) error // obey Cts signal, set Rts depending of internal buffer's state

	SetLowLatency(bool) error

	SendBreak(ms int) error

	Delay(ms int)

	// If the Port is remote, after calling Record() the execution of
	// commands will be delayed until Commit() is called.
	Record()
	Commit()

	Drain() error
	Purge(in, out bool)

	Device
}

func Choose

func Choose(expr string, inictl string) (port Port, name string, err error)

Choose tries to get the name of a serial port by evaluating expr. On success it opens and returns the port, otherwise it returns an error. If expr does not equal one of the values "", "?" and "!", and does not start with "~", it is directly used as a port name. In the other cases, the system is queried for available ports. If necessary, and if os.Stdin is connected to a terminal, the user is prompted to select a port from the list, or to enter a port name if the list is empty.

func Open

func Open(filename string, inictl string) (port Port, err error)

Open a local serial port. Inictl is an optional string containing one ore more commands in Ctl() style