uCon HomePage

Script Cmd: RECV


RECV [-aAcCnt:xX] [arg1 | subcommand]

This command allows the script to wait for some sequence or block of characters.  When initially written, it was essentially an extension to the "wait" portion of the SEND command; over time it has grown in usefulness and complexity...

New as of Jul, 2012: 

New as of Apr, 2014

New as of May, 2016:

Subcommands:

blkinit [size]:     reset the pointers used by recvblock functionality and clear the RECVBLOCK variable
                    if 'size' is specified, then use that as the newly allocated receive block.
blkcpy [fname]:     copy the received block to the shell variable RECVBLOCK.
                    If 'fname' is specified, then also copy  received block to that file.
                    See note3 and '-a' option below.
idleline {msecs}:   wait for 'msecs' milliseconds of idle line.  See note4 below.    

Options:
-a              used with 'blkcpy' subcommand, convert binary RECVBLOCK to ASCII-coded-hex
-A              used with 'blkcpy' subcommand, convert ONLY CR to 'C' and LF to'L' in RECVBLOCK
-c              automatically do a 'blkcpy' after the specified character stream is received
-C              automatically do a 'blkcpy' and 'blkinit' after the specified character stream is received
-n              used with 'blkinit', this disables the circular queue as RECV is accumulating data
                (terminate when buffer is full).
-t {seconds}    specify some number of seconds after which RECV will giveup waiting
                for a prompt (see note below)
-X              wait for some number of characters as specified by arg1
-x              treat arg1 as a character sequence of ascii-coded-hex and wait for
                that binary stream.

If the -t option is used in this command, then upon completion, the shell variable SCR_TIMEOUT will be loaded with either "TRUE" or "FALSE". The script can use this to know if a timeout actually occurred (SCR_TIMEOUT="TRUE") or the command received what it was expecting to receive within the allocated time (SCR_TIMEOUT="FALSE").

NOTE1: -x and -X options are mutually exclusive. Don't use both in one command instance.

NOTE2: the subcommands 'blkinit' and 'blkcpy' are used exclusively, and aside from '-a & -A' with 'blkcpy' and '-n' with 'blkinit', should not be mixed with other command line options.. 

NOTE3: the RECVBLOCK shell variable is cleared by 'blkinit'.  It is only populated when blkcpy transfers characters to it.  The actual number of characters (could be zero) transferred to RECVBLOCK is stored in the shell variable RECVBLKTOT.  

NOTE4: uCon's ability to detect small (<25msec) bursts of idle time on a serial port depends heavily on the CPU.  The smaller the burst to detect, the more likely you'll need a reasonbly high-end PC to succeed.  While generally speaking 25msec is not very short for embedded systems, it is tricky to detect this through a windows application.  The best I've acheived is detection of about a 15msec burst running uCon on a quad-core I5 host; so, your results may vary.

NOTE5: when blkcpy is run without -a or -A, the buffer is first scanned for nulls (0x00) and if found, replaced with "<0>" so that the buffer can be processed as a string..

NOTE6: since the -n option changes the way RECV accumulates data from the target; it only makes sense to use with with the 'blkinit' subcommand. 

Example 1:

This script subroutine will simply wait for 10 characters to be received:

#####################
# WAIT4_TEN:
#
RECV -X 10
RETURN

Example 2:

This script subroutine will wait for the string "hello_there":

#####################
# WAIT4_HELLO:
#
RECV "hello_there"
RETURN

Example 3:

This script subroutine will wait for the binary ACK-EOT character sequence (0x06 0x04):

#####################
# WAIT4_ACK:
#
RECV -x 0604
RETURN

Example 4:

Similar to example #2, this script subroutine will wait for the string "hello_there", but it will populate the RECVBLOCK shell variable with most recently received block of characters around that string

#####################
# WAIT4_HELLO:
#
RECV blkinit
RECV "hello_there"
RECV blkcpy
RETURN

Example 5:

This script subroutine will retrieve the target's prompt and store it in uCon's PROMPT shell variable:

#####################
# GET_MY_PROMPT:
#
RECV blkinit
SEND -n ""
SLEEP 2000
RECV blkcpy
STRING precut "$RECVBLOCK" 3              # Chop off initial whitespace
IF "$STRING" seq CVBLOCK GOTO GET_MY_PROMPT
DIALOG YES_NO "PROMPT = ${STRING}, OK?"
IF $DIALOG seq NO GOTO GET_MY_PROMPT
SET PROMPT $STRING
RETURN

Example 6:

This script takes each received character and echoes it back out the port until 'X' is received:

#####################
# LOOP_TILL_X:
#
RECV blkinit

# Get next incoming character and transfer it to
# the RECVBLOCK shell variable:
# LOOP:
RECV -CX 1
IF $RECVBLOCK seq X goto GOT_X
SEND -nc "$RECVBLOCK"
GOTO LOOP

# GOT_X:
ECHO TERMINATING!
EXIT