Introduction to ScanaStudio scripts

ScanaStudio scripts are JavaScript (*.js) files that are executed by ScanaStudio. Those scripts have access to the signals captured by logic analyzer devices, and can output data in various ways depending on the task the script has to accomplish. There are various kind of script, the most common type is a protocol decoder script, that is, a script that will decode (interpret) logic signals according to a standard protocol (like I2C, Serial UART, CAN, Etc…). There are also scripts that will allow a logic analyzer device to trigger on a specific word of a protocol, and finally, there are scripts that can build some logic patterns (like a PWM pattern) that can be later generated by devices that support signal generation.

Note: This document is oriented to users with some minimal skills, you are one of those users if:

• You have programmed in any language before, and preferably have some JavaScript background
• You have some minimal experience with logic signals and digital electronics
• You are familiar with one or more serial protocols (like I2C, UART or CAN bus, to name only a few examples)

If you feel you’re lacking some of the skills mentioned above, it’s probably not a good idea to start writing scripts until you gain more knowledge about digital electronics and programming.

A bit of history

In 2019, Ikalogic has introduced a new version of ScanaStudio (Logic Analyzer software). With this new version, the scripting system was totally rebuilt from the ground up to enhance its operation and broaden the scope of the scripts. It’s also worth noting that the previous script system was initially designed in 2015 only to decode signals. Over the years, features and options were gradually added to the scripting system, and it came to a point where it was totally non-harmonized and barely usable for someone outside Ikalogic organization. This new version of ScanaStudio script API addresses this problem. It’s designed to be intuitive, future-evolutions ready, easy to appropriate and fast to execute.

Scope of this document

ScanaStudio scripting language is based on JavaScript. This document will not cover the JavaScript basics that someone need to have to write or modify ScanaStudio scripts. Excellent tutorials exist on the internet for that purpose. This document will however cover all the details related to the specifics of writing scripts for ScanaStudio. Example source codes will be provided as often as necessary, so if you’re not a JavaScript expert but have general programming knowledge, you should be able to follow fairly easily.

Important note: This documentation covers ScanaStudio V3.1 and beyond. Earlier versions are not covered by this documentation as it is considered too different to be merged in a single document. Older scripts repository can be found here.

What can a ScanaStudio script do?

We’re constantly opening up new parts of ScanaStudio to be “scriptable”. At the moment this documentation is written, the following main features are implemented:

• Decode logic signals according to a specific protocol (this include building packet-view and hex-view).
• Build logic patterns to be generated with devices that have this capability.
• Build demo signals for a particular protocol (arbitrary signals that are generated when no device is connected to the software)
• Generate trigger sequence (e.g. trigger on a specific I2C address).

More features are planned, so check back later and/or don’t hesitate to share the list of features you think script should be able to handle.

Principle of operation

As stated before, ScanaStudio scripts are based on standard JavaScript. There are two ways ScanaStudio and user script need to interact with each others:

Interaction initiated by ScanaStudio ScanaStudio needs to call one or more special functions (called entry-point functions hereafter) to start an operation. For example, if a script needs to be used to decode signals it must at least implement a function called on_decode_signals(resume), something like this:

function on_decode_signals(resume)
{
   /*
   Write here the code that will interpret the logic signals
   resume is == true if decoder should resume where it left
   */
}

This function will be called by ScanaStudio when logic signals need to be decoded. From a programming point of view, entry point functions can be treated as events handlers.

Interaction initiated by the script The script needs to retrieve information from ScanaStudio, as well as call various functions in ScanaStudio software. An object called ScanaStudio is exposed in the script context as a global object, and can be used for all the interactions with ScanaStudio that are initiated by the script. For example, a protocol decoder script can get the sampling rate for the last captured samples via this function call:

ScanaStudio.get_capture_sample_rate()

In the same manner, the script can output some console messages via this function:

ScanaStudio.console_info_msg("Hello world from the script!").

Below is a more complete example:

function on_decode_signals(resume)
{
   ScanaStudio.console_info_msg(
                  "The sample rate is:" +
                  ScanaStudio.get_capture_sample_rate() + " Hz");
}

Obviously, the example above is completely useless in terms of “signal decoding”, it’s just here to illustrate the way the standard JavaScript is enhanced with the ScanaStudio global object.

Setting up coding environment

This section presents the coding and debugging environment as used by Ikalogic engineers. Those are only recommendations. You’re free to use our tools and methodology and/or inspire from this setup as needed.

To edit the script (or write new ones) we recommend using VSCode editor. It’s a free and open source editor that is perfectly adapted to coding and scripting.

VSCode extension

Ikalogic provides an VSCode extension that adds text snippets, coding hints, and autocompletion feture. After downloading and installing VSCode to your computer, you can install ScanaStudio plugin by following those steps:

1. In VSCode, open the extensions tab (shortcut Shift+Ctrl+X)
2. In the searchbox, type “ScanaStudio”
3. Install the extension named “ScanaStudio-Scripting”

Once the ScanaStudio-scripting package is installed, you will see snippet widgets appear as you type to help you finding the right syntax.

Some snippets can generate whole blocs of code - a template - like the meta-info-template snippet:

Which will generate this code block:

/* Protocol meta info:
<PROTOCOL_NAME> My Protocol </PROTOCOL_NAME>
<DESCRIPTION>
My protocol can decode the s%^* out of any logic signal!
</DESCRIPTION>
<VERSION> 0.0 </VERSION>
<AUTHOR_NAME>	Your name </AUTHOR_NAME>
<AUTHOR_URL> your@email.or.website </AUTHOR_URL>
<COPYRIGHT> Copyright 2018 your name </COPYRIGHT>
<LICENSE>	This code is distributed under the terms of the GNU General Public License GPLv3 </LICENSE>
<RELEASE_NOTES>
V0.0:  Initial release.
</RELEASE_NOTES>
*/

Hint: Start typing the word “template” and ScanaStudio-Scripting VSCode extention will show a list of all available template snippets that can help you easily get started with the writing of a script.