Skip to main content
FW version: Stable

term

info

Any CLI tool has an embedded manual page. To view it, execute e.g. term -?

tip

The term tool provides an interface to the device's CLI. That is different from your operating system's CLI (Windows CMD, where e.g. the term can be invoked from). This sometimes creates confusion. Do not mix these two environments.

term is the most fundamental tool in the set of SWTools for accessing a siliXcon device. It provides access to the standard input and output of the device. term is simply forwarding the characters back and forth. All the processing (apart from keyboard shortcuts and control characters) is done on the device itself.

term window

CLI options​

In addition to the shared connection options, the user can specify debug and verbosity levels, return value offset, define a macro, issue a script to run and more. Please refer to term -? to get the option description.

Keyboard shortcuts​

For simplicity, term offers several hard-coded keyboard shortcuts:

  • CTRL+X to reboot the entire mesh
  • CTRL+R to reboot the target node
  • CTRL+Z to schedule target node debug info
  • CTRL+C to send the interrupt signal
  • CTRL+W to wait for the target shell process
  • CTRL+A to (re)authenticate automatically
  • CTRL+S to run the external real-time SCOPE
  • CTRL+G to run the external GUI
  • CTRL+L to run the secured remote BOOTLOADER
  • ALT+F(n) to edit a linear script n
  • F(N) to run a linear script n
  • ESC to exit with zero

Flow control​

Flow control is implemented in the STREAM service, which is used by the term. When the input buffer of the device is almost full, the STREAM service sends the XOFF character to ask the term to wait. When the buffer is almost empty, the STREAM service sends the XON character to ask the term to continue sending data. This feature is usually used when a larger chunk of text is sent to the device.

Control characters​

Apart from flow control characters, term reacts distinctively on some incoming character codes (decimal):

  • \26 : begin to parse decimal return value
  • \27 : exit
  • \11 : set cursor to home position
  • \12 : clear the screen

How to control term from the device using escape sequences:

  • echo \12 (NP norm feed, new page) clear terminal window
  • echo \27 (ESC, escape) close terminal window
  • echo \26 $variable-name when term ends, it returns the value of the variable-name.

Scripts​

term has the capability of preprocessing and forwarding scripts to the device. The script is a text file that contains code in the language of the YOS/Shell interpreter. The term has a preprocessor that compresses spaces, skips empty lines and comments (denoted with #) and parses lines beginning with @ (these are preprocessing directives}.

Preprocessing directives​

inside a script file, a special character '@' is reserved that identifies the preprocessing directive (control sequence for term binary). A line beginning with @ is not sent to the device, but processed locally. The preprocessing directives are automation alternatives to the keyboard shortcuts.

Script preprocessing directives:

  • @! [credentials] machine login. The argument is in the format of username:password. If the password is omitted, term tries to figure out the password automatically using the auth tool. If the both username and password are omitted, default username (called guest) with the lowest access rights is used.
  • @s run the external real-time SCOPE
  • @g run the external GUI
  • @r reboot the target
  • @x reboot the entire mesh
  • @m minimize the console window
  • @w [timeout:retval] wait for the target shell process (optionally, after the timeout, end with retval)
  • @i [filename] include a script (filename)
  • @c send the interrupt signal
  • @q [retval] end (with optional retval)
  • @d [TOKEN] (: [VALUE]) to define macro 'TOKEN' to value 'VALUE' (value is optional)
  • @f [TOKEN] ifdef 'TOKEN', continue execution until @e)
  • @n [TOKEN] ifndef 'TOKEN', continue execution until @e)
  • @e endif

To evaluate a MACRO:

  • insert [TOKEN] into your script file. The value of macro 'TOKEN' will be evaluated here

Return value forwarding​

as mentioned above, a special incoming character of \26 will invoke the reception of a return value. In such a way, the return value from the device may be passed to the local caller of the script. Let's explain through an example:

Content of 'myscript.ys' (YOS/Shell code, running in the device):

var ret #create a variable
set ret 12345 #fill it with some value
echo \26 $ret \27 #pass that value to the term tool (and make it quit)

Content of batch file 'test_myscript.bat' (Windows batch, running in the PC):

term myscript.ys
echo %ERRORLEVEL%

Now, we have the value (12345) printed out to the local console.

Preset scripts​

Up to 12 scripts could be mapped to keys F1 ... F12. These scripts must be saved in a working directory (where the term was invoked). Such script could be run by pressing the corresponding F(n) key when term is running. These preset scripts can be also edited in the system's default text editor by pressing Alt+F(n).

Script as an argument​

Following options (start with '-'), the term arguments are regarded as optional names of a script file. A script file is processed right after the term starts. Script files usually have .ys extension. If the SWtools package was installed properly, this extension is associated with term and the script can be run by double-clicking the file.

Example:

# run the file scripts/hello-script.ys on the device with address 0

set addr=0
term scripts/hello-script.ys