The ESP has two options for checking and building an EEZ project as shown on Fig. 1. and Fig. 2.

 

Fig. 1: Project checking

 

Fig. 2: Project building

 

Build option will generate IEXP zip file in the same folder where project is located (Fig. 3.) and its suffix will include IDF revision number as described in Extension definitions section.

 

Fig. 3: Generated IEXT zip file

 

Installing the new IEXT

Newly created IEXT can be immediately used in ESW module by installing it with selecting the Import Instrument Definition… option (Fig. 4.) and Import as Workbench extension (Fig. 5).

 

Fig. 4: Import IEXT option

 

Fig. 5: Import IEXT into ESW

Successfully imported IEXT will become visible in Extension manager section as shown on Fig. 6.

 

Fig. 6: Newly installed IEXT in the Extension manager

Making the IEXT publicly available

The IEXT can be also made publicly available that other can use it with EEZ Studio. Other benefits in that case are better version control, network storage (i.e. GitHub repository) and easier installation when the ESW's Extension Manager Update catalog option can be used as described in Introduction.

 

The GitHub's pull request mechanism is used to make an IEXT publicly available by including it into the catalog of IEXT's that makes it accessible by the Extension Manager. A pull request for adding a new instrument extension (IEXT) should modify only ./extensions-list.txt (see IEXT repository section). The new IEXT could be hosted:

  • locally (i.e. it will became a part of repository) or
  • remotely as defined with given URL.

IMPORTANT: Please insure that your pull request include IEXT's .zip file with version suffix that is higher then the latest listed in IEXT catalog (i.e. the GitHub repository). Do not increase .zip version suffix manually, define it in project file that Build procedure can add it automatically (see Extension definitions section).

 

All locally hosted IEXT should be placed into /org/<manufacturer>/<instrument_folder>. The pull request has to be approved by EEZ team, and only files into newly added folder will be checked. The IEXT is also subject for a comprehensive inspection to ensure that it does not contain malicious code.

 

Add a comment

 

The SCPI subsystems can be imported into IEXT project using the properly formatted HTML file as described in Adding SCPI commands and queries from HTML help file. This section describes what is necessary to add into HTML help file so the ESP during import can properly detect SCPI subsystem and its commands and queries.

The HTML help file could be created in various HTML editor or general purpose text processing software that has “export to/save as HTML” feature. One of them is also LibreOffice or OpenOffice Writer which will be used in our example. Unfortunately, conversion from .odt to HTML file still does not produce accurate result. Therefore the EEZ WebPublish extension for OpenOffice extension will be used that produce more predictable HTML output.

SCPI subsystem name

All names of SCPI subsystem, commands and queries require unique bookmark at their beginning. SCPI subsystem name is usually at the beginning of the file, and in our example it is “Common command reference” (Fig. 1.).

 

Fig. 1: SCPI subsystem title

The SCPI subsystem bookmark name has to begin with _scpi_subsys_ prefix, and it is named _scpi_subsys_ieee488 in our example. To insert bookmark, use Insert … Bookmark … option that will open a new entry form as shown on Fig. 2.

 

Fig. 2: OpenOffice Writer insert bookmark

SCPI command and query name

Each SCPI command and query requires unique bookmark that begins with prefix _scpi_. and as in case of SCPI subsystem name, the text that follows will be used as command name or query. When both command and query form exists for the name of the later we can simply add 2 to make it unique. For example for *OPC and *OPC? We can use _scpi_opc and _scpi_opc2 for bookmarks name as shown in Fig. 3.

 

Fig. 3: SCPI command and query section

SCPI command parameter name and type

The ESP while importing HTML help file can also detect SCPI command parameter names and types. Recommended form to specify SCPI command parameters is a table as shown in Fig. 4. the following rules are applied here:

  • Parameter has to be enclosed with <>
  • Enclose parameter in {} brackets if it is mandatory or [] brackets if optional
  • More parameters have to be separated by comma (,)
  • Each parameter specified in command line has to be specified in separate table row with the same name and also enclosed with <>

 

Fig. 4: SCPI command parameters table

Use on of the following labels for the parameter's type (note that numeric values can be defined with any of two possible labels):

  • Integer or NR1
  • Decimal or NR2
  • Float or NR3
  • Boolean
  • Quoted string
  • Data block
  • Channel list
  • Discrete

It is also allowed to use more then one parameter type, e.g. NR1 and Discrete as in case of <fifth> parameter from example shown in Fig. 4. Use “|” character as a separation mark.

