inherent.go

// Copyright (c) 2017-2026 The ivi developers. All rights reserved.
// Project site: https://github.com/gotmc/ivi
// Use of this source code is governed by a MIT-style license that
// can be found in the LICENSE.txt file for the project.

package ivi

import (
	"context"
	"fmt"
	"slices"
	"strings"
	"time"

	"github.com/gotmc/query"
)

type idPart int

const (
	mfrID idPart = iota
	modelID
	snID
	fwrID
)

// Inherent provides the inherent capabilities for all IVI instruments.
type Inherent struct {
	inst             Transport
	timeout          time.Duration
	manufacturer     string
	model            string
	serialNumber     string
	firmwareRevision string
	InherentBase
}

// InherentBase provides the exported properties for the inherent capabilities
// of all IVI instruments.
type InherentBase struct {
	ClassSpecRevision         string
	IDNString                 string
	LocalControlCommand       string // SCPI command to return to local control (default: "SYST:LOC")
	GroupCapabilities         []string
	SupportedInstrumentModels []string
	SupportedBusInterfaces    []string
	ClassSpecMajorVersion     int
	ClassSpecMinorVersion     int
	ResetDelay                time.Duration
	ClearDelay                time.Duration
	ReturnToLocal             bool // Whether to return to local control on Close/Disable
}

// NewInherent creates a new Inherent struct using the given Transport
// interface, InherentBase struct, and timeout. If timeout is zero,
// DefaultTimeout is used. Note: callers should explicitly set ReturnToLocal in
// InherentBase (default Go zero value is false).
func NewInherent(inst Transport, base InherentBase, timeout time.Duration) Inherent {
	if timeout == 0 {
		timeout = DefaultTimeout
	}

	return Inherent{
		inst:         inst,
		timeout:      timeout,
		InherentBase: base,
	}
}

// Timeout returns the timeout used for instrument I/O operations.
func (inherent *Inherent) Timeout() time.Duration {
	return inherent.timeout
}

// newContext creates a context with the driver's configured timeout.
func (inherent *Inherent) newContext() (context.Context, context.CancelFunc) {
	return context.WithTimeout(context.Background(), inherent.timeout)
}

// CheckID queries the instrument for its identification string (*IDN?) and
// verifies that the instrument model is in the list of SupportedInstrumentModels.
// On success, IDNString is populated with the full *IDN? response, the four
// identification fields (manufacturer, model, serial number, firmware
// revision) are cached on the receiver, and the model string is returned.
// CheckID implements the IdQuery behavior described in Section 6.16 of
// IVI-3.2: Inherent Capabilities Specification.
//
// Once CheckID succeeds, the four identification accessors
// ([Inherent.FirmwareRevision], [Inherent.InstrumentManufacturer],
// [Inherent.InstrumentModel], [Inherent.InstrumentSerialNumber]) return the
// cached values without issuing additional SCPI.
func (inherent *Inherent) CheckID() (string, error) {
	ctx, cancel := inherent.newContext()
	defer cancel()

	idn, err := query.String(ctx, inherent.inst, "*IDN?")
	if err != nil {
		return "", fmt.Errorf("error querying instrument identity: %w", err)
	}

	inherent.IDNString = strings.TrimSpace(idn)

	if err := inherent.cacheIdentification(inherent.IDNString); err != nil {
		return "", err
	}

	if !slices.Contains(inherent.SupportedInstrumentModels, inherent.model) {
		return inherent.model, fmt.Errorf(
			"%w: %q is not supported by this driver",
			ErrUnsupportedModel,
			inherent.model,
		)
	}

	return inherent.model, nil
}

// FirmwareRevision returns the instrument firmware revision. It returns the
// value cached by [Inherent.CheckID]; if the cache is empty (the
// [WithoutIDQuery] path where construction-time *IDN? failed), it issues a
// live *IDN? query and caches the result. FirmwareRevision is the getter for
// the read-only inherent attribute Instrument Firmware Revision described in
// Section 5.18 of IVI-3.2: Inherent Capabilities Specification.
func (inherent *Inherent) FirmwareRevision() (string, error) {
	return inherent.lookupIdentification(&inherent.firmwareRevision, fwrID)
}

// InstrumentManufacturer returns the instrument manufacturer. It returns the
// value cached by [Inherent.CheckID]; if the cache is empty it issues a live
// *IDN? query and caches the result. InstrumentManufacturer is the getter for
// the read-only inherent attribute Instrument Manufacturer described in
// Section 5.19 of IVI-3.2: Inherent Capabilities Specification.
func (inherent *Inherent) InstrumentManufacturer() (string, error) {
	return inherent.lookupIdentification(&inherent.manufacturer, mfrID)
}

