YOS command documentation
help [command]
Prints help text for the given [command]. If no [command] argument is given, it writes down help texts for all available commands in the active directory plus all help texts for commands in directory /commands. Each help text is ended by a new line.
Keep in mind that help texts are usually short because of the memory restrictions in the controller, if you want to learn more about a command preferably use this wiki page.
Return value
When called without an argument, returns the count of all printed out commands. If called with an argument (name of the command), will return 0 if the command is found and printed out and 1 if no command with the given name is found.
Example
AM-felix#>help version
-> version: print meta/version
AM-felix#>
reboot
Reboot the system. This command has no arguments.
echo [arg1] [arg2] [arg3] ...
Prints its arguments to the standard output, separated by space. Could be used in combination with variable evaluation and/or escape sequences(but as decimal numbers).
Examples
| command | output |
|---|---|
echo $permanents/time | prints number of secondns since start to standard output |
echo run: $permanents/time | same as first command, with run: prepended. Example output: run: 11290 |
echo \12 | clears terminal window |
echo \27 | escape - closes terminal window |
delay <n>
Pauses shell from parsing for [n] milliseconds. Argument [n] has to be a positive integer.
Return value
If called correctly returns 0. Otherwise (for example no argument provided) returns -1.
Example
AM-felix#>delay 5000
<paused for 5 seconds>
AM-felix#>
logout
Ends current session and ends shell. After that, auth key for a new administrator login is displayed followed by a usual login prompt. This command has no arguments.
Return value
Returns 0 if executed correctly.
whoami
Prints 8-bit number in hexadecimal format. Write and read access rights of the currently logged user are reflected in this number. Bits 7 and 6 (counting from right to left) represent write rights, bits 5 and 4 represent read rights, and bits 3 to 0 are reserved for future use.
Return value
Returns the same number as it prints.
Example
AM-felix#>whoami
f1
Output f1 in binary is 1111 0001, so the first two bits (here first two 1s) represent write rights, the third and fourth bit (here also 1s) represents read rights, and the rest is unimportant as of now.
ls [-l] [-r] [-f<string>] [directory]
Mimics the usual UNIX ls command. Lists items in [directory]. If no [directory] argument is given, lists active directory. Beware that in our filesystem, we don't use directories . and .. as you'd expect in a UNIX system, so you can't include them in [directory].
Options
-l- list directory in long format (similar to UNIXls -l)-r- will go through the directory recursively.-f<string>- only list state variables containing<string>in their name.
Return value
Returns the count of printed items or -1 if given argument (directory) not found.
Examples
| command | output |
|---|---|
ls | lists items in active directory in standard format |
ls -l misc | lists items in subdirectory misc in long format |
ls -ffoo | lists all items containing foo in their name in active directory |
ls -lrfbar dir | goes through directory dir recursively and lists all items containing bar in their names in long format |
cd [directory]
Changes active directory to the given argument [directory]. If no argument is given, change the active directory to the root directory. Command cd .. changes active directory to the current parent directory - goes up one level.
Example
AM-felix#>cd commands
AM-felix#/commands>cd ..
AM-felix#>cd permanents/total
AM-felix#/permanents/total>cd
AM-felix#>
dump [-h] <data item>
Prints the given <data item> to standard output. Option -h writes the output in
hexadecimal format, bytes are delimited by space. Without this argument, the output is written as a string of ASCII characters, each character for one byte.
It goes from the first byte to the last byte, in a matter of a number it means it goes from LSB to MSB - LSB will be the first written byte.
Return value
Returns the count of successfully dumped items.
Example
AM-felix#>dump permanents/totaltime
#~
AM-felix#>dump -h permanents/totaltime
2f 7e 00 00
AM-felix#>
version [-n] [-h] [-s] [-a] [-d]
Prints version of the device - string consisting of basename, HWID, SWID, and address of the device. Basename and HWID are delimited by colon and space, other identifiers are delimited by comma and space. Only some parts can be printed, this is chosen by options. If multiple options are used, each part is printed on a new line.
Options:
-nprints only the basename-hprints only the HWID-sprints only the SWID-aprints only the address of the device-dprints only the type of the device, in format<class-signature>:<class-string>.
Return value
If option -a is specified, returns the printed address. If option -d is specified, returns the class signature (in the printed string it's the part before the colon). Otherwise returns 0.
Example
AM-felix#>version
AM-felix: esc3-am1f_06dxh0810-A10, VECTOR_2_generic Jun 21 2021, addr: 0
class 10: AM, build target: esc3-am1_default
AM-felix#>version -nha
AM-felix
esc3-am1f_06dxh0810-A10
0
AM-felix#>
uid
Prints unique identifiers of the device - UUID, SN.
Return value
Returns the least significant part of UUID, see example
Example
AM-felix#>uid
UUID: 203932385642571100210034, S/N: 928VBW112134
AM-felix#>echo $vars/retval
2162740 // returned number in hexadecimal is 210034, which corresponds to the leftmost part of UUID
clock [-t<time>] [-d<date>]
If called without the options, it prints the current time in the device. If called with either option (or both), you can set the current time and date. This command will only work if RTC is available on the device.
Options:
-t<input-time>- set the time (hours, minutes, seconds).-d<date>- set the date similarly.
term <dest> <interface> [data]
Starts remote terminal session over desired <interface> to given <dest>. Could be ended by writing quit in the remote terminal. [data] should be a command that we wish to run in the remote terminal. If present, only the given command is run and the remote terminal ends right after that. If [data] is not given, the remote terminal will stay open.
<dest>- address of the target device. It is a number in range0 - 255.<interface>- number of the used interface. For more info on which number represents which interface, look at the Interface IDs table.[data]- command we wish to run on the device we are connecting to. Can be multiple words (meaning spaces allowed).
Return value
Returns 0 if and only if the command was successfully executed.
Examples
AM-felix#>term 0 3 run 0 0
Will connect to a device at address 0 over CAN interface (more info in the interface table), then runs command run 0 0 and disconnect.
AM-felix#>term 0 3
Same as the upper example, but won't run any commands and will stay connected.
send -i<interface> [-n<mode>] -a<address> -f<flags> -s<SID> <data/variable>
Send a message to the given address via the desired interface. The message can be just bytes represented by numbers in range 0 - 255 or a name of a variable, in that case, the whole variable is sent.
-i<interface>- number of the interface that will be used to send the message. For number assignment to the desired interface refer to Interface IDs table.-n<mode>- sets interface, but you are able to set multiple interfaces at once. For more information look below.-a<address>- address of the receiver. It has to be a number in range0 - 255. Address255is used for broadcast messages.-f<flags>- flags for the message. It has to be a number in range0 - 255.-s<SID>- SID of the target service.<data/variable>data- bytes of the message to be sent. You can send more than one byte. Bytes are separated by space. Each byte is represented by a number in range0 - 255.variable- name of the variable we want to send.
Difference between -i and -n
You can declare which interface you want to use with both -i and -n, beware that the latter choice will overwrite the previous. For example, if you choose 3 interfaces with -n and then choose another interface x with -i, x will be the only selected interface.
As you know from the Interface IDs table, each interface has its own number. In reality, these numbers represent bit-positions. For example, CAN has interface number 3, which means that if bit number 3 is 1 then CAN interface will be selected.
When using the -i, you are selecting one interface number, and what internally happens is that we create a number that has 1 (in binary terms) in that specified bit. For example, if you declare -i3, the created number will be 1000 in binary (1 left-bitshifted 3 times).
On the other hand, if you use the -n options, we let you create the final number and give it to us. For example, you can pass -n10. The given number is 10, converted to binary 1010, which means you selected two interfaces, interface numbers 3 and 1.
Return value
Returns 0 if and only if the command was successfully executed.
Examples
Send data over can and after receive them in different device:
send:
AM-felix#>var mydata_tx.8 uint8
AM-felix#>set mydata_tx.0 0x10
AM-felix#>set mydata_tx.1 0x20
AM-felix#>
AM-felix#>send -i3 -f1 -s0x700 mydata_tx
receive:
AM-felix#>var mydata_rx.8 uint8
AM-felix#>
AM-felix#>receive -i3 -f1 -s0x700 mydata_rx
AM-felix#>send -s2 -a7 -i3 15 15 84
Sends 3 bytes (values 15, 15 and 84) to a device o address 7 via interface number 3 and sid 2.
AM-felix#>send -s2 -a7 -i3 vars/ticks
Sends variable ticks in directory vars over the same route.
receive -i<interface> [-n<mode>] -a<address> -f<flags> -s<sid> -t<sid2> [variable]
Starts service that listens for messages incoming from a given address through a given interface. It can receive data (bytes) or variables. When receiving data (by not specifying [variable] argument) and a message comes, it is printed to the standard output (redirected usually to terminal). If [variable] is given and a message comes, the command will load [variable] with the received data.
Running service could be stopped by running the command receive without parameters.
-i<interface>a number of the physical interface to listen. For number assignment to the desired interface refer to Interface IDs table.-n<mode>interface to listen, but you are able to set multiple interfaces at once. For more information look at Difference between-iand-n.-a<address>optional matching address of the sender. It is a number in range0 - 255.-f<flags>optional flags to filter received message datagram with. It is a number in range0 - 255. E.g. to disable link layer decoding, select BROADCAST datagram (-f1).-s<sid>optional matchingsidof the message. E.g. when CAN interface and BROADCAST datagram is selected (-f1), the<sid>value corresponds to the CAN ID.-t<mask>optionalmaskthat defines bits that must match incoming message's SID and the value specified with-s<sid>. If you want-tto have any effect, use it after-s.[variable]an optional name of the variable to store the received data into. The specified variable has to be write-accessible by the logged user.
The syntax is similar to send; we don't pass any arguments when receiving data.
Return value
Returns the number of received messages.
setaddr [-y] <new address>
Sets address of the device to value of argument <new address>. An address is a number in range 0 - 255 and is used in any type of communication with the device. The default address of each device is 0. If the address is changed, change takes place after device restart. Address change is immediately written to the flash memory, there is no need to save this change manually.
The range 0 - 255 is the maximum range, which can be further reduced by the used communication protocol. For example, CAN bus has only 3 bits reserved for address by default (more info in msgconf). This results in an address range 0 - 7. Setting device address beyond these limits will make the device not reachable via the communication interface.
After the device restarts, terminal (or other communication channel from which was the address changed) has to be reconfigured to communicate with the new address.
With -y option present, no confirmation prompt is displayed.
Return value
Returns 0 if and only if the command was successfully executed.
log [data]
Can be called with or without arguments. When called without arguments, prints out the whole log. If [data] is present, [data] is logged to the device's internal flash memory. [data] can be multiple words (strings separated by whitespace).
If the log file is full, the oldest data will be overwritten.
Return value
Returns 0 if and only if the command was successfully executed.
proclog [r/p/s]
Record or playback previously recorded plot activity.
proclog rstarts recording data redirected to it withplot -l ...continuously.proclog pplayback the recorded data. You can view the data in scope. Playback will stop automatically when the data is fully transmitted.proclog sstops the recording or playback.
Return value
Returns proclog's status number. 1 is recording or occupied, 0 is ready/idle and so on... #TODO
vr [-r] [-f<string>] [path1] [path2] ... [pathN]
Tool for printing dynamic variables. When run without any arguments prints all dynamic variables in directory vars/.
-r- will go through the directory recursively.-f<string>- will only list variables that contain<string>in their names.[path1] - [pathN]- Can be a path to a directory, in that case, lists all dynamic variables in that directory, or can be a path to a dynamic variable, then lists just the one variable. Can be either path fromvarsor a relative path from the active directory. You can say it has a default valuevars, meaning it will list directory/varsif no argument[path]is given.
Return value
Returns number of printed values. Return -1 if no variable with the given name was found and -2 if there exists an entry with the given name but it is not a dynamic variable.
var <name1> [name2] [name3] ... [nameN] [type]
Create dynamic variable (or more variables) with name <name1> ([name2], [name3] ... ) in directory /vars. Variable (variables) exists until YOS device is restarted. Created variable type is defined by the last parameter of command - [type] parameter. Supported variable types are:
Types
| type id | description |
|---|---|
| int8 | signed, 8-bit integer, range -128 - 127 |
| uint8 | unsigned, 8-bit integer, range 0 - 255 |
| int16 | signed, 16-bit integer, range ?32,768 - 32,767 |
| uint16 | unsigned, 16-bit integer, range 0 - 65,536 |
| int32 | signed, 32-bit integer, range ?2,147,483,648 - 2,147,483,647 |
| uint32 | unsigned, 8-bit integer, range 0 - 4,294,967,296 |
| float | 32-bit number with floating decimal point |
Note: Allowed types are also int64, uint64, double, and string, but beware that these types are not fully supported yet and are mostly useless.
Return value
Returns 0 if and only if the command was successfully executed.
Arrays
With var you can also create arrays. To create an array of length N substitute any [name] with [name-of-array].N. So the final command can look something like this:
var myarray.10 int32
This creates an array of 10 int32s. To access elements in the array write name-of-array.i where i is the wanted index. Some examples of working with arrays:
AM-felix#>var myarray.10 int32
AM-felix#>set myarray.0 130
AM-felix#>set myarray.3 260
AM-felix#>echo $vars/myarray
130,0,0,260,0,0,0,0,0,0
AM-felix#>echo $vars/myarray.3
260
AM-felix#>
set <var1> [var2] [var3] ... [varN] <expression>
Sets the variable to value specified by an expression. Overflows can happen! Also, remember that no whitespace in <expression> is allowed!
The expression is C-style string format which can contain braces, operators, variables, and constants. The expression is evaluated in a floating-point scalar and considered valid when the result is nonzero. If the bitwise operators are used in the expression, it is evaluated in a 32-bit fixed-point scalar. The operators can be: *, : (for division) , +, -, >, <, >=, <=, ==, !=, &&, ||, &, |, ^. If the output should be a boolean value, we convert 1 for true and 0 for false. The expression is evaluated from the left to the right and operators are not prioritized. If a priority is required, the user must specify that with braces. 3+5*4 needs to be entered as 3+(5*4).
When setting an array of variables, values are delimited by , (comma) without any whitespaces. Following command starts to set values of variables in the array from the first position - position 0 (indexing starts from 0):
set [name of array] value0,value1,value2...
Not all values have to be assigned, setting the first 3 values of an array with length 10 is ok, the remaining values will be untouched.
Return value
Negative values are for errors, if a positive value is returned then it represents the count of successfully set variables.
Some error code mappings, other codes can be expression parsing errors or others:
| retval | meaning |
|---|---|
-100 | no enough arguments |
-101 | settable variable not found |
-102 | write restricted |
-105 | desired value too low |
-106 | desired value too high |
-107 | desired value is not allowed |
Examples
| command | description |
|---|---|
set f (q/180)*3.141592654 | Converts value q from degrees to radians and saves it to f. |
set i i*i | Squares i and saves it to i. |
set ret i>17 | If i is greater than 17, ret will be 1. Otherwise ret will be 0. |
set myarray 1,2,3 | Sets first 3 values of myarray to 1, 2 and 3, assuming myarray is an array. |
format [-b<base>] [-p<precision>]
Set default input/output format for the numbers in the Term tool. Different output formats can be selected by following options:
-b<base>- set the base for input/output format of integer numbers.-b8for octal format,-b16for hexadecimal, and so on.-p<precision>- set the precision for float numbers. Positive values select the number of rounding digits. Negative values select the scientific notation, where the value selects the count of valid digits.0select default settings.
Return value
A negative value meaning an error occurred. 0 means successful execution.
pr [-r] [-f<string>] [-d] [path1] [path2] ... [pathN]
Tool for printing parameters. When run without any arguments prints all parameters in the current directory.
-r- will go through the directory recursively.-f<string>- will only list variables that contain<string>in their names.-d- won't print out parameters that have default values.[path1] - [pathN]- Can be a path to a directory, in that case, lists all parameters in that directory, or can be a path to a parameter, in that case, lists just the one parameter. Can be an absolute path (starting with/) or a relative path (without/at the beginning). If no[path]is given, lists all parameters from the current directory.
Return value
| retval | meaning |
|---|---|
-2 | given argument is not a param |
-1 | given argument not found |
| any positive value | number of printed parameters |
Example
AM-felix#>pr # list all parameters
List of available params:
-> sampling_time uint8 : 100 (100), Interval for sending msg from driver API
-> mode_forward uint8 : 2 (2), Driver mode when cmd is positive
-> mode_reverse uint8 : 8 (8), Driver mode when cmd is negative
Total 3 entries
AM-felix#>pr -fmode # list only parameters containing "mode" in their name
List of available params:
-> mode_forward uint8 : 2 (2), Driver mode when cmd is positive
-> mode_reverse uint8 : 8 (8), Driver mode when cmd is negative
Total 2 entries
AM-felix#>pr -d # list only non-default parameters
List of available params:
Total 0 entries # all my parameters are default
restore [-y] [-r] [-f<string>] [-m] [-M] [-s] [-p<n>] [path1] [path2] ... [pathN]
Restores the given parameters or directories to preset values. If run without arguments, it restores all parametric variables in the active directory recursively.
Options:
-y- no confirmation prompt is displayed.-r- won't list parameters recursively.-f<string>- only list parameters containing<string>in their name.
Preset options:
-m- will set parameters to theminpreset.-M- will set parameters to themaxpreset.-s- will set parameters to thesteppreset.-p<n>- usable only if the given parameter has more presets thandefault,min,maxandstep.-p1will use the first extra preset,-p2the second and so on.
Arguments [path1] [path2]... [pathN] correspond to the directories and parameters we want to restore. If no argument is given the command goes through the active directory recursively.
Return value
| retval | meaning |
|---|---|
-1 | given parameter not found |
0 | no parameters restored |
| any positive value | number of parameters restored |
Example
AM-felix#>restore # restore all params to default values, recursively
restore params to 0 (y/n)? : y
93 entries done.
AM-felix#>restore -ry # restore params only in the active directory, and auto-confirm
3 entries done.
AM-felix#>restore -My # restore all params to max value, where possible
40 entries done.
save [-d] [-b] [-e] [-y] [parameter]
Save parameters to backup or user storage. If [parameter] is not given will save all the parameters. When you specify [parameter], the only option that will be significant is -y and you will always save into your userstorage.
Options:
-b- if specified will save tobackupinstead ofmainstorage.-d- will print hash size and hash as if it was saving the data to storage, but won't save anything. stands for dummy.-e- erase userstorage.-y- no confirmation prompt is displayed.
Return value
Negative values stand for errors while saving. When saving given parameters as arguments to userstorage, return value should be 0. When saving everything (no arguments) returns the hash of the saved files.
Examples
AM-felix#>set mode_forward 3
AM-felix#>save
save params to main (y/n)? : y
309 bytes, #05f3 hash
AM-felix#>
Set mode_forward to 3 and save it to the main flash memory. If no save was run after the assignment, after reboot the change would be lost.
AM-felix#>pr mode_forward # check the current parameter value
-> mode_forward uint8 : 3 (2), Driver mode when cmd is positive
Total 1 entries
AM-felix#>set mode_forward 5 # set mode_forward to a different value
AM-felix#>save -y mode_forward # save the parameter to userstorage
saving 1 bytes
AM-felix#>reboot # reboot the device
...
AM-felix#>pr mode_forward # check the parameter value after reboot
-> mode_forward uint8 : 3 (2), Driver mode when cmd is positive
# i didn't save the value so the previous value got loaded after reboot
Total 1 entries
AM-felix#>load -y mode_forward # load parameter from userstorage
AM-felix#>pr mode_forward
-> mode_forward uint8 : 5 (2), Driver mode when cmd is positive
Total 1 entries
Example using userstorage and the optional argument with save and load.
load [-b] [-d] [-y]
Loads parameters saved in the flash memory. It restores recursively all parametric variables all directories and all subdirectories.
Options:
-b- load values frombackupinstead frommainstorage.-d- will print hash size and hash as if it was loading the data from storage, but won't load anything. stands for dummy.-y- no confirmation prompt is displayed.
Return value
Negative values for errors, 0 when aborted at prompt and positive values for a number of bytes restored.
Examples
AM-felix#>set mode_reverse 40 # mistakenly set mode_reverse to 40
...
AM-felix#>load -y # restore mode_reverse to its saved value
309 bytes, #5725 hash
AM-felix#>pr mode_reverse
-> mode_reverse uint8 : 8 (8), Driver mode when cmd is negative
# mode_reverse is now back 8
Total 1 entries
AM-felix#>
st [-r] [-f<string>] [-p<period>] [path/state variable] ...
Prints the given state variable or all state variables in a given directory. If no argument is given, the command prints all state variables in the active directory. The command can take multiple arguments.
-r- will go through the directory recursively.-f<string>- only list state variables containing<string>in their name.-p<period>- prints the state variable(s) every<period>miliseconds.<period>has to be a positive number. The printing can be stopped withCtrl+cor issuing commandst.[path/state variable]- If specified, will print out that state variable, or if the path leads to a directory, all state variables in that directory. There can be more than one argument of both directories and variables. If no argument is given will use the active directory as default.
Return value
Returns number of printed values. Return -1 if no state variable with the given name was found and -2 if there exists an entry with the given name but it is not a state variable.
Examples
AM-felix#>st driver/energy -p500 # will print twice a second state variable driver/energy
AM-felix#>st -rfgpio # will list current values of all state variables with gpio in their name
pm [-r] [-f<string>] [path/permanent variable]
Tool for printing permanent variables and their values. If an argument is specified, will print out that permanent variable, or if a path to a directory is given, all permanent variables in that directory will be printed. There can be more than one argument of both directories and variables. If no argument is given pm will use the directory /permaments as default.
Options
-r- will go through the directory recursively.-f<string>- only list state variables containing<string>in their name.
Return value
Returns the number of printed permanent variables.
Examples
AM-felix#>pm # lists all perm. variables in /permanents
AM-felix#>pm -rfmax # lists all perm. variables containing 'max' in their name recursively
AM-felix#>pm time ttl permanents/single_run
AM-felix#> # lists variable time, ttl, and all variables in permanents/single_run
pmlog
Prints history of permanent variables. This command has no arguments.
Return value
Returns 0 when successfully executed, -1 when an error occurred.
-#--
script [p/h/r/s/q/e]
Tool for manipulating the internal script. If run without an argument will prompt the user to type the script and end it with quit. This action will overwrite the internal script if there is one present on the device.
Each device can hold only one internal script at a time, so if you want to run another script you have to overwrite the current one. A script is a list of YOS commands along with code flow operators.
Arguments
p- prints out the current script, its size, and hash. Hash is also returned.h- prints out only the size of the script and its hash.r- returns script rights. Non-zero if the script is running.s- starts/restarts the script.q- quits the script.e- erase the current internal script.
Return value
Returned negative value stands for error either while executing or stopping the script or for passing an unknown argument. 0 is returned when executed successfully.
Example
AM-felix#>script # create a new script and save it
enter internal script, type 'quit' to exit
echo ahoj
echo cus
quit # end the script with quit
total 20 bytes
AM-felix#>script p # print the currently saved script
echo ahoj
echo cus
# total 19 bytes, #F3E7 hash
AM-felix#>script s # run the internal script
ahoj
cus
AM-felix#>