EEZ project – Preparing the HTML help
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 that the EEZ Studio 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 AOO (Apache OpenOffice) Writer what 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 AOO 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: AOO 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 EEZ Studio 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 EEZ Studio will report detection of the HTML help file that contain newly defined APPLy from our example as shown in Fig. 5. Check Command option to commit its import. The newly detected command and query will also introduce two enumerations (<voltage> and <QueryParam>) that will be also detected and reported into the separate tab (Fig. 6).
Fig. 5: Detected new SCPI command
Fig. 6: Detected new enumerations
When detected new items are 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 AOO Writer with previously installed WebPublish extension will be used. Please note that WebPublish extension installation require AOO Writer restart. The WebPublish extension works with profiles and a HTML profile is required for conversion into HTML format.
To access the WebPublish extension, open the AOO Extension Manager as shown in Fig. 9.
Fig. 9: Open AOO Extension Manager
Fig. 10 shows the AOO Extension Manager in which you should find Webpublish and click on the Option button (3) to view the profile.
Fig. 10: AOO Extension manager
In the list of WebPublish profiles (Fig. 11), you can select the default HTML profile (4) and open it (5) to check that its parameters are set as shown in Fig. 12
Fig. 11: WebPublish extension profiles
Fig. 12: WebPublish HTML profile definition
Now we can select from WebPublish toolbar HTML option, select above mentioned HTML profile (Fig. 13) and choose name for the HTML file.
Fig. 13: 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 accomplish with e.g. MS Word. As a final step a Save as option to HTML format has to be selected as shown on Fig. 14.
Fig. 14: MS Word Save as HTML option