SCPI API design

What makes a good SCPI API?

If you're building a new generation of instrument, or responsible for maintenance of the SCPI protocol stack on an existing instrument family, here's some guidance!

There are a wide range of SCPI implementations across the industry. All of them can be improved in some way or other. Most of the do's (and don'ts) on this list come from real world examples of fielded instruments, however in the interests of neutrality and politeness this document will not mention specific implementations by name.

In general, you should think of SCPI not as an interactive shell or console but as an API, one which happens to be encoded in mostly human readable text. Design for machine consumption.

Performance

All other things being equal, your API should be fast. Make commands execute as quickly as possible and avoid unnecessary round trips in the API design.

Pipelining

You should support pipelined transactions (sending multiple commands which execute in sequence as the instrument is ready for them, then sending replies in sequence if necessary). This provides a huge performance boost especially over higher latency connections such as Wi-Fi or VPNs. You do not need gigabytes of receive buffer, but sending several dozen commands in quick succession (such as when replaying a saved instrument configuration to resume a previous experiment) should work.

For example:

(Client) C1:EN
(Client) C2:EN
(Client) C3:EN
(Client) C4:EN
(Client) C1:VDIV?
(Client) C2:VDIV?
(Client) C3:VDIV?
(Client) C4:VDIV?
(Scope)  0.25
(Scope)  0.50
(Scope)  0.125
(Scope)  0.05

Error handling

Consistency / orthogonality

When is SCPI not enough?