Crate scpi

This crate attempts to implement the IEE488.2 / SCPI protocol commonly used by measurement instruments and tools.

• SCPI-1999
• IEEE 488.2

It does not require the std library (ie it’s no_std compatible) or a system allocator (useful for embedded).

Scope

The crate does not support any transport layer, it only reads ascii-strings ([u8]) and writes ascii responses.

It does not implement any higher level functions/error handling other than SCPI parsing and response generation. See scpi-contrib for higher level abstractions.

Using this crate

Add scpi to your dependencies:

[dependencies]
scpi = "1.0"

Features

Common features

• alloc (enabled by default) — Use alloc

• arrayvec — Use arrayvec

• std — Use std (overrides alloc)

• compact — Enable compact feature in lexical-core

Units of measurements

Use uom for automatic conversion of unit suffixes.

• unit-electric-potential (enabled by default) — Electric potential (Voltage)

• unit-electric-current (enabled by default) — Electric current

• unit-electrical-conductance (enabled by default) — Electric conductance (inverse resistance)

• unit-electrical-resistance (enabled by default) — Electric resistance

• unit-electric-charge (enabled by default) — Electric charge

• unit-capacitance (enabled by default) — Electric capacitance

• unit-inductance (enabled by default) — Electric inductance

• unit-energy (enabled by default) — Energy

• unit-power (enabled by default) — Power

• unit-angle (enabled by default) — Angle

• unit-ratio (enabled by default) — Ratio / percentage / unitless

• unit-thermodynamic-temperature (enabled by default) — Temperature

• unit-time (enabled by default) — Time

• unit-frequency (enabled by default) — Frequency

(See rustdoc/docs.rs for available features)

Getting started

Look at the example for how to create a tree and run commands.

Here’s a good resource general SCPI style and good practices: Keysight SCPI Training slides

Character coding

SCPI is strictly ASCII and will throw a error InvalidCharacter if any non-ascii (>127) characters are encountered (Exception: Arbitrary data blocks).

String parameters and reponse data should use byte-slices (&[u8]) with valid ASCII data.

The str type can be decoded from either a string parameter or arbitrary block and will automatically be checked for UTF8 encoding. When used as response data a str will always return an arbitrary block.

Error handling

The Node::run(...) function aborts execution and returns on the first error it encounters.

User commands will often use functions which may return an error, these should mostly be propagated down to the parser by rusts ? operator.

Limitations and differences

• Overlapping commands are not supported, Github issue.

Contribution

Contributions are welcome.

Project organisation:

• scpi - Core parser crate
• scpi-contrib - Mandatory command implementations and higher level abstractions
• scpi-derive - Macro derive library, manly used to generate enum type parameters (see option::ScpiEnum).

Modules

• error
  This module contains standard SCPI errors in the form of the Error enum.
• option
  Support for SCPI style enums.
• parser
  SCPI Parser and response formatter
• prelude
  Prelude containing the most useful stuff
• tree
  A SCPI command tree consisting of command nodes and handlers.
• units
  Re-export supported uom types if enabled

Macros

• Branch
  A utility to create a Node::Branch.
• Leaf
  A utility to create a Node::Leaf.
• Root
  A utility to create the root Node of a command tree.
• cmd_both
  Marks the command as both query and event by creating a stub for Command::meta.
• cmd_nquery
  Marks the command as not queryable by creating a stub for Command::meta.
• cmd_qonly
  Marks the command as query only by creating a stub for Command::meta.

Structs

• Context
  Context in which to execute a message.

Traits

• Device
  A basic device capable of executing commands and not much else