serial

README

goSerialPort : Embedded Serial port Package

Package goSerialPort is Embedded focused serial port package. It helps to read, write and configure the serial port.

This project draws inspiration from

• github.com/tarm/serial
• github.com/johnlauer/goserial
• go.bug.st/serial

This project aims to provide low level API and compatibility for Windows and Linux. As time progresses other OS and architectures would be added.

This library perform read / write in Non-Blocking Manner.

By default this package uses 8 bits (byte) data format for exchange. This is typical for Embedded Applications such as UART of an MCU.

Note: Baud rates are defined as OS specifics

Currently Following Features are supported:

1. All types of BAUD rates
2. Flow Control - Hardware, Software (XON/XOFF)
3. RTS , DTR control
4. CTS , DSR, RING read back
5. Parity Control - Odd, Even, Mark, Space
6. Stop Bit Control - 1 bit and 2 bits
7. Hardware to Software Signal Inversion for all Signals RTS, CTS, DTR, DSR, RI
8. Sending Break from TX line X. ... More on the way ...

Install

go get -u github.com/boseji/goSerialPort

You can cross compile with

GOOS=windows GOARCH=386 go install github.com/boseji/goSerialPort

Specifically for Window7 on i386 or 32-bit.

Hardware Test Setup

Use a USB to UART board where all the UART standard signals are exposed.

Here is a picture explaining the Connections:

License

Copyright 2021 Abhijit Bose. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0

Documentation

Overview

Package serial is Embedded focused serial port package that allows you to read, write and configure the serial port.

This project draws inspiration from the github.com/tarm/serial package, github.com/johnlauer/goserial package and go.bug.st/serial package

Initially this project aims to provide API and compatibility for Linux. As time progresses other architectures would be added.

This library is Context based and performs read write asynchronously.

By default this package uses 8 bits (byte) data format for exchange.

Note: Baud rates are defined as OS specifics

Currently Following Features are supported:

1. All types of BAUD rates
2. Flow Control - Hardware, Software (XON/XOFF)
3. RTS , DTR control
4. CTS , DSR, RING read back
5. Parity Control - Odd, Even, Mark, Space
6. Stop Bit Control - 1 bit and 2 bits
7. Hardware to Software Signal Inversion for all Signals RTS, CTS, DTR, DSR
8. Sending Break from TX line X. ... More on the way ...

Index

• Constants
• Variables
• type Config
  • func (c *Config) String() string
• type Port
  • func OpenPort(cfg *Config) (Port, error)

Constants

const (
	// StopBits1 defines a single Stop bit sent after every data unit block
	StopBits1 byte = iota
	// StopBits15 defines a 1 and 1/2 Stop bits sent after every data unit block
	StopBits15 byte = iota // 1.5 Stop Bits
	// StopBits2 defines a 2 Stop bits sent after every data unit block
	StopBits2 byte = iota
)

Specific Stop bits type

const (
	ParityNone  byte = iota
	ParityOdd   byte = iota
	ParityEven  byte = iota
	ParityMark  byte = iota
	ParitySpace byte = iota
)

Parity Constants

const (
	// FlowNone for no flow control to be used for Serial port
	FlowNone byte = iota
	// FlowHardware for CTS / RTS base Hardware flow control to be used for Serial port
	FlowHardware byte = iota
	// FlowSoft for Software flow control to be used for Serial port
	FlowSoft byte = iota // XON / XOFF based - Not Supported
)

const DataSize byte = 8

DataSize defines the unit data size in bits used for Serial communication

Variables

var (
	// ErrNotImplemented -
	ErrNotImplemented = fmt.Errorf("not implemented yet")
	// ErrPortNotInitialized -
	ErrPortNotInitialized = fmt.Errorf("port not initialized or closed")
	// ErrNotOpen -
	ErrNotOpen = fmt.Errorf("port not open")
	// ErrAlreadyOpen -
	ErrAlreadyOpen = fmt.Errorf("port is already open")
	// ErrAccessDenied -
	ErrAccessDenied = fmt.Errorf("access denied")
)

Types

type Config

type Config struct {
	Name         string
	Baud         int
	ReadTimeout  time.Duration // Blocks the Read operation for a specified time
	Parity       byte
	StopBits     byte
	Flow         byte
	SignalInvert bool // Option to invert the RTS/CTS/DTR/DSR Read outs
}

Config stores the complete configuration of a Serial Port

func (*Config) String

func (c *Config) String() string

String is the implementation of the Stringer interface

type Port

type Port interface {
	io.ReadWriteCloser
	Rts(en bool) (err error)
	Cts() (en bool, err error)
	Dtr(en bool) (err error)
	Dsr() (en bool, err error)
	Ring() (en bool, err error)
	SetBaud(baud int) (err error)
	SignalInvert(en bool) (err error)
	SendBreak(en bool) (err error)
}

Port Type for Multi platform implementation of Serial port functionality

func OpenPort

func OpenPort(cfg *Config) (Port, error)

OpenPort is a Function to Create the Serial Port and return an Interface type enclosing the configuration