22. Terminal Scripting

Terminal Scripting tool is a Terminal Emulation tool bundled with SmartSnippents Toolbox that enables users download a firmware and interact with a target device in real time.

There are two different modes that this tool can be used.

• Standard execution mode, that enables users transmit commands to be executed on target device one by one and receive the response of each of these commands.
• Auto-execution mode, that enables users specify a “batch-file” to hold a list of commands and properties that will be executed automatically by the tool as a batch. In this case there is a set of meta-tag properties that a user can specify to be used with that file.

Terminal scripting is implemented in a command-agnostic way. Nevertheless, as an example, there is reference firmware provided by Dialog that is using a specific set of commands known as “Codeless AT Commands”. All transmitted commands should comply with the ascii format.

Communication for downloading the firmware is happening over JTAG or UART interface, while for interacting with the target in terms of transmiting commands & receiving responces, a serial UART interface in being used.

User can access Terminal Scripting by selecting the respective tool/icon found under the Tools tab of the ribbon menu.

Figure 102 Default Terminal Scripting menu

22.1. Terminal Window and Command Prompt

The Terminal Window shows the queue of commands sent to the device along with the received responses, while diskete icon found on the upper right corner of the view enables the user to export the collected information to a flat text file. Further to that, users can choose to clear information depicted in terminal window by clicking on the ‘Clear History’ button located next to the “save-as”/diskete icon.

User can type in commands in the text input filed and either press Enter to send them or just click the ‘Send’ button.

Figure 103 Terminal Window and Command Prompt

22.2. Firmware download

To download and run a firmware file in SysRAM, press the ‘Browse’ button to select the appropriate .hex, .ihex or .bin file to download. After selecting a file, press the ‘Download to SysRAM’ button for the actual downloading process to start.

The user can also run the firmware in flash: downloading and launching a file in flash may be a more complicated task, so user is welcome to use the dedicated flash programming tools before starting the Terminal Scripting tool. In this case, there is no need to press the ‘Browse’ or Download to SysRAM’ buttons

Figure 104 Firmware download

22.3. Load batch file

By pressing the ‘Browse’ button, the user is presented with a file browser to select a batch file of commands to execute on target.

User can specify a global fixed delay for the tool to wait once a command is being transmitted and before proceeding with the next one found in the file. Default value is pre-defined at 500 mSec.

User can start batch job execution by clicking the ‘Run’ button. In case that provided file is not in expected format, batch job will immediately abort and a pop up window will explain in more detail the issue found. If no issue is found, execution will continue normally by respecting the provided ‘Global fixed delay’, while the ‘Run’ button will remain disabled until all commands in the batch-file get transmitted.

User can abort batch job execution by clicking the ‘Abort’ button any time. Also users can track the flow of execution by selecting ‘Debug Batch Execution’ option. When this option is active messages will appear on the Log panel providing information about the state of execution. During a debug execution, a 20 mile seconds overhead is added to the delay time between transmuted commands for every metatag found before the next command is send.

Figure 105 Batch file loader

22.4. Formatter

User can customize how messages are displayed on the Terminal Window by provides a simply .csv file holding rules about color of the messages and the replacement of specify text. These rules are all gathered on one single file. The order of rule appearance is taken into a count when the replacement and the coloring is applied. First all replace rules are applied top to bottom and then the coloring rules are applied, again top to bottom.

For the formatter to take effect and manipulate the received message a ‘new line’ (\n) character must get received at the end of every message. Then and only then formatter will take effect and only on the last received message. Messages are spited by the formatter by ‘\n’. Previously formatted data will not get changed if a new formatter is provided.

Figure 106 CSV file formatter

22.5. Console Settings

Users can customize the way messages appear on Terminal Window throw Console Settings.

When the ‘Display timestamp’ option found selected, every transmitted message will display the time that it was received by the Terminal Spiting. The timestamp has the following form Year.Month.Day.Minute.Second.MileSecond.

When the ‘Local echo’ option found selected, commands that get transmitted will appear instantly within the Terminal Window, acompanied by the ‘–>’ marker.

When the ‘Apply text replacement’ option found selected, every text found matching any rule from the .csv file it will get replaced by the corresponding text.

Similar to the above when the ‘Apply coloring’ option found selected, every text matching any rule it will get the appropriate color

Figure 107 Console Settings

22.6. UART Connection

User can define UART connection settings for the terminal, specific to the application that is currently running on target device.

Figure 108 UART connection

The ‘Connect’ button allow the user to manually allocate the UART port. The ‘Connect’ button is disable when a connection is already established. When the user downloads a firmware to the target or sends a command to the target or tries to run a batch file the Terminal Scripting tool auto-connects to the UART port. Since Terminal Scripting tool is working interactively and keeps the UART port open, a ‘Release’ button is provided to allow users easily release the UART port so that it is available for all tools and applications. The ‘Release’ is enable when there is an established connection.

Note

If the user unplugs the target and then re-plugs it, while there is an established connection, the user won’t be able to communicate with the target. If this happens the user should release UART port and after that should re-connect to the target.

If no UART port is provided for the communication (see Settings and Virtual COM port / JTAG selection), then Terminal Scripting will find all available UART ports and it will ask users to select one. If only one it was found, then it will automatically connect to that one. In either case info regarding the connection will be provided to users.

Users can customize/configure the current communication with the UART port throw ‘Settings’ button. For the changes to be applied to the communication channel users should press the ‘Ok’ button.

