asrl

README

asrl

Go-based implementation of an Asynchronous Serial (ASRL) interface for Interchangeable Virtual Instrument (IVI) drivers.

Overview

The asrl package enables controlling test equipment (e.g., oscilloscopes, function generators, multimeters, etc.) over serial port. While this package can be used by itself to send Standard Commands for Programmable Instruments (SCPI) commands to a piece of test equipment, it also serves to provide an Instrument interface for both the ivi and visa packages. The ivi package provides standardized APIs for programming test instruments following the Interchangeable Virtual Instrument (IVI) standard.

Usage

dev, err := asrl.NewDevice("ASRL::/dev/tty.usbserial-PX8X3YR6::9600::8N2::INSTR")
if err != nil {
    log.Fatal(err)
}
defer dev.Close()

ctx := context.Background()

// Query the instrument identification.
idn, err := dev.Query(ctx, "*IDN?")
if err != nil {
    log.Fatal(err)
}
fmt.Println(idn)

// Send a SCPI command.
if err := dev.Command(ctx, "OUTP ON"); err != nil {
    log.Fatal(err)
}

Documentation

Documentation can be found at https://pkg.go.dev/github.com/gotmc/asrl.

Contributing

Contributions are welcome! To contribute please:

1. Fork the repository
2. Create a feature branch
3. Code
4. Submit a pull request

Development Dependencies

• just - task runner that replaces GNU Make

Testing

Prior to submitting a pull request, please run:

$ just check
$ just lint

To update and view the test coverage report:

$ just cover

License

asrl is released under the MIT license. Please see the LICENSE.txt file for more information.

Documentation

Overview

Package asrl provides an Asynchronous Serial (ASRL) interface for controlling test equipment via serial ports using SCPI commands. It implements the VISA ASRL resource string format and serves as an instrument driver for the ivi and visa packages.

This package is part of the gotmc ecosystem. The visa package (github.com/gotmc/visa) defines a common interface for instrument communication across different transports (GPIB, USB, TCP/IP, serial). The asrl package provides the serial transport implementation. The ivi package (github.com/gotmc/ivi) builds on top of visa to provide standardized, instrument-class-specific APIs following the IVI Foundation specifications.

Devices are addressed using VISA resource strings of the form:

ASRL::<port>::<baud>::<dataflow>::INSTR

For example:

ASRL::/dev/tty.usbserial-PX484GRU::9600::8N2::INSTR

Supported dataflow values are 8N1 (default), 8N2, 7E2, 7E1, and 7O1.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/gotmc/asrl"
)

func main() {
	ctx := context.Background()

	// Open a serial device using a VISA resource string.
	dev, err := asrl.NewDevice(ctx, "ASRL::/dev/tty.usbserial-PX484GRU::9600::8N2::INSTR")
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = dev.Close() }()

	// Query the instrument identification.
	idn, err := dev.Query(ctx, "*IDN?")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(idn)

	// Send a SCPI command.
	if err := dev.Command(ctx, "OUTP ON"); err != nil {
		log.Fatal(err)
	}
}

Example (WithOptions)

package main

import (
	"context"
	"log"

	"github.com/gotmc/asrl"
)

