Skip to main content
Firmware Stable

Interface manipulation commands

msgconf [-y] [interface] [cfg0] [cfg1] [cfg2] [cfg3]​

Configures the link layer of communication interfaces — physical speed, timing, and datagram composition options. For network-layer settings (service protocol enable/disable and SID remapping), see protoconf.

Printing the configurations​

Command msgconf [interface] prints the configuration of the given interface. Command msgconf prints all the interfaces and their configurations in a shorter format.

Setting the configurations​

Command msgconf [interface] [cfg0] [cfg1] [cfg2] [cfg3] sets [interface] to given configurations [cfg0], [cfg1], [cfg2] and [cfg3]. If the [cfg1] - [cfg3] values are not entered, zeroes are configured (as defaults). If only [cfg0] is given, it is taken as a single 32-bit number. The special values for these numbers are: 0 - disable the current interface and ?1 - set the given interface to the release-specific default configuration.

  • [interface] is a 4-bit number that identifies the communication interface. The numbers assignment is listed in the table below.

  • [cfg0], [cfg1], [cfg2] and, [cfg3] are four 8-bit numbers in the range 0 - 255 that specify the setting of the communication interface. If these four numbers would be merged into one 32-bit number, [cfg0] would be the LSB, and [cfg3] would be the MSB.

  • Option -y will auto-confirm the changes (otherwise a (y/n) ? prompt will appear).

Interface IDs​

[interface] numberInterface
0SWD
1UMSG/UARTCOM
2UMSG2
3CAN
4CANEXT
5UMSG3/UARTEXT
6UMSG4
7USB
8NRF24
9BLUETOOTH
10UDP
11LIN
11LIN2
13LIN3

Interface-specific configuration​

This section covers only the most common interfaces and their typical use cases. For greater detail, please refer to siliXcon.

CANx​

Description of how to read and set configuration for the CAN Interface ([interface] number 3 or 4).

  • [cfg0] - indirectly sets the speed of the interface. It is a prescaler of the maximum CAN speed - 2 Mbps. Possible values and their meaning is in the table below.
[cfg0] valueSpeed
12 Mbit/s
21 Mbit/s - default setting in most releases
4500 kbit/s
5400 kbit/s
8250 kbit/s
10200 kbit/s
16125 kbit/s
20100 kbit/s
  • [cfg1] - configures the CAN timing. The value 0 is default and other values are reserved for further definition.
  • [cfg2] - configures the (n) bits used for the transmitter address in the CAN ID for unicast and multicast messages. If this value is set to 0, a default value of n = 3 is used. Other values are reserved for further definition. See the CAN ID calculator to visualize how changing n affects the CAN ID space.
  • [cfg3] - reserved for further definition.

UARTx​

  • [cfg0] - sets baud-rate of selected UART interface in the following way:
[cfg0] valueBaud rate
81200 bps
92400 bps
104800 bps
119600 bps
1219200 bps
1338400 bps
1457600 bps
15115200 bps
16230400 bps
17460800 bps
18921600 bps
  • [cfg1], [cfg2] and [cfg3] - configure the UART mode and timings. The default values are 0 which denotes the 8 bits, no parity, and 1 stop bit. Other values are reserved for further definition.

Return value​

When called with arguments, returns the current or set value of that interface. When called without arguments returns 0.

Examples​

CommandDescription
msgconf 3 8 0 4 6sets speed od first CAN interface to 250 kbit/s with default timing, uses 4 bits for transmitter address in CAN 2.0a and 6 bits for transmitter address in CAN 2.0b
msgconf 3 -1sets the first CAN interface to release-specific default configuration
msgconf 3 0disables the first CAN interface
msgconf 3 4sets the speed of the first CAN interface to 500 kbit/s (other configuration remains default)
msgconf 1 15 0 0 0sets UART COM to baud rate 115200 bps, 8 bits, no parity, and 1 stop bit (115200 kbps is the default setting in most releases). Zeroes at the end could be omitted, command msgconf 1 15 has the same effect

msginit <interface> <cfg0> [cfg1] [cfg2] [cfg3] [-y]​

Works similarly to msgconf (for more info look above), but only for setting the configuration. The only difference is that msginit DOES NOT save the changes to flash memory. This means that the changes you make with msginit will be lost after reboot.

msghost [-e/-d] <dest> <interface>​

Changes the host address to <dest> and specifies over what interface will the communication take place. In other words, redirects the communication with the host (for example SWTools) to the specified address over the specified interface.

  • <dest> - address of the target device. It is a number in range 0 - 255.
  • <interface> - number of the used interface. For more info on which number represents which interface, look at the Interface IDs table.

With options -e (short for enable) / -d (short for disable), you can disable/enable the stream output from the controller to the host. The controller will save the unsent data to a buffer (buffer has limited storage), and send it after the stream output is enabled again (with -e). When not specified the option stays as is.

Return value​

Returns 0 if and only if the command was successfully executed.

protoconf [-y] [interface] [conf]​

Command for viewing and changing service protocol configuration for interfaces. Operates at the network layer — controlling which service protocols are enabled and how their Service IDs (SIDs) are mapped on a given interface.

  • -y option, if present no confirmation prompt is displayed.
  • [interface] interface number according to Interface IDs table.
  • [conf] a 32-bit configuration word. Can be entered as a single number, or as four 8-bit numbers ([cfg0] [cfg1] [cfg2] [cfg3], where [cfg0] is the LSB). A negative value (-1) resets to default configuration.

The command can be run with 0 arguments, 1 argument, or 2+ arguments. When run without arguments, lists all interfaces and their protocol configurations. If run with only the interface argument, prints configuration for that interface. If run with -1 as the interface argument, resets all interfaces to default.

