uCon HomePage Lua
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:

AUXCOM BACKUP BEEP BMPVIEW CATCH CD CLS COMPORT
CONFIG CONNECT DIALOG ECHO EVENT EXIT FILE FKEY
FSEND GOSUB GOTO IF LOG LUA MONCMD NEWMON
RECV REGEX RETURN

RUN SEND SET
SHELLEXEC SLEEP SOCKET STRING SYSTEM TCP TFTP TIME


TITLE XMODEM

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

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 variable names are dedicated to certain commands...

Some variables are read-only, and only show up within the context of a script:

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...

symbol replacement-text
symbol1 replacement-text1
symbol2 replacement-text2

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.

EXAMPLES:

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.


EXAMPLE_1:

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.


EXAMPLE_2:

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

# SHOW_COUNT:
ECHO Hello, the count is now $COUNT
RETURN

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...

Hello, the count is now 0
Hello, the count is now 1
Hello, the count is now 2
Hello, the count is now 3
Hello, the count is now 4
Hello, the count is now 5


EXAMPLE_3:

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...

# TOP:
DIALOG Q_AND_A "Please enter a number between 1 and 4:"
IF $DIALOG lt 1 GOTO ERROR
IF $DIALOG gt 4 GOTO ERROR
DIALOG OK "Thanks!"
EXIT
DIALOG YES_NO "Out of range, want to try again?"
IF $DIALOG seq YES GOTO TOP
DIALOG OK "Fine, just click OK to exit."
EXIT

EXAMPLE_4:

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').

SET VAR1 Hello,
SET VAR2 my
SET VAR3 name
SET VAR4 is
SET VAR5 Fred

SET IDX 1
# NEXT:
ECHO ${VAR${IDX}}
SET IDX=$IDX+1
IF $IDX lt 6 GOTO NEXT

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...

Hello,
my
name
is
Fred

EXAMPLE_5:

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:/tmp/log
SET PROMPT "uMON>"
LOG on $LOGFILE
SEND "tfs ls"
LOG off
FILE fstat $LOGFILE
IF $FSTAT sne FILE GOTO ERROR_1
SET LINE 3
SET COUNT 1
ECHO

# DUMP_FILES:
FILE token $LOGFILE 1 $LINE
IF $TOKEN seq \$TOKEN GOTO DUMP_DONE
ECHO " "FILE$COUNT: $TOKEN
SET LINE=$LINE+1
SET COUNT=$COUNT+1
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 set of files currently in TFS; however, here is an example...

uMON>tfs ls
Name                Size     Location    Flags Info
app_01            196752    0xffe2412c   Ec
app_go             68844    0xffe0005c   bEc
monrc                354    0xffe10eac   e
symtbl             77918    0xffe5421c
try                  158    0xffe10dac   e

Total: 5 items listed (344026 bytes).
uMON>
  FILE1: app_01
  FILE2: app_go
  FILE3: monrc
  FILE4: symtbl
  FILE5: try
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. 


EXAMPLE_6:

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).

SET SOUND C:\windows\system32\sndrec32
SET MEDIA C:\windows\media\tada.wav
SYSTEM -pw "${SOUND} /embedding /play /close \"${MEDIA}\""

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...

SET SOUND C:\windows\system32\sndrec32
SET MEDIA C:\windows\media\*.wav
FILE first $MEDIA
# NEXTFILE:
FILE next
if "$FILE" seq \$FILE EXIT
SYSTEM -pw "${SOUND} /embedding /play /close \"C:\windows\media\\${FILE}\"" 
GOTO NEXTFILE

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).

EXAMPLE_7:

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...

IF $SVNREV ge 620 GOTO GOOD_VERSION
DIALOG OK "UPDATE UCON!!!"
EXIT

# GOOD_VERSION:
...