ABC Script Tool Help
The ABC Script Tool is an application used to read, write and run scripts for use with AB Circle smart card readers
and smart cards. These scripts can then be used to control script execution and send commands to a connected smart card reader.
In order to run the AB Circle Script Tool, you will need a Java Runtime Environment (JRE) installed on your machine.
The Java Runtime Environment can be downloaded from here: https://www.java.com/en/download/.
For help on installing Java, please see also here: https://java.com/en/download/help/index_installing.xml.
The ABC Script Tool supports the following operating systems:
- Microsoft Windows (Windows 7 SP1 and above)
- Mac OS X (10.12 or above)
- Linux (various versions)
Note: Other operating systems should work as well (as long as there is java support), but are not tested at this time.
After installing java (see also 1.2. Prerequisites on how to install):
- On Windows and Mac OS X; in order to run the AB Circle Script Tool, simply double click the ABCScriptTool_v1.0.4.jar file and the tool will start.
- On Linux; open a terminal and type "java -jar ABCScriptTool_v1.0.4.jar" and the tool will start.
⇑ Back to top
The main program window consists of 3 parts:
- Menu: holding all options in the program which control card reader connections, handling scripts, and script execution.
- Script Panel: used for displaying and editing scripts.
- Output Panel: used for displaying messages and statuses.
In order to run a script on a smart card reader in general the following steps should be performed:
- Create a new script or open an existing script through the "File" menu
- Select the smart card reader to run the script on from the "Readers" menu.
The program will show all AB Circle readers connected to the system.
- Select the connection options for connection to the reader through the "Connection" menu (or alternatively, define the options in a script).
- Control script execution through the various options, or build a script by inserting script commands through the "Script" menu
- Select "Validate" (or its shortcut F4) to validate the script or "Run" (or its shortcut F5) to run the script.
The output window will display the result of the script run(s).
⇑ Back to top
There are various menu options in the program which control smart card readers, scripts and script execution.
These are listed below:
-
File
- New: Start a new script file
- Open: Open a script file
- Open Recent: Open a previously opened script file
- Save: Save the currently open script file
- Save As: Save the currently open script file under a different name or location
- Exit: Exit the program
- Readers
- List of AB Circle smart card readers present on the local system
Click any of the listed readers to select for use
- Refresh: refresh the list of smart card readers
- Connection
- Mode
- Shared: Connect to the reader using Shared mode
- Direct: Connect to the reader using Direct mode
- Protocol
- Card Default: Connect to the card using the default card protocol (T=0 or T=1)
- T=0: Connect to the card using the T=0 protocol
- T=1: Connect to the card using the T=1 protocol
- Script
- Options
- Word Wrap: Enables or disabled word wrap in the script editor panel
- Script Run Iterations: sets the number of iterations a script should run
- Infinite: Sets the number of script run iterations to infinite
- Delay between commands: Sets an optional delay in milliseconds between commands sent to the reader
- Delay between script runs: Sets an optional delay in milliseconds between script runs
- Connect per iteration: Enables or disables (re-)connecting to the reader each script run iteration
- Wait for card before running: If enabled, waits for a card to be detected on the reader before starting running a script
- Insert
- RESET command: inserts a .RESET command
- CONNECT T=0 command: inserts a .CONNECTT0 command
- CONNECT T=1 command: inserts a .CONNECTT1 command
- CONNECT DEFAULT command: inserts a .CONNECTDEFAULT command
- CONNECT DIRECT command: inserts a .CONNECTDIRECT command
- DISCONNECT command: inserts a .DISCONNECT command
- ITERATIONS command: inserts a .ITERATIONS command
- RUNINFINITE command: inserts a .RUNINFINITE command
- WAITFORCARD command: inserts a .WAITFORCARD command
- COMMANDDELAY command: inserts a .COMMANDDELAY command
- SCRIPTRUNDELAY command: inserts a .SCRIPTRUNDELAY command
- APDU command: inserts an (example) .APDU command
- ESCAPE command: inserts an (example) .ESCAPE command
Note: please see the command list below for explanation of the commands
- Validate: Validates the current script & reports errors if any found
- Run: Runs the current script
- Stop: Stops a currently running script (thus only shown if a script is running)
- Output
- Options
- Show timestamp: cntrols if a timestamp is shown in each line of the output
- Output to log file: If enabled directs the output to a log-file
- Open Log Location: Opens the folder where the logs are located
- Clear: Clears the output panel
- Help
- Show Help: shows this help file
- About: Shows a dialog about the AB Circle Script Tool
⇑ Back to top
A smart card reader script consists of a collection of commands that either;
- control the script execution
- control the card handling and connection
- APDU / Escape commands sent to a selected smart card reader and/or card
Note: commands that control script execution override settings chosen in the menu.
The usual order of writing a script is usually:
- A list of commands controlling script execution;
- Optional card connection command;
- APDU's or Escape commands to send to the reader;
- Optional card disconnect command.
The real order of commands does not matter since the complete script is parsed before running.
But the commands are executed from top to bottom, thus an ITERATIONS command followed by a RUNINFINITE
will be overridden by the latter and the script will run infinite.
The list of supported commands is listed below:
1. Controls script execution
|
| .ITERATIONS:N | : | Number of script iterations to execute, where N should be a number between 1 and 999999. |
| .RUNINFINITE | : | Run script infinitely |
| .WAITFORCARD | : | Wait for a detected card before running the script |
| .COMMANDDELAY:X | : | Delay between commands in milliseconds, where X should be a number between 1 and 999999. |
| .SCRIPTRUNDELAY:Y | : | Delay between script runs in milliseconds, where Y should be a number between 1 and 999999. |
2. Control card connection
|
| .RESET | : | Resets the card in/on the reader using current active protocol |
| .CONNECTT0 | : | Connect to the card in/on the reader using T=0 protocol |
| .CONNECTT1 | : | Connect to the card in/on the reader using T=1 protocol |
| .CONNECTDEFAULT | : | Connect to the card in/on the reader using the card default protocol |
| .CONNECTDIRECT | : | Connect card using Direct mode |
| .DISCONNECT | : | Disconnect a previously connected card
Note: a card will always be disconnected at the end of an iteration or script run (depending on selected option) |
3. Commands to send to the reader / card
|
| APDU command | : | APDU command to send; should be in the format: command # [optional return bytes] response |
| .ESCAPE | : | Escape command to send; should be in the format: .ESCAPE@control code: command # [optional return bytes] response |
// Example Script for Contactless Mifare 1K card.
// Wait for detected card before running script
.WAITFORCARD
// Number of script iterations (1 iteration here)
.ITERATIONS: 1
// Connect card using T=1 protocol
.CONNECTT1
// Send APDU commands (Format: command # [optional return bytes] response)
//Load Authentication Key (Key Index 0)
ff 82 00 00 06 ff ff ff ff ff ff#90 00
//Authenticate (Block 4, Key Type A, Key Index 0)
ff 86 00 00 05 01 00 04 60 00#90 00
// Write 16 bytes into Block 4
ff d6 00 04 10 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F#90 00
// Read 16 bytes from Block 4
ff b0 00 04 10#00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F 90 00
// Set Value Block 5 to 5
ff d7 00 05 05 00 00 00 00 05#90 00
// Read Value in Block 5
ff b1 00 05 00#00 00 00 05 90 00
// Increment Value in Block 5
ff d7 00 05 05 01 00 00 00 01#90 00
// Read Value in Block 5
ff b1 00 05 00#00 00 00 06 90 00
// Decrement Value in Block 5
ff d7 00 05 05 02 00 00 00 02#90 00
// Read Value in Block 5
ff b1 00 05 00#00 00 00 04 90 00
// Disconnect card
.DISCONNECT
// (c) 2020-2021, AB Circle Limited
|
⇑ Back to top
Copyright © 2020-2021, AB Circle Limited