JPA-SCPI Parser - Quick Start User Guide

Quick Start User Guide

This user guide will show you just how easy it is to make your instruments talk SCPI using JPA-SCPI Parser. Full details of all these steps and more are given in the JPA-SCPI Parser User Manual.

Three Steps to SCPI...

Decide the command set that your instrument will support
Create the command specifications file-pair (use an instrument template, or create from the base template if you prefer)
Integrate calls to JPA-SCPI Parser into your code

1. Decide Your Command Set

Depending on what type of instrument you are building, you will want to support different types of SCPI commands.

SCPI divides instruments into Instrument Classes. There are 13 Instrument Classes in the current SCPI Standard, including: DC Voltmeter, AC Voltmeter, Ohm Meter, Digitizers (oscilloscopes, etc.) and Power Supplies (programmable power supplies, calibrators, etc.).

Decide which Instrument Class or Classes your instrument belongs to. More information is given in the JPA-SCPI Parser User Manual, and the SCPI Standard.

We provide templates for 10 of the most popular Instrument Classes. Each template contains all the commands that an instrument of that class must include to claim compliancy with that SCPI Instrument Class.

You may find your instrument does not belong to any SCPI Instrument Class. This is OK - the instrument will still be SCPI-compliant if it supports the base SCPI commands. We supply a Base Template containing the commands you need.

SCPI also allows you to add any commands of your own.

2. Create the Command Specifications

Once you have decided which SCPI Instrument Class(es) your instrument belongs to, and what additional commands you wish to support, it is a simple matter of defining the command specifications.

The command specifications are defined in this pair of files:

cmds.c
cmds.h

cmds.c

The cmds.c file is created from one or more of the supplied templates.

Now add your own commands to the cmds.c file.

For example, this is the command specification for a DMM (Digital Multi-Meter) to set its function to DC voltage measurement and to set the range:

[SENSe:]VOLTage:DC:RANGe {<range>}

The keyword sequence of this command is represented in cmds.c by this code:


							const char *SSpecCmdKeywords[] =

							{

							/*                              Index

							                                -----          */

							   :

							"[SENSe:]VOLTage:DC:RANGe",  /*   15           */

							   :

							};

Note the similarity between the specification and the code - this is what makes JPA-SCPI Parser so easy to use.

The type, number and order of parameters that are used with this command are then added to cmds.c. In this example the parameter is a required (not optional) numerical value without units:


							const struct strSpecCommand sSpecCommand[] =

							{

							  /*    Param 1                 Param 2                    Index

							        -------                 -------                    -----       */

							          :

							  {{   { REQ  NUM  sNoUnits  },{ NOP             } }},  /*   15        */

							          :

							};

Other types of parameter are just as easy to specify. You can also specify choices of parameter such as {<range>|MINimum|MAXimum}. Again a close correspondence between the command specification and cmds.c makes the process easy.

Other features you can specify include:

Default parameters, such as {MINimum|MAXimum|DEFault}, where DEFault is returned if no parameter is entered
Optional parameters, such as [<resolution>]

View an example cmds.c file

cmds.h

The small cmds.h file contains the Unit Types supported by your parameters, e.g. volts, amps, etc. It also contains constants such as the maximum number of parameters allowed.

Any platform-specific information required by JPA-SCPI Parser (e.g. maximum value representable by an unsigned long variable, etc.) is also kept in cmds.h.

View an example cmds.h file

3. Integrate JPA-SCPI Parser into Your Code

The final step is to integrate JPA-SCPI Parser into your code. The easy-to-use functions of JPA-SCPI Parser make this simple.

Set your compiler to include the scpi.c and cmds.c files in your build.
#include "scpi.h" in any of your code modules that call JPA-SCPI Parser functions.
Modify your code to carry out the following steps after a termination character/signal has been received on the comm port, indicating the end of the received command line string:
1. Pass a pointer to the input command line string to the SCPI_Parse() function. JPA-SCPI Parser will parse the first command in the command line.
2. Check the function's return code. It will indicate one of these results:
  1. The input command was recognized as a valid command
  2. The input command was not recognized (returned error code indicates the exact reason)
  3. There are no (more) commands to parse in the input command line
3. If the command is valid, use the JPA-SCPI Parser access functions to convert the user parameters into useable variables - SCPI_ParamType(), SCPI_ParamUnits(), SCPI_ParamToDouble(), SCPI_ParamToLong(), SCPI_ParamToString(), etc.
4. Validate the parameters and if ok, carry out whatever actions are necessary for that command.
5. If the command was not valid, handle the error as required by your instrument.
6. SCPI_Parse() also returns a pointer to the start of the next command in the input command line. Return to step 1, using this new pointer. Stop parsing the command line when SCPI_Parse() indicates there are no more commands to parse.

Sample code and comprehensive instructions are included with JPA-SCPI Parser to take you through all the steps needed to create your SCPI parser.

Read on