| uCon HomePage | |
|
| SCRIPTING | ||
uCon supports the ability to run scripts. This means that you can create command files that allow you to programmatically automate interaction with the device uCon is connected to. The Scripts menu item supports the ability to create, edit, run, halt, pause, resume and even single-step a script. The script can be run full speed or at a debug rate, where each non-comment line in the script must be approved by the user through a simple dialog box interaction. A script can be run from the menu item Scripts->Run or through a function key or button whose "script" checkbox has been set.
As of Aug 8, 2014, uCon scripts can optionally be powered by Lua! Refer to the Lua page for more information.
QUICK JUMPS:
CREATING A SCRIPT:
A script is simply a file, so any editor that allows you to create a non-formatted text file (like notepad, or vi or emacs) can be used to create the script. Within uCon the Scripts->Edit and Scripts->New menu items will open up an editor on a current or new script respectively. The default editor is Notepad; however, this can be changed through the dialog box opened by the menu item Config->Miscellaneous by modifying the content of the "Editor" item within that dialog. A script is simply a set of commands that build up some type of interaction with the target connection (COM port, telnet, ssh, etc...) The most typically used command is likely to be "SEND" because this is the command that sends a string to the target. For more information on each of the script commands, refer to the following list. For a few quick examples refer to the examples below.
RUNNING A SCRIPT:
A script can be run through the Scripts->Run dialog box, or through a function key or button configured to access a script. In either case, when the filename is specified, it can be a full path or just a filename. If a full path is specified, the uCon will look for the script in the specified directory path. If only a filename is specified, then uCon will look for that file under the scripts directory below the directory under which uCon was installed. Typically this is X:/program files/ucon (with 'X' being a drive specification).
As of release 5.2 if uCon (Jan 2006), a script can also be paused. This simply allows the user to tell the script runner to stop prior to starting the next command in the script. Then, when in the paused state, the script can either be resumed or stepped. Resume simply allows the script to continue and step tells the script running to execute the next command in the script and return to a paused state.
TRACING A RUNNING SCRIPT:
uCon's system trace facility allows the user to monitor the execution of the script. Click the Config->SystemTrace menu item to open the system trace dialog box, and check the SCRIPTS check box. Then, if the trace window is not visible (refer to main window for view of trace window), click the Toggle button in that dialog box to enable it.
COMMANDS:
Following is the list of commands currently available for scripts:
AUXCOM [-p:] {CMD} [cmd-specific arguments]
Open and control additional com ports.
BACKUP [-r] {target IP address} {list file path}
Backup (or restore) a set of files on a uMon based target..
BEEP {frequency (hz)} {duration (msec)}
Send audible tone.
BMPVIEW [-h:l:m:R:rT:t:w:] {imagefile name} {viewer tag}
Display raw bitmap image file.
CATCH {off | catch_string1} [catch_string2] [catch_string3] [...] {catch_script}
Turns on (or off) uCon's ability to "catch" a string sent from the target and run a script.
CD [dirname]
Change current working directory.
CLS [-t]
Clear console screen.
COMPORT ['command']
Run some kind of command or configuration change on the COM port.
CONFIG {subcommand} [command-specific arguments]
Make changes to Config->Miscellaneous through script.
CONNECT {connection_type} {connection-specific arguments}
Change the current backend connection.
DIALOG [-h:mt:w:x:y:] {dialog type} {user_message_string}
Interact with the user through some type of dialog box.
ECHO {any string}
Echo the specified string to the console.
EVENT {1-8} {operation} [timeout]
Use events for multi-session synchronization.
EXIT [UCON]
Terminate the script.
FKEY [-bcs] {1-16} [ {label} {text} ]
Establish a function key (or button) setting.
FILE {sub-command} {filename} [args] ...
Interface to a file.
FSEND [-d] {filename}
Transfer file to target with no protocol.
GOSUB {tag}
Call some tagged subroutine within the script.
GOTO {tag}
Branch to some tagged location in a script file.
IF {var1} {test} {var2} {ACTION} [else ACTION]
Conditional test.
LOG {on|off|append} [file to log to]
Enabled and/or disable logging.
LUA {path to Lua script}
Run script through Lua interpreter.
MONCMD [-p:vw:] {target_ip_address} {"string_to_target"}
Send a command to a target running MicroMonitor..
NEWMON [-A:B:b:p:vw:] {target_ip_address} {binary_image_file}
Update the boot image of a target running MicroMonitor.
RECV [-txX] [arg1]
Wait for some sequence of characters.
REGEX [-bcin] {regular expression} {test string}
Run regular expression processing on a specified string.
Return from a subroutine (something called by GOSUB).
RUN {scriptname}
Run a script from within a script.
SEND [-cnp:rt:Tx] ["string_to_target"]
Pass the specified string to the target and wait for a prompt.
SET [-e] {VAR} {VAL | =EXPRESSION}
Establish the content of a shell variable.
SHELLEXEC {operation} {file} [params] [directory]
Wrapper to Win32 ShellExecute API.
SLEEP {msecs}
Delay in milliseconds.
SYSTEM [-pw] {"cmdline"}
Process a command line as a local, PC-resident command.
STRING [-a] {subcommand} {string} [args] ...
Parse, query or modify content of a string.
TCP [-ch:p:r]
Interact with other TCP based servers, particularly a remote uCon session's Telnet server.
TIME [-ef:s]
Print the current time of day or compute elapsed time in milliseconds.
TITLE [-t] [string]
Update the content of uCon's title bar.
TFTP [-r:v] {server_ip} {get | put} {srcfile} {destfile} {netascii | octet}
Transfer a file with the PC being the client.
XMODEM [-dnp:t:] {send | send1k | recv | recvcrc} {xmodem cmdline} {filename}
Startup an xmodem file transfer through a script.
SHELL VARIABLES:
Shell variables are used in uCon's scripts the same way shell variables would be used in any other shell. A variable is established either intrinsically (see below) or with the SET command, then the content of that variable can be accessed later by prefixing the name of the variable with a dollar sign ($).
Some shell variable names are dedicated to certain commands/features...
Some variable names are initialized at uCon startup:
Note that it is likely that the value of INSTALLDIR will contain the string "Program Files"; hence, when using $INSTALLDIR as an argument to a command, you will probably need to wrap it with double quotes so that it is treated as a single argument.
Most of the examples below use shell variables in some way, particularly, EXAMPLE_4 shows how shell variables can be nested to allow you to treat a set of variables as a table.
Note that the current set of established shell variables can be dumped to the console using the Scripts->Environment menu item.
SYMBOLS:
An extension to shell variables is the script runner's ability to process symbols. Similar to the way a '$' is used to indicate a shell variable, a '%' (percent sign) is used to indicate a symbol. Symbols are simply strings found in a symbol file (named by the content of the SYMFILE shell variable). The format of the content of the symbol file is simply...
With this file pointed to by the SYMFILE shell variable, a script can include "%symbol" and it will be replaced with "replacement-text" at runtime. Note this level of command line processing is only performed if the SYMFILE shell variable is set and points to a valid file.
In each of the following examples, the content of the script is blue-fixed-width font, and the output of the script is green-fixed-width font to distinguish it from the descriptive text. Also refer to each of the various command help text for additional examples applicable to that command.
Note: in all cases where shell variables are used as command line arguments, if the content of the variable includes whitespace, then the shell variable (with its leading $ character) should be enclosed within double quotes so that the content of the variable is seen as a single token (regardless of the whitespace) on the command line.
This first example demonstrates how a script is used to automate a login process using the SEND command and its ability to wait for a specified string (or prompt). We assume that the target connected to the COM port is waiting for a login or user name, and after that username is entered the user must enter a password and if the password is correct, a system prompt will be presented. The prompt used for the password is "Password:" and the system prompt generated after the password has been entered is "CLI:".
| SET PROMPT Password: | |
| SEND "els" | # Send "els" and wait for the string "Password": to |
| # be sent by the target system. | |
| SET PROMPT CLI: | |
| SEND "els_pswd" | # With the PROMPT shellvar changed, this SEND command |
| # waits for the string "CLI:" to complete. |
The "programmability"
mentioned earlier is provided by the "IF"
command and the script's ability to deal with subroutines
and branches. Here is a simple example that
will count (and echo that count) up to five...
SET COUNT 0
# TOP_OF_LOOP:
GOSUB SHOW_COUNT
SET COUNT=$COUNT+1
IF $COUNT le 5 GOTO TOP_OF_LOOP
EXIT
The '#' is used in the script in two ways:
Notice
in example #1 that the '#' does not have to be at the beginning
of a line, it can be at any point in the line to let the command parser
know that no further processing of that line should be done. If used as
a label for GOTO or GOSUB, then it must be the first character of a new
line and the label is the first block of non-whitespace after the
initial '#' character.
This
example also demonstrates the expression evaluation capability of the SET command.
The
output of this script would be...
This script demonstrates the use of the DIALOG command. Assume we want to interact with the user to query for some number between 0 and 4.. This script will query the user, and respond if the input is out of range...
This script demonstrates the use of nested shell variables. It allows you to establish a set of shell variables and then use another variable as an index into the set (as if it was a table in 'C').
In the above script, the variables VAR[1-5] are created, and can be thought of as a 5-element table of words. The loop below it uses $IDX to step through the table. The output of this script would be...
This script demonstrates the use of the FILE command and its ability to query file information and content for use in a script. The script assumes that the target is running MicroMonitor, and that there are a few files in the monitor's file system. In the nutshell, this script dumps the output of the MicroMonitor "tfs ls" command to a file (C:/tmp/log). The presence of that file is verified by the first FILE command, then the content of that file is is queried by the second FILE command and acted upon using IF.
SET LOGFILE C:/users/USER/downloads/logfile SET PROMPT "uMon:" LOG on $LOGFILE SEND "help" LOG off FILE fstat $LOGFILE IF $FILE sne FILE GOTO ERROR_1 SET LINE 3 SET COUNT 1 ECHO # DUMP_FILES: FILE token $LOGFILE 1 $LINE IF $FILE seq \$FILE GOTO DUMP_DONE IF $FILE seq _END_OF_FILE_ GOTO DUMP_DONE IF $FILE seq _END_OF_LINE_ GOTO SKIP_ECHO ECHO " "LINE$COUNT TOKEN1: $FILE # SKIP_ECHO: SET LINE=$LINE+1 SET COUNT=$COUNT+1 SLEEP 100 GOTO DUMP_FILES # DUMP_DONE: ECHO OK, all finished! EXIT # ERROR_1: ECHO Log file $LOGFILE not found EXIT
The ouput of the above script depends on the command set for the target; however, here is an example...
uMon:help Teensy4.1 uMon-M 1.0.2 Built: Jan 4 2024 @ 12:14:44 Psram: 8Mbyte Console on: VCOM and RXTX7 AppRamBase: 0x70002000 MAC: 04:e9:e5:0b:c1:cf IP: 0.0.0.0 Moncomptr: 0x60001040 Micro-Monitor Command Set: call cm dhcp dm echo edit ether exit flash fm gosub goto heap help icmp if mt mtrace phy pm read reset return set sleep sm tftp tfs xmodem version arm bkpt ccm ctx emc fpb gpio halfkay iomuxc ivt led lut mpu map nvic otp pit sai scb sd src syst wdt udp usb vcom vtbl uMon: LINE2 TOKEN1: Teensy4.1 LINE3 TOKEN1: uMon-M LINE4 TOKEN1: Built: LINE5 TOKEN1: Psram: LINE6 TOKEN1: Console LINE7 TOKEN1: AppRamBase: LINE8 TOKEN1: MAC: LINE9 TOKEN1: IP: LINE10 TOKEN1: Moncomptr: LINE12 TOKEN1: Micro-Monitor LINE13 TOKEN1: call LINE14 TOKEN1: ether LINE15 TOKEN1: heap LINE16 TOKEN1: phy LINE17 TOKEN1: sleep LINE18 TOKEN1: arm LINE19 TOKEN1: gpio LINE20 TOKEN1: mpu LINE21 TOKEN1: scb LINE22 TOKEN1: usb LINE23 TOKEN1: uMon: OK, all finished!
Note1: Some of the output is generated by the target and some is generated by the ECHO command in the script.
Note2: The "token" subcommand of FILE is useful for parsing whitespace delimited strings within a file. If you need to parse something a bit more complicated, refer to the REGEX command.
This example shows you how to make some noise when uCon starts up. We will build a script called startup_sound, and to make the script execute when uCon starts up we add that script name to the "StartScr" text box in the Config->Miscellaneous dialog. We also have to make a few assumptions about the environment for this...
The tool sndrec32 is located under C:\windows\system32 and some system .wav files are found under C:\windows\media (refer to the script below, and make appropriate changes if needed).
As far as scripting goes, this is a simple example; however, it does demonstrate the use of the SYSTEM command, and provides a cute way to generate whatever sound is in a .wav file on your system.
Just in keeping with the examples above, now lets do something that uses the "FILE" command to step through all of the .wav files found in the C:\windows\media directory...
The output of the above script is audible. You'll hear the playing of each .wav file in the media directory. The important point here is to note that the "FILE first" and "FILE next" commands provide the ability to walk through a directory of files with a name filter (the above case uses *.wav).
The SVNREV shell variable is auto-populated by uCon at startup with the SVN revision number of the uCon executable. This allows a script to verify that the running version of uCon supports the stuff in the script. So, if you are using something in a script that is relatively new (see Whats New page), then you should note the SVN revision of your version of uCon (Help->About). For this example, we'll assume the SVN revision is 620, and use it as follows at the top of your script...