// InstrumentModel returns the instrument model. It returns the value cached
// by [Inherent.CheckID]; if the cache is empty it issues a live *IDN? query
// and caches the result. InstrumentModel is the getter for the read-only
// inherent attribute Instrument Model described in Section 5.20 of IVI-3.2:
// Inherent Capabilities Specification.
func (inherent *Inherent) InstrumentModel() (string, error) {
	return inherent.lookupIdentification(&inherent.model, modelID)
}

// InstrumentSerialNumber returns the instrument serial number. It returns the
// value cached by [Inherent.CheckID]; if the cache is empty it issues a live
// *IDN? query and caches the result.
func (inherent *Inherent) InstrumentSerialNumber() (string, error) {
	return inherent.lookupIdentification(&inherent.serialNumber, snID)
}

// lookupIdentification returns the cached identification field when
// populated, otherwise issues a live *IDN? query and caches the result.
func (inherent *Inherent) lookupIdentification(field *string, part idPart) (string, error) {
	if *field != "" {
		return *field, nil
	}

	value, err := inherent.queryIdentification(part)
	if err != nil {
		return "", err
	}

	*field = value

	return value, nil
}

// cacheIdentification parses the given IDN string into the four cached
// identification fields on the receiver.
func (inherent *Inherent) cacheIdentification(idn string) error {
	const numIdentificationParts = 4

	parts := strings.Split(idn, ",")

	if len(parts) != numIdentificationParts {
		return fmt.Errorf("idn string (`%s`) could not be split in four", idn)
	}

	inherent.manufacturer = strings.TrimSpace(parts[mfrID])
	inherent.model = strings.TrimSpace(parts[modelID])
	inherent.serialNumber = strings.TrimSpace(parts[snID])
	inherent.firmwareRevision = strings.TrimSpace(parts[fwrID])

	return nil
}

// Reset resets the instrument.
func (inherent *Inherent) Reset() error {
	ctx, cancel := inherent.newContext()
	defer cancel()

	if err := inherent.inst.Command(ctx, "*rst"); err != nil {
		return err
	}
	// Wait for the device to finish resetting.
	time.Sleep(inherent.ResetDelay)

	return nil
}

// Clear clears the instrument.
func (inherent *Inherent) Clear() error {
	ctx, cancel := inherent.newContext()
	defer cancel()

	if err := inherent.inst.Command(ctx, "*cls"); err != nil {
		return err
	}
	// Wait for the device to finish clearing.
	time.Sleep(inherent.ClearDelay)

	return nil
}

// Disable places the instrument in a quiescent state as quickly as possible.
// If ReturnToLocal is true, this method also returns the instrument to local
// control by sending the SYST:LOC command, allowing the front panel to regain
// control. Disable provides the method described in Section 6.4 of IVI-3.2:
// Inherent Capabilities Specification.
//
// Errors from the local control command are intentionally ignored because not
// all instruments support SYST:LOC, and a failure to return to local should
// not prevent the instrument from being closed.
func (inherent *Inherent) Disable() error {
	if !inherent.ReturnToLocal {
		return nil
	}

	ctx, cancel := inherent.newContext()
	defer cancel()

	// Best-effort return to local control so the front panel regains control.
	// Use the instrument-specific command if provided, otherwise default to
	// SYST:LOC which is the most common SCPI local control command.
	cmd := inherent.LocalControlCommand
	if cmd == "" {
		cmd = "SYST:LOC"
	}

	_ = inherent.inst.Command(ctx, cmd)

	return nil
}

func (inherent *Inherent) queryIdentification(part idPart) (string, error) {
	ctx, cancel := inherent.newContext()
	defer cancel()

	s, err := query.String(ctx, inherent.inst, "*IDN?")
	if err != nil {
		return "", err
	}

	return parseIdentification(strings.TrimSpace(s), part)
}

func parseIdentification(idn string, part idPart) (string, error) {
	const numIdentificationParts = 4

	parts := strings.Split(idn, ",")

	if len(parts) != numIdentificationParts {
		return "", fmt.Errorf("idn string (`%s`) could not be split in four", idn)
	}

	return strings.TrimSpace(parts[part]), nil
}

// SetReturnToLocal controls whether the instrument returns to local control
// when Disable() or Close() is called. Default is true.
func (inherent *Inherent) SetReturnToLocal(enabled bool) {
	inherent.ReturnToLocal = enabled
}

// IsReturnToLocal returns whether the instrument will return to local control
// when Disable() or Close() is called.
func (inherent *Inherent) IsReturnToLocal() bool {
	return inherent.ReturnToLocal
}

// Close returns the instrument to local front panel control by calling
// Disable. The underlying transport connection is not closed — that is the
// caller's responsibility since they created it.
func (inherent *Inherent) Close() error {
	return inherent.Disable()
}