Configuration word layout​

The 32-bit [conf] word is structured as follows:

BitsFieldDescription
0 - 7Service enableBitmask of enabled service protocols (see table below).
8 - 15Remap enableBitmask of services whose SIDs are remapped by the offset below.
16 - 23Offset base8-bit base value for the SID offset computation.
24 - 31Offset shift8-bit shift amount (only bits 0-4 used, i.e. 0-31).

The effective SID offset is computed as: offset = base << shift.

When entered as four separate bytes:

  • [cfg0] = service enable (bits 0-7)
  • [cfg1] = remap enable (bits 8-15)
  • [cfg2] = offset base (bits 16-23)
  • [cfg3] = offset shift (bits 24-31)

Service protocol bits​

BitService protocol
0PWR (power) - controls device power state.
1FWD (forward) - forwards messages from one interface to another.
2BL (bootloader) - firmware update protocol.
3ID (identification) - transfers device metadata (HWID, SWID, UUID ...).
4FS (filesystem) - filesystem transfer, used by emGUI.
5RPC (remote procedure call) - executing commands in the controller, used by emGUI.
6STREAM - default standard input/output streaming, used by Terminal emulator.
7PLOT (scope) - real-time data sampling, used by Scope tool.

For a detailed description of each service, see the Communication stack — Service protocol page.

Service enabling​

The lower byte (bits 0-7) of the configuration word controls which service protocols are active on a given interface. Each bit corresponds to one service — setting a bit to 1 enables that service, 0 disables it. A disabled service will neither transmit nor respond to incoming messages on that interface.

SID remapping​

The upper bytes of the configuration word control SID remapping — relocating service SIDs by a computed offset on a per-interface basis. For a conceptual explanation of how SID remapping works, including the CAN ID derivation and an interactive calculator, see the Communication stack — SID remapping page.

Availability

SID remapping requires YOS >= 2.8.5, BL (embl) >= 2.9.0, and SWTools >= 4.0.0.

When SID remapping is active on the device, a matching device configuration file (commonly swtools.ini) must be provided to the host-side tools so they use the same relocated SIDs. See example below.

Return value​

When called with arguments, returns the current/set value of the given service protocol.

Examples​

AM-felix#>protoconf
<outputs 15 lines>

Prints configuration for each interface.

AM-felix#>protoconf -1
reset all protos to default (-1)
(y/n) ?
y
AM-felix#>

Sets all interfaces to default configurations.

AM-felix#>protoconf 3 0b11110111
configuring proto 3 as 247 (247)
(y/n) ?
y
AM-felix#>

Enables all service protocols except for ID service for interface number 3 (CAN).

Remapping example​

AM-felix#>protoconf 3 255 255 100 0
configuring proto 3 as 6619391 (0x0064FFFF)
(y/n) ?
y
AM-felix#>

This configures the CAN interface (3) with:

  • cfg0 = 255 — all services enabled
  • cfg1 = 255 — all services remapped
  • cfg2 = 100 — offset base = 100
  • cfg3 = 0 — offset shift = 0

Effective offset = 100 << 0 = 100. Every service on this interface now transmits and receives with its SID shifted by +100 (e.g. PWR uses SID 100 instead of 0, FWD uses SID 102 instead of 2, etc.).

The corresponding host-side device configuration file:

swtools.ini
; SID remap offset: 100<<0 = 100 (matching protoconf = 0x0064FFFF on CAN)

[IDs]
resetID = 100
ID_ID = 103
bootloaderID = 104
bootloaderdataID = 105
FS_ID = 106
FS_DATAID = 107
RPC_ID = 108
RPC_DATAID = 109
streamID_rx = 110
streamID_tx = 111
MSG_SID_PLOT = 120
MSG_SID_PLOT_CONTINUE = 121
MSG_SID_PLOT_SETUP = 122

Large offset example​

AM-felix#>protoconf 3 255 255 4 8
configuring proto 3 as 134283775 (0x080400FF_FFFF)
(y/n) ?
y
AM-felix#>

This configures:

  • cfg0 = 255 — all services enabled
  • cfg1 = 255 — all services remapped
  • cfg2 = 4 — offset base = 4
  • cfg3 = 8 — offset shift = 8

Effective offset = 4 << 8 = 1024. Services are now at SIDs 1024+ (PWR = 1024, FWD = 1026, etc.).

There are two ways to provide this configuration to the host-side tools:

  1. Global swtools.ini — place the sections directly in swtools.ini. The file is searched in this order: working directory, %AppData%\silixcon\swtools\ (Windows) or ~/.config/swtools/ (POSIX), then executable directory.

  2. Device-specific file via -d — pass -d <devname> to the tool (e.g. -d falcon). SWTools will look for <devname>.ini (e.g. falcon.ini) in the same search paths listed above. This keeps the global swtools.ini untouched and allows per-device configurations to coexist.

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 range 0 - 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 range 0 - 255. Address 255 is used for broadcast messages.
  • -f<flags> - flags for the message. It has to be a number in range 0 - 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 range 0 - 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.

  • -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 -i and -n.
  • -a<address> optional matching address of the sender. It is a number in range 0 - 255.
  • -f<flags> optional flags to filter received message datagram with. It is a number in range 0 - 255. E.g. to disable link layer decoding, select BROADCAST datagram (-f1).
  • -s<sid> optional matching sid of the message. E.g. when CAN interface and BROADCAST datagram is selected (-f1), the <sid> value corresponds to the CAN ID.
  • -t<mask> optional mask that defines bits that must match incoming message's SID and the value specified with -s<sid>. If you want -t to 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.

Special cases​

  • A number of received messages can be retrieved with calling receive without parameters.
  • Running service could be stopped by running receive -1.

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.