Discrete parameter's type can be also detected and its values has to be also separated with a “|” character.

The ESP will report detection of the HTML help file that contain newly defined MY:SPECial:COMMand from our example as shown in Fig. 5. Check Command option to commit its import. The newly detected command will also introduce two enumerations (used for parameter <fourth> and <fifth>) that will be also detected and reported into the separate tabs (Fig. 6.).

 

Fig. 5: Detected new SCPI command

 

Fig. 6: Detected new enumerations

When new items are detected, marked and imported, the new command and its parameters will appear in the project as shown in Fig. 7. New enumerations can be found in Enumerations section (Fig. 8).

 

Fig. 7: Imported new SCPI commands with parameter definitions

 

 

Fig. 8: Imported new enumerations

Generating a HTML file

The final step is to convert SCPI subsystem help file formatted as described above to HTML format. In our example the OpenOffice Writer with previously installed EEZ WebPublish extension will be used. Please note that extension installation require OpenOffice Writer restart. The WebPublish extension works with profiles and a HTML profile is required for conversion into HTML format. To check profile, access OpenOffice Extension Manager option (select Tools … Extension manager menu option) and select WebPublish Options (Fig. 9.).

 

Fig. 9: OpenOffice Extension manager

When e.g. default HTML profile is selected for editing (Fig. 10.) check if its parameters are as shown in Fig 11.

 

Fig. 10: WebPublish extension profiles

 

Fig. 11: WebPublish HTML profile definition

Now we can select from WebPublish toolbar HTML option, select above mentioned HTML profile (Fig. 12) and choose name for the HTML file.

 

Fig. 12: Select WebPublish conversion to HTML option

The complete above described procedure of creating SCPI subsystem help file that has to be converted into HTML format for importing into EEZ project, can be accomplished with e.g. MS Word. As a final step a Save as option to HTML format has to be selected as shown on Fig. 13.

 

Fig. 13: MS Word Save as HTML option

 

Add a comment

Shortcuts can simplify execution of SCPI commands sequence or JavaScript code used in communication with an instrument. Shortcuts included into IEXT will become available by default to all instances of the installed instrument and they can be complemented with user defined shortcuts for selected instrument instance. IEXT project shortcuts section is shown on Fig. 1.

 

Fig. 1: Shortcut and scripts menu

The Add Shortcut option will open an entry form (Fig. 2.) with the following parameters (mandatory parameters are marked bold):

 

Parameter

Explanation

Name

Shortcut name that will appear in the instrument's shortcut toolbar

Used in

Define build configurations that will include this SCPI command or query. All build configurations option is selected by default.

Keybinding

Shortcut's “hotkey” definition. Usually the function keys are used (F1 to F12) but other combinations with special keys (Ctrl, Alt, etc.) are also allowed.

Action type

Shortcut type: SCPI commands or JavaScript code.

Action code

Contain SCPI commands sequence or JavaScript code depending of selected Action type.

Requires confirmation

When selected, an additional confirmation dialog box will be displayed when shortcut is selected from the instrument's shortcut toolbar.

Show in toolbar

Enables displaying of shortcut button in the instruments shortcut's toolbar

Button position

Shortcut button position within the toolbar. Applicable only if Show in toolbar option is checked.

Button color

Shortcut button color. Applicable only if Show in toolbar option is checked.

 

An example of a shortcut that include JavaScript code is shown on Fig. 3. Note that its Action type parameter is set to JavaScript.

 

Fig. 2: Add new shortcut with SCPI commands sequence

 

Fig. 3: Add new shortcut with JavaScript

Created shortcut examples will appear in the Shortcut section as shown on Fig. 4. and sorted by their Toolbar position parameter.

 

Fig. 4: Shortcut's toolbar positions

Created IEXT's shortcut will appear in the instrument's Terminal and can be accessed by mouse click and F2 and F3 key respectively.

 

Fig. 5: Shortcuts in the instrument toolbar

 

Add a comment

 

A newly created EEZ project contains only the basic items in the Settings tab as shown on Fig. 1. organized into General and Build sections.

 

Fig. 1: Settings tab for the newly created project

The General sections is used to define SCPI documentation folder path that will be using during SCPI help HTML files import and update. Please be sure that newly created project is saved first, before this option is used. The recommended path to the SCPI help HTML files is doc subfolder in the folder where project file has been saved.

