README ¶
sers
Overview
Package sers offers serial port access for the Go programming language. It is a stated goal of this project to allow for configuration of non-traditional bit rates as the may be useful in a wide range of embedded projects.
Functionality
Primarily the library provides an implementation of the SerialPort
interface
for the supported platforms. For every serial port, you get the functionality
of an io.ReadWriteCloser
as well as methods to set and query various
parameters. Secondarily it helps you communicate with the users of your
programs through the use of mode strings that represent the data than can be
written and read with {Get,Set}Mode
.
The SetMode()
and GetMode()
methods allow setting and retrieving key
parameters such as baud rate, number of data bits, number of stop bits and the
used parity scheme. As far as the underlying platforms support it, SetMode
allows you to set arbitrary, non-traditional baud rate. The generation of
break conditions is supported through the SetBreak()
method. The behavior
of the Read()
method can be fine tuned with the SetReadParams()
method.
The library offers the concept of mode strings like 9600,7e1
or
57600,8n1,rtscts
. These can be parsed by ParseModestring
into an internal
representation that can be set through SetModeStruct
. The mode string is quite
flexible and allows omission of certain parts. Mode strings are easily read and
written by humans. This makes the user interface of programs that use serial
ports easier to create and use: programs do not need to provide a plethora
of command line switches, but can accept one string and delegate handling
to sers
.
Due to backwards compatibility there is a difference in data representation
between SetMode
and GetMode
.
Platforms
sers
has been successfully used on Mac OS X, Linux and Windows.
The following known restrictions apply.
Linux
cgo
is needed to compilesers
- Using non-traditional baud rates may not work. This depends on whether the
system headers have correct definitions for
struct termios2
. Traditional baud rates use traditional termios baud rate setting methods via defines such asB1200
etc. The author is successfully using non-traditional baud rates on Linux, though.
OS X
- Calling
GetMode
before having calledSetMode
will result in an error. cgo
is needed to compilesers
Windows
- Only
NO_HANDSHAKE
is supported.
Feature ideas
Not relying on cgo
Compilation for Linux and OS X involved use of cgo
and thus a C compiler.
This makes cross compilation harder for every user of sers
.
If all necessary definitions for serial port handling can be expressed in Go, it is conceivable to make a pure-Go version for both these operation systems.
Deadlines
Adding deadline methods, SetDeadline
as well as Set{Read,Write}Deadline
.
On termios platforms this relatively easy as we can let the runtime netpoller do the heavy lifting. On Windows I do not yet understand the most promising path to implementation.
net.Conn
support
Building on deadlines, {Local,Remote}Addr
methods would enable a SerialPort
to implement net.Conn
. This makes it easy to plug a SerialPort
into various
network protocol implementations that build on byte streams.
Regularize interface
With a working deadline implementation, the wart of SetReadParams
could be
dropped or, at least, relegated to platform specific support. {Get,Set}Mode
can be made to both take a Mode
struct. Representation of parity, stop bit
and handshake settings will be move to their own type to prevent mixups.
These changes would mean a new major version as they imply modifications that are not backwards compatible.
Release History
v1.1.0
- add
GetMode()
toSerialPort
- add modestrings,
ParseModestring
- add
Mode
struct - add a more detailed
README.md
v1.0.2
- termios platofrms: make
Close()
unblock readers
v1.0.1
- use our own definition of
struct termios2
as the headers on a number of linux distributions are wrong. - add
verification/setbaudrate
v1.0.0
sers
appears in the primordial soup.
Documentation ¶
Overview ¶
Package sers offers serial port access. It is a stated goal of this package to allow for non-standard bit rates as the may be useful in a wide range of embedded projects.
Example ¶
This program opens a serial port, configurable by changing portname below and configures it for 57600 baud, 8 data bits, no parity bit, 1 stop bit, no handshaking. It then reads up to 128 bytes from the serial port, with a timeout of 1 second and prints the received bytes to stdout.
Output:
Index ¶
Examples ¶
Constants ¶
const ( N = 0 // no parity E = 1 // even parity O = 2 // odd parity )
const ( NO_HANDSHAKE = 0 RTSCTS_HANDSHAKE = 1 )
Variables ¶
This section is empty.
Functions ¶
func SetModeStruct ¶ added in v1.1.0
func SetModeStruct(sp SerialPort, mode Mode) error
Types ¶
type Mode ¶ added in v1.1.0
func ParseModestring ¶ added in v1.1.0
Parses a modestring like "115200,8n1,rtscts" into a struct Mode. The format is baudrate,framestring,handshake. Either the handshake part or both the framestring and handshake parts can be omitted. For the omitted parts, defaults of 8 data bits, no parity, 1 stop bit and no handshaking will be filled in. The framestring consists of a sequence databits, parity, stopbits. Any or all of the three components can be left out. Non-specified parts will take the default values mentioned before.
Valid choices for databits are [5, 6, 7, 8], for parity it is [n, o, e] and for stopbits it's [1, 2]. Valid choices for the handshake parts are "", "none" and "rtscts". The function is not case sensitive.
A couple of examples:
60000 - 60000 baud, 8 data bits, no parity, 1 stopbit, no handshake 115200,8e1 - 115200 baud, 8 data bits, even parity, 1 stopbit, no handshake 57600,8o1,rtscts - 57600 baud, 8 data bits, odd parity, 1 stopbit, rts/cts handshake 19200,72 - 19200 baud, 7 data bits, no parity, 2 stop bits, no handshake 9600,2,rtscts - 9600 baud, 8 data bits, no parity, 2 stop bits, rts/cts handshake
type ParameterError ¶
func (*ParameterError) Error ¶
func (pe *ParameterError) Error() string
type SerialPort ¶
type SerialPort interface { io.Reader io.Writer io.Closer // SetMode sets the frame format and handshaking configuration. // baudrate may be freely chosen, the driver is allowed to reject // unachievable baud rates. databits may be any number of data bits // supported by the driver. parity is one of (N|O|E) for none, odd // or even parity. handshake is either NO_HANDSHAKE or // RTSCTS_HANDSHAKE. // // Known bug on Windows: Only NO_HANDSHAKE is supported. SetMode(baudrate, databits, parity, stopbits, handshake int) error // GetMode retrieves the current mode settings. // // Known bug on OS X: GetMode only works after SetMode has been called // before. If not, it returns an error. GetMode() (Mode, error) // SetReadParams sets the minimum number of bytes to read and a read // timeout in seconds. These parameters roughly correspond to the // UNIX termios concepts of VMIN and VTIME. SetReadParams(minread int, timeout float64) error // SetBreak turns on the generation of a break condition if on == true, // otherwise it clear the break condition. SetBreak(on bool) error }
Serialport represents a serial port and offers configuration of baud rate, frame format, handshaking and read paramters as well as setting and clearing break conditions.
func Open ¶
func Open(fn string) (SerialPort, error)
func TakeOver ¶
func TakeOver(f *os.File) (SerialPort, error)
TakeOver accepts an open *os.File and returns a SerialPort representing the open file.
Attention: This calls the .Fd() method of the *os.File and thus renders the deadline functionality unusable. Furthermore blocked readers may remain stuck after a Close() if no data arrives.
type StringError ¶
type StringError string
func (StringError) Error ¶
func (se StringError) Error() string