func main() {
	ctx := context.Background()

	// Open a device with functional options.
	dev, err := asrl.NewDevice(ctx,
		"ASRL::/dev/tty.usbserial-PX8X3YR6::9600::8N2::INSTR",
		asrl.WithHWHandshaking(true),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() { _ = dev.Close() }()

	// With hardware handshaking enabled, Command polls DSR before writing.
	if err := dev.Command(ctx, "SYST:REM"); err != nil {
		log.Fatal(err)
	}
}

Index

• Variables
• type Device
  • func NewDevice(ctx context.Context, address string, opts ...DeviceOption) (*Device, error)
  • func (d *Device) Close() error
  • func (d *Device) Command(ctx context.Context, cmd string, a ...any) error
  • func (d *Device) Query(ctx context.Context, cmd string) (string, error)
  • func (d *Device) Read(p []byte) (n int, err error)
  • func (d *Device) ReadContext(ctx context.Context, p []byte) (int, error)
  • func (d *Device) Write(p []byte) (n int, err error)
  • func (d *Device) WriteContext(ctx context.Context, p []byte) (int, error)
  • func (d *Device) WriteString(s string) (n int, err error)
  • func (d *Device) WriteStringContext(ctx context.Context, s string) (int, error)
• type DeviceOption
  • func WithDelayTime(t time.Duration) DeviceOption
  • func WithEndMark(b byte) DeviceOption
  • func WithHWHandshaking(enabled bool) DeviceOption
  • func WithReadTimeout(t time.Duration) DeviceOption
• type VisaResource
  • func NewVisaResource(resourceString string) (*VisaResource, error)
  • func (v *VisaResource) Address() string
  • func (v *VisaResource) Baud() int
  • func (v *VisaResource) DataBits() int
  • func (v *VisaResource) InterfaceType() string
  • func (v *VisaResource) Parity() serial.Parity
  • func (v *VisaResource) ResourceClass() string
  • func (v *VisaResource) StopBits() serial.StopBits
  • func (v *VisaResource) String() string

Examples

• Package
• Package (WithOptions)

Variables

var (
	ErrInvalidResource      = errors.New("visa: invalid VISA resource string")
	ErrInvalidInterfaceType = errors.New("visa: interface type was not ASRL")
	ErrInvalidResourceClass = errors.New("visa: resource class was not INSTR")
	ErrInvalidBaud          = errors.New("visa: invalid baud")
	ErrUnsupportedDataflow  = errors.New("visa: unsupported dataflow")
)

Sentinel errors returned by NewVisaResource.

var ErrDSRNotReady = errors.New("asrl: DSR not ready")

ErrDSRNotReady is returned when the Data Set Ready signal is not asserted within the ReadTimeout period.

Types

type Device

type Device struct {
	EndMark       byte
	HWHandshaking bool
	DelayTime     time.Duration
	ReadTimeout   time.Duration
	// contains filtered or unexported fields
}

Device models a serial device and implements the ivi.Driver interface.

func NewDevice

func NewDevice(ctx context.Context, address string, opts ...DeviceOption) (*Device, error)

NewDevice opens a serial Device using the given VISA address resource string. The context is checked before opening the serial port. Optional DeviceOption values can be provided to override the default settings for EndMark, HWHandshaking, DelayTime, and ReadTimeout.

func (*Device) Close

func (d *Device) Close() error

Close closes the underlying serial port.

func (*Device) Command

func (d *Device) Command(ctx context.Context, cmd string, a ...any) error

Command sends a SCPI/ASCII command to the serial port. The command can be optionally formatted according to a format specifier. An endmark character, such as newline, is automatically added to the end of the string.

func (*Device) Query

func (d *Device) Query(ctx context.Context, cmd string) (string, error)

Query writes the given SCPI/ASCII command to the serial port and returns the response string. The device's endmark character (newline by default) is automatically added to the query command. The string returned is not stripped of any whitespace. The context is used for cancellation; if the context is canceled while waiting for a response, Query returns the context error.

func (*Device) Read

func (d *Device) Read(p []byte) (n int, err error)

Read reads from the serial port into the given byte slice.

func (*Device) ReadContext

func (d *Device) ReadContext(ctx context.Context, p []byte) (int, error)

ReadContext reads from the serial port into the given byte slice with context support. If the context is canceled before the read completes, ReadContext sets a short timeout to unblock the read, waits for the goroutine to finish, resets the reader, and returns the context error.

func (*Device) Write

func (d *Device) Write(p []byte) (n int, err error)

Write writes the given data to the serial port.

func (*Device) WriteContext

func (d *Device) WriteContext(ctx context.Context, p []byte) (int, error)

WriteContext writes the given data to the serial port with context support. If the context is already canceled before the write begins, WriteContext returns the context error. Serial writes are typically non-blocking, so no goroutine-based cancellation is needed.

func (*Device) WriteString

func (d *Device) WriteString(s string) (n int, err error)

WriteString writes a string to the serial port. An endmark character, such as a newline, is not automatically added to the end of the string.

func (*Device) WriteStringContext

func (d *Device) WriteStringContext(ctx context.Context, s string) (int, error)

WriteStringContext writes a string to the serial port with context support. An endmark character, such as a newline, is not automatically added to the end of the string.

type DeviceOption

type DeviceOption func(*Device)

DeviceOption is a functional option for configuring a Device.

func WithDelayTime

func WithDelayTime(t time.Duration) DeviceOption

WithDelayTime sets the delay between serial operations.

func WithEndMark

func WithEndMark(b byte) DeviceOption

WithEndMark sets the end-of-message byte used by Command and Query.

func WithHWHandshaking

func WithHWHandshaking(enabled bool) DeviceOption

WithHWHandshaking enables or disables hardware handshaking (DSR polling).

func WithReadTimeout

func WithReadTimeout(t time.Duration) DeviceOption

WithReadTimeout sets the read timeout on the serial port.

type VisaResource

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

VisaResource represents a VISA enabled piece of test equipment.

func NewVisaResource

func NewVisaResource(resourceString string) (*VisaResource, error)

NewVisaResource creates a new VisaResource using the given VISA resourceString. If the dataflow isn't provided as part of the VISA resource string, the dataflow will default to 8N1.

func (*VisaResource) Address

func (v *VisaResource) Address() string

Address returns the serial port address.

func (*VisaResource) Baud

func (v *VisaResource) Baud() int

Baud returns the baud rate.

func (*VisaResource) DataBits

func (v *VisaResource) DataBits() int

DataBits returns the number of data bits.

func (*VisaResource) InterfaceType

func (v *VisaResource) InterfaceType() string

InterfaceType returns the VISA interface type (e.g., "ASRL").

func (*VisaResource) Parity

func (v *VisaResource) Parity() serial.Parity

Parity returns the parity setting.

func (*VisaResource) ResourceClass

func (v *VisaResource) ResourceClass() string

ResourceClass returns the VISA resource class (e.g., "INSTR").

func (*VisaResource) StopBits

func (v *VisaResource) StopBits() serial.StopBits

StopBits returns the stop bits setting.

func (*VisaResource) String

func (v *VisaResource) String() string

String returns the original VISA resource string.