dScope Series III Scripting and automation

Scripting: Getting Started

The thought of scripting dScope can be very daunting if you've never scripted anything before, and, let's face it, few people have. dScope uses VBScript (Visual Basic Script) which is a Microsoft computer language. It is based heavily on Visual Basic with which it shares a lot of similarities, but in many ways it's simpler with remarkably few big features missing. Nearly every Windows computer has a scripting host built in (the "Windows Scripting Host" or "WSH") which enables it to recognise and run VB scripts natively. If you were to open Notepad and write the line:

MsgBox "Hello"

You could then save the file as "Hello.vbs" and you would have created a working executable script. If you double click on this file, the Windows Scripting Host will recognise it as a VBS file and execute it. This will create a little message box with the word "Hello" in it. If you think that's too simple to be true, you had better try it.

Getting started scripting dScope is not much harder. dScope uses the same technology behind the scenes, but is adapted so that it works from within dScope and can access all its "Methods" (the things dScope can do) and "Properties" (its settings) directly.

Exercise: Creating a very simple dScope script
This section will guide you in very small steps through creating a very simple dScope script. You will need the dScope software installed and running and a dScope connected.

From the "Automation" menu, select "Edit Script" - this will open the script editor.
The script editor opens with a new blank script already loaded as shown below. In the panel on the left is the basics of a script. All the lines that begin with a single quote " ' " and appear in green are comments. You can also have a comment at the end of a line (see the last line below). Anything in blue is a VBScript function or statement. The main thing to note here is that there is a subroutine called dScope_Main that is executed when you run the script.

In the script edit panel, in the line below where it says ""' *** TODO : Insert your code here *** " type the word "msgbox " (without the quotes). You should find that as soon as you enter the space at the end of the word, that dScope recognises it as a command, and will turn it blue and add capital letters so that it reads "MsgBox"
Next, in the list of dScope methods and properties in the panel on the right, click the "+" next to "Analyzer" to open out the analyzer branch of the tree. (This has already been done in the screen shot above.)
Do the same again to open out the "Signal Analyzer" branch as shown above.
Double click on the item that says "Channel A RMS Amplitude" (the one that is highlighted above). You should find that the words "SignalAnalyzer.SA_ChARMSAmpl" have been inserted into the script at the cursor position.

At this point you have completed a working script that accesses the dScope and retrieves the Channel A reading from the Signal Analyzer and displays it in a message box. It isn't saved, but you can still run it by clicking on the run script button on the toolbar:

. Try it now - you don't need to save the file to run it. You will notice that the message box is a bit sparse. You could enhance this line by changing the line in the script to:

MsgBox Round(SignalAnalyzer.SA_ChARMSAmpl,2) & "dBu", vbInformation, "Reading from script"

This will display the same reading rounded to 2 decimal places and with the letters "dBu" appended to the end. In addition, the "vbInformation" bit tells the scripting engine to make this an "information" message box and to put the words "Reading from script" in the title bar. This all works because the setting of the message box are expected by the scripting engine in a particular sequence separated by commas. The message box only has three parameters: the message content, the type of message box (which includes what buttons it has on it etc.) and the title bar text.

Changing dScope Settings
The above example basically reads a value from dScope and sticks it in a message box. If we wanted to change a value of a dScope setting, the syntax is very simple:

SignalGenerator.SG_ChAFreq = 876

The above will set the Signal generator Channel A frequency to "876". This hasn't said anything about the units, and will set the generator value to "876" in whatever units the dScope generator is currently set to. We could force the units to Hz by the line:

SignalGenerator.SG_ChAFreqUnit = UNIT_FREQ_HZ

This line says we want to change the "SG_ChAFreqUnit" property of the "SignalGenerator" object to a value of "UNIT_FREQ_HZ". The "UNIT_FREQ_HZ" is a "constant" that is defined within the dScope software and is something that it will recognise as a valid value for the frequency unit of the signal generator. When we select the Signal Generator Channel A frequency unit from the list on the right of the edit window the applicable constants for this setting are shown in the box below it. These can also be double clicked to copy them across to the edit panel. This is shown in the screen shot below.

Properties list

Saving and running scripts
Once you have written your script, you need to save it to be able to use it again later. This is the same as saving any other file on a Windows system: just click the save icon save button

and enter a file name. The system will save the file with a .dss file extension if you don't specify one. It's good practice to fill in the description comment at the top of the script and add any notes that will help you know what the script does at a later stage.

To run a script at a later stage you can double click on the file in Windows Explorer and it will execute within dScope automatically, including starting dScope if it is not already running. Probably more useful, you can select the script from the dScope "Run Script" dialogue and run it that way. If it is something that you use frequently, you can create a button on the User Bar that runs the script. See the dScope Operation Manual for information on how to do this.