Additionally, we can found here all ESP's currently available Project features. For making an IEXT the following three items has to be added:

  • ESW extension definitions
  • SCPI and
  • Shortcuts

Each of the above mentioned items will add its own tab that follows the Settings tab icon as shown on the Fig. 2.

 

Fig. 2: Additional tabs for selected Project features

The Build section contains Destination folder path where IEXTs will be created. The project file folder is defined by default (hence single dot) as shown on Fig. 3.

 

Fig. 3: Build destination folder

The Build sections also contains Configurations and Files subsections while Files is still not used for building an IEXT. Configurations sections for a newly created project include only Default configuration which can be renamed is necessary. The Configurations is used to define parameters that is shared between more instruments within the same family, for example, the rigol_ds_mso_1000 IEXT includes four configurations as shown on Fig. 4.

 

Fig. 4: Multiple Build configurations example

The Configuration items are as follows:

 

Parameter

Explanation

Name

Configuration name that describe e.g. instrument family, or group of instrument models with the same feature within the same family.

For example, the same Rigol DS1000 series instruments exists in two variants with signal generator installed (-S model) or without signal generator. Consequently model with additional feature comes with more SCPI commands. Creating two configurations give us possibility to select what SCPI command set is supported in one or another model even if SCPI commands are located in the same SCPI help file (chapter). The process of how to assign SCPI command help to one or more instruments will be described later in Project file Subsystems chapter.

Description

Additional information about the configuration, e.g. manufacturers promotional text of the instrument family.

Properties

Various Instrument configuration parameters. If defined they will override default ESW values.

 

There is no limitation in number of Build Configurations, and at least one has to be defined. Configuration adding and removing can be accomplished using options shown on the Fig. 5.

 

Fig. 5: Build configuration Add and Remove options

 

Add a comment

The Subsystems section is used to define SCPI commands (organized into subsystems), searchable help section and SCPI commands and queries syntax used by ESW to assemble a valid SCPI command ready for execution. This chapter is organized in the following sections:

Adding SCPI commands and queries from HTML help file

SCPI commands (and queries) that can be used with instrument can be added in two ways: from specially formatted HTML help files or manually.

The first and preferred method require more preparations (i.e. creating HTML files) but offers more structured SCPI subsystems and simplify keeping track of changes. SCPI subsystems section has Refresh with content from HTML help folder option (Fig. 1.) that will compare HTML files stored in SCPI documentation folder (see Settings) with SCPI subsystems that already exists in the project.

 

Fig. 1: Refresh SCPI commands from HTML help folders

This method presume that each HTML file include only one SCPI subsystems. Therefore one can create as many HTML files as instrument has SCPI subsystems. That give us freedom to add support for SCPI subsystems one by one or all at once.

For example, we can start with only one HTML file that has to be located in SCPI documentation folder (Fig. 2).

 

Fig. 2: SCPI help file example

The Refresh action in this example detected and reported 16 new SCPI commands as shown in Fig. 3. where we can decide what to do with reported commands: we can select one or more of them to include them into project or reject that action if reported commands and their number is not as we expected (i.e. not in accordance with created HTML files).

 

Fig. 3: Detected SCPI command changes

The result of adding newly detected SCPI commands and queries is shown in Fig. 4. The subsystem name defined in HTML file is listed in Subsystems section and commands and queries in Commands section.

 

Fig. 4: Newly added SCPI commands

The selected SCPI command or query details are displayed on the right as follows:

 

Parameter

Explanation

Name

SCPI command or query name (has to be defined in accordance with SCPI specification).

Description

SCPI command or query name description.

Help link

Hyperlink to description related to SCPI command or query that could be within HTML help file (added automatically and displayed down below) or somewhere else.

Used in

Define build configurations that will include this SCPI command or query. All build configurations option is selected by default.

Parameters

List of mandatory and optional SCPI command parameters

Response

Expected SCPI query response

 

If HTML help file is structured properly as e.g. for the Generic SCPI instrument that is available on the GitHub repository, the ESP will also include command parameters into the project. Still, the SCPI query will require some attention, since its response type cannot be directly parsed. Therefore ESP will report some errors (seven in our case as shown in Fig. 4.).

Adding SCPI commands and queries manually

The second method for adding SCPI commands and queries is by adding it manually. A new SCPI subsystem can be created by choosing Add item option (+ sign) from Subsystems section as shown in Fig. 5.

 

Fig. 5: Create new SCPI subsystem