Figure 109 Settings for Terminal Scripting

22.7. Batch File Structure

Batch file must follow a specific structure defined by the following rules:

1. Every line in the batch file should be terminated with a proper line termination combination, for the file to be considered as valid (win -> \\r\\n).

2. A Batch file is holding lines of data that can be recognized either as a <metadata block>, a <command block> or an independent command to be transmitted as is.

3. Tool is transmitting messages to the target in a commands-agnostic way, for that reason only well-known <metadata blocks/tags> can be recognized. Everything else will be handled automatically as a msg/command and will be forwarded to the target in an as-is basis.

4. A <metadata block> can hold one or more <metadata tags> only, accompanied by their values. Should start directly with a ‘\\’ (backslash) character, indicating the existence of at least one <metadata tag>.

5. A <metadata Tag> is a descriptor provided with a list of ‘ ‘ (space) separated values as argument. Should always start with a single ‘\\’ (backslash) character and is being terminated either from another <metadata tag> or once the end of line reached. <metadata Tags> can be found in a form one after the other, while <metadata Tags> and accompanied values should be followed always by a ‘ ‘ (space character) and this rule is applied till the end of line/end of block reached.

6. <metadata tags> can get split to two different categories.

   • Command-Specific Property metatags. This type of metatags gives unique properties to the next command that will get transmitted. If two or more metatags set the same property, the latest is used.
   • Action specific metatags. This type of metatags are independent from commands. When an action metatag is encountered then the indicated action is taken. These metatags start ‘\\>’ and can not be at the same line with a command.

7. <metadata tags> taken account for a command to be transmitted can be found in multiple lines before a command, in form of <metadata blocks> and/or after a command (within the same line), forming a <command block>.

8. <metadata tags> provided in separate lines before a <command block> or independent command, will be consumed with the first appearance of a command to be transmitted (<command block> or independent command).

9. A <command block> is starting with a command found in the beginning of the line, followed by a ‘ ‘ (space character) and a <metadata block>. After the first ‘\\’ (backslash) character found, only <metadata tags> can be specified and till the end of lineblock reached.

10. A ‘command’ can hold any alphanumeric string, but never the ‘\\’ (backslash) character. If there is a ‘command’ that explicitly contains a ‘\\’ character, then for this ‘command’ a special format should be followed and for that reason every ‘\\’ character within the provided ‘command’ should be replaced with a double back slash combination one ‘\\\\’.

11. Valid <metadata Tags> are summarized to the following:

    Property metatags:

    • \\delay [time in mSec]: If provided, and once the current command transmitted successfully, it will introduce a delay before the next command to be able to get transmitted to the target. This <metadata Tags> (if provided) will overcome global delay and prevail all other timing rules even if used in combination with other Tags. \delay <space character> <arithmetic value in mSec> <line termination sequence>
    • \\comment [description text]: It can be provided only in a single<metadata tag> <metadata block> (one <metatada bock> per line with only one <metadata tag>). \comment <space character> <any alpharithemtic string without a '\' character> <line termination sequence>

    Action metatags:

    • \>echo [description text]: If provided, it will inform tool that the provided description text needs to be displayed in a new line of the Terminal window. \>echo <space character> <any alpha-arithmetic string without a '\' character> <line termination>
    • \>label [name]: If this action meta-tag provided, it will not introduce any significant action than just to mark the targeted line with a label_name, in order for the \branch, \check metatag operation to properly use. \>label <space character> <any alpha-arithmetic string without '\' - backslash or space character> <line termination>
    • \>branch [labelName]: If this action meta-tag provided and label name exists in the batch file, then tool will record the current line location for this branch command and then It will jump to the location that the referenced labelName indicates (goto equivalent). Maximum number of branches that can be executed in real time is 10000. \>branch <space character> <any alpha-arithmetic string without '\' - backslash or space character> <line termination>
    • \>check [labelName] [respSubString]: If this action meta-tag provided, it will try to check if the provided sub-string is part of the last received line-terminated response and if there is a match, it will execute a \branch operation to the provided label Name. For \check action meta-tag, no nested branches are being supported. String comparison will happen over the originally received message – prior to any textual replacement. \>check <space character> <any alpha-arithmetic string without '\' - backslash or space character> <space character> <any alpha-arithmetic string without a '\' character> <line termination>
    • \>return: If this action meta-tag provided, it will try to revert execution pointer to the last processed \branch, \check action meta-tag, and it will continue execution from there. Maximum number of return action meta-tags that can be executed in real time, are directly related to the number of branch action meta-tags currently used. Maximum execution is restricted to 10000. \>return <line termination>

22.8. CSV Formatting File Structure

CSV file must follow a specific structure defined by the following rules:

1. Needs to have exactly three columns.
2. The first column indicates the type of rule that the line represents.
   • The keyword “replace” indicates that the line should be formatted to express values for textual replacement.
   • The keyword “color” indicates that the line should be formatted to express values for textual coloring.
3. The second one holds a regular expression (regex) that matches the textual rule we need to search for in the received message.
4. The last one, holds different value type per case:
   • In case of a replacement rule should hold a replacement string.
   • In case of a coloring rule it should hold the color name as a string to be applied.

The following list of colors is supported (standard web color):

1. white
2. silver
3. gray
4. red
5. maroon
6. yellow
7. olive
8. lime
9. green
10. aqua
11. teal
12. blue
13. navy
14. fuchsia
15. purple
16. black