The goal of this document is to introduce you to the powerful and flexible script engine that
BlackcatUSB Script Engine
BlackcatUSB Script Engine
is built into BlackcatUSB. The purpose of this feature is to allow you to create
device specific scripts for manipulating the data on the flash.
The BlackcatUSB script engine is modeled after the vbscript language for
efficiency and simplicity.
How a script file is executed
A script file can be executed one of two ways, automatically (like in the case of
JTAG) or manually from the "Load Script" button on the front tab.
In JTAG mode, when a device is detected, the device sends BlackcatUSB its
manufacture ID and part number. The script engine then looks for the name of
that ID in the script folder and if found will run that script. If it was not found, the
script engine will instead run the "default.bcs" script.
In SPI mode, only flash information is retrieved, so the software will not know
what device it is being used in or what it is for. Therefore, you will need to load
the script manually after the software has detected and connected to the Flash
Script file structure
A script file is just a plain text document. You can open and edit one using
Notepad. The contents of a script file is made up of commands, control tags, and
events. When a script file is ran, any non event command will be executed.
An event is a series of commands that are executed together, much like a function.
Events can only be executed two ways, by either using its name as a function or
from assigning it to a button.
To create a event, you use CreateEvent(EventName) where EvetName is the
name you will specify. At the end of your event you must be a EndEvent tag to
let the script engine know the event is over.
Events are very useful. You can pass variables to events and retrieve values from
events. When you pass a variable or value to a event, the event will create a new
variables for each argument passed. These new variables will be named $1, $2, $3
and so on for each variable passed.
For example a script that looks like:
Will popup "Hello World" when executed.
You can also use events like functions to parse information an use the event like
you would a command function. For example:
StrVar = $1 & $2
Commands are built in functions that you will want to use to access the
functionality of the software. Some functions can be used to retrieve values and
some are used only to do certain tasks. You can test out commands by entering
them into the software's console page. This can be a good way to test out
elements of your script in real time, without the need to close and restart the
software each time.
For a list of all the commands you can use, see
Script_Commands.pdf (Located in the Blackcat USB Build 247 Download)
A variable is a name that you assign a object too. You can assign a string, data,
integers, or boolean values.
ThisVar = "Hello World"
Will now create a variable named ThisVar whose string value is "Hello World".
To create a data array use ";" after each byte:
MyData = 0x01;0x02;0x03;0x04;0x05;0x06
If you assign a variable 4 or less bytes, the variable will auto convert to a Integer
type instead of a Data type. To create a boolean variable:
DoVar = True
And to create an integer:
VarInt = 470
Integer variables are able to be added or subtracted. String and Data variables can
VarInt = 5
VarInt += 10
msgbox(VarInt) #this will produce the result of 15
For strings and data, use the operand "&", for example:
VarStr = "Hello "
VarStr = VarStr & "World!"
msgbox(VarStr) #Will produce "Hello World!"
MyData = 0x01;0x02;0x03;0x04;0x05
MyData = MyData & 0x06;0x07
msgbox(hex(MyData)) #Will produce "0x01020304050607"
* the hex command converts the data array into a hex string that can be printed.
Simply put, you can create a IF ELSE statement to execute code based on a
condition. Use the tag "If" followed by a condition statement. You can add a
"else" tag to execute if the statement is evaluated false. End the condition using
the tag "EndIf"
For example, take the following code:
If (5 > 2)
msgbox("This will be executed")
msgbox("This will not")
The condition statement (5 > 2) is evaluate and found to be true. You can also
use functions that return TRUE or FALSE in a If statement.
If you precede the condition statement with the "not" keyword, what ever the
statement is evaluated at, the opposite will happen.
If not (GetValue() > 10)
msgbox("This will be executed")
retVar = 5
To allow you to control the execution of the script, you can use many built in
The tag "goto" can be used to change the current position of your script that is
executing. To do so, create a label by creating a name and ending it with ":" then
when your script executes "goto <that label name>" the script will go to that
The tag "exit" can be used to leave the current section of code. If this is used in a
If statement, the script position will jump to the next command after the EndIf
tag. If you want to leave a event, you can specific "exit event" or if you want to
quit the whole script all together, use "exit script".
A new feature is the ability to create sub scripts. A subscript is a specific script
that is only executed if it is selected via the main tab on the software. For
example, if you have two different devices that use the same microprocessor (and
thus return the same device ID) you can create two different scripts and use the
"Subscript(script name)" tag to specify that additional script. The sub script you
specify needs to exist in your scripts folder. When the user selects this script
from the main page, only the main script and the specified sub script are executed
Now when you start the software, you can choose which script run by selecting it
from the drop down menu. To save you time, this choice is remembered and will
automatically be chosen the next time you run the software.