Functional description

When an ASCII stream is captured by the device, it goes through the communication stack (using STREAM service from our service protocol) and then it is passed to the YOS/Shell interpreter. On the first layer, each YOS instance runs a simple line editor that handles ASCII control characters (such as Backspace, DEL, TAB, arrows, etc.). These allows the user to perform a typical line editing before return character is received and the entire line processed cannonically. Shell then splits each incoming line into space-separated tokens, evaluates variables (stringification expansion) and runs commands. If the Shell receives the start-of-code-block (character {), it doesn't run the next commands immediately. Instead, it saves the bulk text into a buffer, until the last of the nested end-of-code-block (character }) arrives. Afterward, the entire block is executed at once.

Shell

Shell is process running inside controller. It parses text from standard input and interprets it, shell is not case sensitive. Shell always works with one line of the text, this line is ended by character [CR] (0x0D in hex)1. When line of text is fed into the shell, it starts to interpret it from right to left. Text is divided into a tokens that are delimited by space. The most left token is considered to be a name of the command to be run, other tokens are considered to be parameters and they are passed to the command. Before the command is run, shell deals with all special characters in the parsed text. These special characters and their function is described in the corresponding sections. Line of text consists of tokens: token0 token1 token2 ... tokenN[CR]

• token0 : name of the command to be executed
• token1 ... token N : command arguments
• [CR] (0x0D in hex) : confirmation character

Default system shell is connected to the predefined interfaces as part of communication protocol. The STREAM service forwards its input and output over the selected interface.

Login prompt

Each time, before shell is started, login prompt is printed into terminal. User is first asked for user name and after that for password. The user name is not case sensitive. Default guest login is guest and password guest. The username and password can be also provided in an one-line token form: username:password as an answer to the login prompt. Privileged access is protected by password (token) that is predefined or dynamically generated by authenticating service, which must be negotiated before login prompt (using a different service).

Login as:
Password:

info

Login prompt can also be skipped by sending character "!", optionally following by the username:password, switching the CLI into machine login mode.

Shell prompt

When the shell is ready to parse the next line of the text, it writes a prompt. Prompt consists of device basename followed by character #, then is printed current working path, and prompt is ended by character >. Example of prompt:

AM-felix#/driver>

Prompt, as was described above, could be simplified (only character >) by choosing machine login mode. This simple prompt is used when YOS device is controlled over CLI by another device (such as PLC), or for automated scripting. It simplifies parsing text that is comming from device to supperior system. For reliable operation in machine login mode, before login is sent (or skipped), the YOS device should also be acknowledged of start of communication. This is done by sending newline (with no other text) before login is sent or skipped or using the low-level control characters.

Session control characters

Some additional, low level characters are reserved for achieving the CLI automation, to simplify the command synthesis and output parsing on the other side, as well as synchronization of the input/output buffers. Those are:

• 0x04 [ENQ] ask for session log-out
• 0x05 ask for log-in as default user in the machine login mode
• 0x07 [BEL] ask for handshake. The system will reply either with 0x06 when logged in or 0x05 when logged out.
• 0x11 [XON] flow control ON (handled by the stream service)
• 0x13 [XOFF] flow control OFF (handled by the stream service)

Shell editor

Some characters are processed directly by the shell and they are not passed as arguments to the command that is going to be run. These characters also can not be used in command names. These characters are useful for scripting:

• # comment: text that follows the character # is considered to be a comment and is ignored until the end of the line.
• [tab] tabulator: it is used for text autocompletion. If multiple valid possibilities exist, they are cycled by sending [tab] repeately.
• [left arrow]: moves the text cursor to the left.
• [right arrow]: moves the text cursor to the right.
• [up arrow]: shows last entered command.
• [backspace]: erase the character before the cursor.
• [del]: erase the character after the cursor.
• [insert]: switches between insert / overwrite edit mode.
• [home]: puts the cursor to the line begin.
• [end]: puts the cursor to the line end.
• " " quotes: delimit characters. The token may hold special characters when they are contained within the quotes.
• ( ) braces: delimit tokenization. The token may hold spaces when they are contained within the braces.

Token expansion (stringification)

The shell provides a special syntax for expression evaluation (expressing the content of variables, etc) within the token. The expansion is triggered when a token contains the $ character. The rest of the token is then considered as a stringification directive. Such substitution is especially useful when the user wants to pass a non-immediate argument to a command. When using the $, the expansion is done by the shell, and the value is first converted to a string before being passed on. The command then receives the expanded string. Please refer to the stringification page for more information.

Executing a command

When running a command, the shell is first looking for this command in the active directory, then it searches in directory /commands (similar to system variable $PATH in other OS). Commands located in a directory /commands are globally available in the system and can be run just by typing their name without the need to write the full path. After the command is executed, the shell writes a prompt as confirmation, that the command ended and the shell is ready to accept the next line of text. Command, that was just executed, writes its return value to special parametric variable /vars/retval. Usually, if the variable's value is zero or positive, the previous command is completed without error. A negative value of the retval is used when some error occurs during command execution. In addition, the command itself could print an error message into standard output, before the shell prints the prompt.

Block execution

Shell is able to run a whole block of commands at once. When it finds the beginning of the block ({ character), it pauses the execution of the following commands until it receives the end of block (} character). All commands in the block are buffered and run from beginning to end when the block is ended. Subblocks of the code can be created inside the main block beginning by first {. These subblocks are also started by character { and ended by character }. When scripts are used in the YOS device, blocks and subblocks of the code are used to navigate inside the scripts by branch command.

• { block begin: this character denotes the begin block of the code block. It should be placed at the beginning of the new line and no other text should follow the character on the same line.
• } block end: this character denotes the end of the code block/subblock. It should be placed at the beginning of the new line and no other text should follow the } character on the same line.

Limitations

The structured text is interpreted in a small microcontroller with limited resources. Moreover, the YOS system avoids dynamic memory allocation (to approach autoSAR standards). Therefore, several limitations have to be kept in mind when designing the script code (note that these may vary depending on the installed microcontroller):

• line length should not exceed 100 characters
• the maximum space-separated token count is 10 per line
• the maximum number of tokens for stringification evaluation is 4 per line
• the maximum size of the in-line stringification evaluation is 32 characters
• maximum total size of all code blocks (incl. functions) is ~8000 characters
• maximum total size of all dynamic variables (incl. descriptor objects) is ~6000 bytes
• the size of the internal script storage is ~16 kb
• execution speed is usually limited to a few lines per millisecond (depending on the system load)