Parameters
Bool - is a value of either TRUE or FALSE
String - is a value of readable characters. This value is indicated with surrounding
quotes
Integer - is a 32 bit (unsigned) number. Hex values are automatically converted
Data - is an array of bytes. Can be specified with 0x80;0x81;0x82 etc.
Functions
Command: SetParam
Parameters: Integer, Integer
Syntax: Setting, Value
Description: Sets a device parameter on the board (firmware controlled). The
delays are set in milliseconds and is the amount of time the AVR
should wait between read or write instructions. The main purpose
of this command is to fine tune performance; the faster the device
operates, the higher the error rate is. This can also affect different
target devices differently.
Settings: 1: Intel Flash delay
2: AMD Flash delay
3: Memory read delay
4: Memory read mode
5: Flash base location
Examples: SetParam(1, 30) #Sets the Intel flash delay to 30
ms
Command: Ejctrl
Parameters: Integer
Returns: Integer
Description: Sends a JTAG control message to the target device. These types of
commands are very dependant on the target device. This can be
used to stop (0x10000) or start (0x0) the target processor. The
result of the command is returned.
Examples: Ejctrl(0x10000) #Stops the target processor
Command: Pause
Parameters: Integer
Description: Waits the specified amount of time (in milliseconds), useful only
in scripts.
Examples: Pause(1000) #Waits 1 second
Display Commands
Command: writeline
Parameters: String
Description: Displays a message to the console.
Examples: writeline("this is only a test")
Command: msgbox
Parameters: String
Description: Displays a message to the user using a pop-up box.
Examples: msgbox("Hello World!")
Command: mode
Parameters: None
Returns: String
Description: Returns a string indicating which mode BlackcatUSB is in.
Examples: mode() #Returns "JTAG"
Command: ask
Parameters: String
Returns: Bool
Description: Asks the user a yes or no question and returns that value. You can
use this in a if statement to make conditional sections.
Examples: ask("Continue script?")
Command: status
Parameters: String
Description: This sets the status text (the bottom bar of the software).
Examples: status("script is complete")
Tab Commands
These are for creating a application specific tab that allows you easy access to commands from the GUI
Command: Tab.Create
Parameters: String
Returns: Integer
Description: Creates a application specific tab. Returns the index of the tab.
Examples: Tab.Create("My Device")
Command: Tab.AddGroup
Parameters: String, Integer, Integer, Integer, Integer
Syntax: Name of group, (X-axis), (Y-axis), Length, Height
Description: Creates a group box on the tab.
Examples: Tab.AddGroup("Feature",10,10,420,140)
Command: Tab.AddBox
Parameters: String, String, Integer, Integer
Description: Creates a input box on your tab.
Examples: Tab.AddBox("BXNAME","default text",30,110)
Command: Tab.AddText
Parameters: String, String, Integer, Integer
Description: Creates a text label on your tab.
Examples: Tab.AddBox("txtName","What to say",30,110)
Command: Tab.AddImage
Parameters: String, String, Integer, Integer
Description: Adds a image to your tab from the specified file (in your scripts
folder)
Examples: Tab.AddImage("ImgName","logo.gif",20,20)
Command: Tab.AddButton
Parameters: Event, String, Integer, Integer
Description: Adds a button to your tab. The specified event is called when the
user clicks on the button.
Examples: Tab.AddButton(HelloWorld,"Click Me!",20,20)
Command: Tab.Remove
Parameters: String
Description: Removes any previously added object from your tab.
Examples: Tab.Remove("ImgName")
Command: Tab.SetText
Parameters: String, String
Description: Changes the text of any previously created object
Examples: Tab.SetText("txtName","Jigga Jigga!")
Command: Tab.ButtonDisable
Parameters: String
Description: Disables a button so the user can not click it and run the event.
Examples: Tab.ButtonDisable("btName")
Command: Tab.ButtonEnable
Parameters: String
Description: Enables the button (if you had it disabled)
Examples: Tab.ButtonEnable("btName")
JTAG Specific Commands
These commands are only valid when the device is in JTAG mode. If it is not, they are ignored.
Command: JTAG.MemoryAddress
Parameters: Integer
Description: Initialized the dynamic memory controller and sets the base
memory address.
Examples: JTAG.MemoryAddress(0x80000000)
Command: JTAG.MemorySize
Parameters: Integer
Description: Sets the size of the memory (in bytes) of the dynamic memory
Examples: JTAG.MemorySize(0x800000)
Command: JTAG.MemoryInit
Parameters: None
Description:
Will initialize and connect the BlackcatUSB interface to the
memory interface. You may need to specify address and size prior
to calling this function. If successful, the GUI will add the
"Memory" tab.
Examples: JTAG.MemoryInit()
Command: JTAG.FlashBase
Parameters: Integer
Description: Will set the hard wired base address of where that flash device is
located on the memory controller.
Examples: JTAG.FlashBase(0x1FC00000)
Command: JTAG.FlashInit
Parameters: None
Description:
Will connect to the CFI compliant flash on the memory controller
to allow for reading and writing. This will create the "Flash" tab on
the GUI. Must set FlashBase prior.
Examples: JTAG.FlashInit()
Flash Device Commands (compatible with SPI and JTAG modes)
Command: Flash.Exist
Parameters: None
Returns: Bool
Description: Returns true if the flash device has been initialized and is
connected.
Examples: Flash.Exist()
Command: Flash.Write
Parameters: Data, Integer, Optional Integer
Syntax: Data object to write, flash address offset, optional length
Description:
Writes a data variable to the flash device. Works for both CFI and
SPI flash devices, but please note you must have already initiated
the flash.
Examples: Flash.Write(dataVar,0,256) #Writes
Command: Flash.Read
Parameters: Integer, Integer, Optional Bool
Returns: Data
Description:
Reads data from the flash device. Works for both CFI and SPI
type flash devices, but please note you must have already initiated
the flash.
Examples: dataVar = Flash.Read(0,512) #Reads 512 bytes
Command: Flash.ReadVerify
Parameters: Integer, Integer
Returns: Data
Description:
Similar to ReadFlash(), this function actually does it twice and
compares the result, and if needed verifies all data to ensure that
the data read is 100% accurate. Returns nothing if verification
failed. This function is preferred over ReadFlash where the
integrity of the data is vital.
Examples: dataVar = Flash.ReadVerify(0,512) #Reads 512 bytes
Command: Flash.ReadString
Parameters: Integer
Returns: String
Description: Reads a string from the location specified on the flash device.
Returns nothing if error or string not found.
Examples: dataStr = Flash.ReadString(0x5000)
Command: Flash.GetSectorSize
Parameters: Integer
Returns: Integer
Description: Returns the size
Examples: dataInt = GetSectorSize(0)
Command: Flash.GetSectorCount
Returns: Integer
Description: Erases the specified flash sector
Examples: sectors = Flash.GetSectorCount()
Command: Flash.EraseSector
Parameters: Integer
Returns: Nothing
Description: Erases the specified flash sector
Examples: Flash.EraseSector(0)
Command: DumpFlash
Parameters: None
Description: Reads all the data from flash (twice) and then prompts the user to
save the file to disk. Usefully for making a flash backup.
Examples: FlashDump()
Command: FixFlash
Parameters: None
Description:
Attempts to reprogram the bootloader of a device blindly (no
verification, no check device id etc.). This is sometimes successful
in restoring a device that does not boot correctly. Only supported
in JTAG mode.
Examples: FixFlash()
Command: Verify
Parameters: None or Bool
Returns: Bool or nothing
Description: Used to enable or disable the flash verify process. It can also be
used to return the current setting.
Examples: Verify(true)
File Input and Output
Command: OpenFile
Parameters: String, String (optional)
Returns: Data
Description:
Prompts the user for a file and then reads the file from disk and
returns a data variable. First parameter is the title of the window
and the optional second is the standard file filter to use.
Examples: MyData = OpenFile("Choose file", "Firmware files (*.bin)|*.bin")
Command: SaveFile
Parameters: Data, String, String (optional)
Syntax: Data variable to write, title prompt, default save name
Description: Prompts the user to save a data variable to the hard drive.
Examples: SaveFile(MyData,"Where to save?","fileread.bin")
Misc
Command: hex
Parameters: Integer
Returns: String
Description: Converts a integer value or variable into a hex string
Examples: hex(255) #ouputs "0xFF"
Command: resize
Parameters: Data, Integer, Integer (optional)
Description:
Resizes a byte array (usually in a variable), starting at the first
parameter. The optional parameter can be used to specify how
many to copy.
Examples: resize(datavar,2) #removes the first two bytes
Command: Len
Parameters: String, Integer or Data
Returns: Integer
Description: Returns the length of a string , the number of bytes in a data object
or the number of bytes to hold a integer.
Examples: len("hello") #returns 5
dataVar = 0x1F;0x2F;0x2F;0xFF;0x2A;0x50
len(dataVar) #returns 6
len(302) #returns 2
Command: Byte
Parameters: Data, Integer
Returns: Integer
Description: Returns the value of the byte located in a data array.
Examples: dataVar = 0x1F;0x3F;0x2F;0xFF;0x2A;0x50
word(dataVar,2) #Returns 47
Command: Word
Parameters: Data, Integer
Returns: Integer
Description: Returns the value of the four bytes located in a data array.
Examples: dataVar = 0x1F;0x3F;0x2F;0xFF;0x2A;0x50
word(dataVar,2) #Returns 805251664
Command: HWord
Parameters: Data, Integer
Returns: Integer
Description: Returns the value of the two bytes located in a data array.
Examples: dataVar = 0x1F;0x3F;0x2F;0xFF;0x2A;0x50
hword(dataVar,2) #Returns 12287
Command: value
Parameters: String
Returns: String
Description: Returns the text value of a Tab object, such as a textbox you have
created.
Examples: strVar = value(MYINPUTBOX)
Command: ToInteger
Parameters: String
Returns: Integer
Description: Converts a integer stored in a string as a integer.
Examples: ToInteger("234") #Returns 234
Command: sigmakey
Parameters: None
Returns: String
Description: Returns the SIGMA key of a given device. Only compatible in
JTAG mode. Also prints the key to the console.
Examples: strVar = sigmakey()
Command: copy
Parameters: Data, Data
Returns: Data
Description: Copies two data variables and returns them as a new combined
data variable.
Examples: dataVar = copy(data1,data2) #equals data1+data2
Terms of Use:
THIS TUTORIAL IS INTENDED FOR THEORETICAL USE ONLY, USE ON PRODUCTION SYSTEMS MAY VIOLATE YOUR ISP's TERMS OF SERVICE. THEORYSHARE TAKES NO RESPONSIBILITY FOR YOUR ACTIONS. THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THIS SOFTWARE IS INTENDED FOR EDUCATIONAL USE ONLY AND MAY BE ILLEGAL IF USED IMPROPORLY. USERS ASSUME FULL RESPONSIBILITY FOR THEIR ACTIONS.
|
