Skip to main content
FW version: Stable

Persistent script management

this tutorial shows how to augment the device's functionality by installing persistent scripts.

info
  • Let's presume that a successful comlink with the device was already established (the device is connected, connection options were set, the driver was installed, etc.)
  • Let's presume that you are familiar with the YOS scripting.

How does it work​

The script is a text file that contains code in the language of the YOS/Shell interpreter. As mentioned, each device offers to permanently install a script inside its FLASH memory. Such code is executed automatically after a successful boot and it can augment the functionality of a firmware application. The YOS command script serves to manage the internal persistent script.

Usually, the steps are:

  • Code your script first,
  • execute, evaluate and tune your code first with run-time loading,
  • repeat until the desired behavior is reached.
  • Load the finished, tuned code permanently with script command
  • test the device with the loaded permanent script,
  • repeat the loading for other devices, if necessary.
warning

A persistent script alters the functionality of the controller and the whole vehicle. The augmented vehicle can be potentially harmful and cause injuries. siliXcon disclaims any liability for property or health losses caused by custom-made persistent scripts.

Example code​

Let's code up a sample YOS script for the AM controller with the following purpose:

  • beep with the motor each time there is a rising edge on the DIN input
  • make a log each time the temperature reaches 90 degrees

var temp_reach int8
set temp_reach 0

{
  var last_sample sample int32

  #sample the input DIN1 (see relevant datasheet)
  set sample (/common/din.0!=0)

  #detect the edge and beep
  if (sample)&&(!last_sample) beep 50

  #remember last state
  set last_sample sample

  #sample the controller temperature
  set sample /driver/temp

  #compare with the threshold and log
  if (sample>90)&&(!temp_reach) {
     log Temperature reached, time $/permanents/time s
     set temp_reach 1
  }

  #repeat
  branch s
}

#The loop has ended (the user has terminated with ctrl+c).
#Let's print out the entire log if the temp was reached this run :
if temp_reach {
    echo
    echo =================================
    echo Temp reached this time, full log:
    log
}

info
  • The persistent script is not run in the service mode, e.g. if the util initialization fails. For exp. script will not be run if the driver ends up with pre-init error.
  • The device runs the persistent script with the rights of its installation session.
  • The device ends the script when it receives an interrupt signal (ctrl+c pressed in term).

How to install to FLASH​

Let's assume that your code has been tested enough with run-time loading (e.g. copy-pasting into the term tool or executing it as a stand-alone file from your computer). Then, the script command may be used for installing the code persistently. Please refer to the relevant documentation.

With the device's CLI and term​

Simply typing the script command to the term initiates recording to the FLASH. Once a quit token is then received, the parsing is ended and the record is finalized. Therefore, you only need to wrap the code with script and quit keywords. You can use these directives to install the script manually from any CLI console:

script

#
# ... enter your code here ...
# ... or use the previous example ...
#

quit

Note that user must be logged in and the session must be active. With the term, the preprocessing directives may be used to prepare the environment: wait for the device, log in, etc. In such a way, the full installation is handled automatically. An installer script may look like this:

@c #send interrupt - terminate running script (if any)
@w #wait for shell process to be responsive (and no script is running)
@! #do automatic log-in

script

# Either enter your code here or insert the code from another file:

@i bare_script_file_name.ys

quit

With the emGUI or yosctl​

warning

This method doesn't use term tool but directly installs the bare source code without running the preprocessor. If your script contains preprocessing directives, use the previous method.

You may invoke the script manager from the node's context menu in emGUI. The currently installed bare script code will be displayed and available for editing. You can paste your new bare code into the input box and click install. Moreover, this manager monitors the script execution within the device and provides basic control:

term

Alternatively, a batch tool installscript is shipped within the standard SWTools installation. It invokes script command with yosctl. So, to install your script programmatically and safely, open a Windows console and type:

installscript file_with_my_bare_code.ys

How to view and erase the installed script​

The script command has several modules for such a purpose. Let's introduce two of them:

  • script p to print the currently installed script
  • script e to erase the currently installed script

The following gif first shows an installation of a simple Hello, world! script. Then it prints the recorded code back:

term

tip