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 BIN2DM BMPVIEW CATCH CD COMPORT
CLS CONFIG CONNECT DIALOG ECHO EVENT EXIT FILE
FKEY FSEND GOSUB GOTO IF LOG LUA MONCMD
NEWMON AVRLOADER RECV REGEX RETURN RUN SEND SET
SHELLEXEC SLEEP SOCKET STRING SYSTEM TCP TFTP TIME
SENDINPUT

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

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.

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.


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


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