A new command can be added into selected subsystem using Add item option (+ sign) from Commands section (Fig. 6.).

 

Fig. 6: Add new SCPI command or query

Properties of the newly added command is displayed on the right side and can be modified as shown on Fig. 7.

 

Fig. 7: Edit SCPI command properties

In our example command will require three parameters, that can be added sequentially one by one using the Add button. The third parameter is marked as optional (Fig. 8).

 

Fig. 8: Define SCPI command parameters

The question mark (?) at the end of the name make difference between SCPI query and command. Therefore, if we'd like to add a SCPI query instead of command, the name has to end with question mark. For example, APPLy? is a query form of the APPLy command. When SCPI query is defined a new section will appear as shown on Fig. 9.

 

Fig. 9: SCPI query response properties

Finally, a word of caution when project contains SCPI commands and queries that were manually added. Every time when Refresh with content from HTML help folder option (Fig. 1.) is selected it will report that “deleted” commands are found. Such commands does not exists in any of HTML help files, hence they are proclaimed as deleted (the ESP presume that they were once existed and imported into project but afterward removed from the latest HTML files version). In this case, commands listed under Deleted tab can be simply ignored (not checked).

 

Fig. 10: Detected changes when manually added commands and queries exists

Parameters types and enumerations

The SCPI parameters could be of one or more types. The SCPI command parameter type can be specified using the selection shown on Fig. 11.

 

Fig. 11: SCPI command parameter types

 

Parameter

Explanation

Numeric

Numeric values that can be Signed integer (NR1), Decimal, i.e. float with no exponent (NR2) or Real, i.e. float always with exponent (NR3).

Boolean

Logical “True” (1) or “false” (0).

String

One or more characters.

Data block

Block of data that is started with # symbol used to transfer huge amount of data, e.g. screenshot capture, measured data from the internal memory buffer, program or profile file upload/download, etc.

Channel list

List of one or more instrument “channels” that started with @ symbol, e.g. (@1,3) specify first and third instrument channels/modules .

Discrete

Enumerations of one or more values (see below).

Any

Denote usage of any of the above mentioned parameter types.

 

Supported SCPI query parameter types are similar to command parameter types as shown in Fig. 12. With few exceptions listed in the following table.

 

Parameter

Explanation

Arbitrary ascii

Similar to String type but without quotation marks, e.g. as it is the case of response to *IDN? Query.

List of quoted string

List of two or more quoted strings separated by comma.

Non standard data block

Special case of Data block that doesn't follow SCPI standard that specify usage of # symbol at the beginning (e.g. require to properly handle data block generated by some Siglent instruments).

 

Fig. 12: Response types used with SCPI queries

Special attention require Discrete parameter types. Many SCPI commands and queries works with predefined values that can be used to address instrument resources (e.g. channels, modules), pre-installed functionalities or which has to be additionally obtained and activated, etc. For example, discrete values can be channel names like CH1, CH2, CH3 or wave shapes like SINusoid, SQUare, RAMP, PULSe, NOISe, etc. and they don't necessarily have numeric equivalents. Therefore we cannot use Numeric type, and from other side String type could offer too much freedom and in that case IEXT cannot provide “hints” i.e. list of values that instrument only can accept with accompanied command.

List of allowed (discrete) values can be defined using the enumerations (Fig. 13). Project can contain unlimited number of enumerations with possibility that one or more discrete values is repeated in two or more enumerations.

 

Fig. 13: Enumerations section for discrete parameter types

A new enumeration can be created by choosing the Add item option (+ sign) when enumeration can be specified (Fig. 14.). Enumeration data (members) can be added using the Add button and entering the name as shown in Fig. 15. and Fig. 16. Please note that Member's Value field is not used and can be left empty.

 

Fig. 14: Add new enumeration

 

Fig. 15: Empty newly created enumeration

 

Fig. 16: Specify enumeration data

Once defined, the enumeration will become available in the list of Discrete types and can be used with multiple SCPI commands and queried. For example, we can use it to specify allowed values for channel parameter of previously created APPLy? query or APPLy command (Fig. 17).

 

Fig. 17: Enumeration selection

When IEXT is successfully built and installed we can see how above mentioned channel parameter of Discrete type looks in SCPI command selection (Fig. 18). It will offer a list of discrete values that can be used to accurately select one of the existing channel.

 

Fig. 18: Discrete type parameter selection displayed as part of selected command

 

Add a comment

Subcategories