Serial Commands#

Simplicity Commander can be used to transfer files to SiWx917 devices over the adapter's serial (VCOM) port, using the Embedded Kermit protocol. These files include M4 or NWP application images, as well as tokens for unlocking debug access to either device core.

All serial commands require a physical data connection (i.e. USB cable) between the host computer and the adapter. The serial port can be explicitly provided using the --serialport option; this will also bypass all J-Link specific handling of the adapter board/kit. If the J-Link serial number is provided via the --serialno option, the adapter's serial port is automatically inferred by Commander.

serial file transfers can be aborted by pressing CTRL+C. Providing --showprogress will display a progress bar for the ongoing file transfer.

Simplicity Commander will attempt to configure the serial communication to use the highest available speed (921600 baud), depending on the specific adapter board and the target device. If this configuration is not desired, you may provide the --fixedspeed option to let Commander skip this step.

Note: Prior to running any of the serial commands, the target device must be booted in ISP mode. Some adapter boards support programmatically restarting their target devices in ISP mode; in these cases Commander will attempt to do so automatically.

Load an RPS Application Over Serial#

RPS images can be loaded to either the M4 or the NWP core of the SiWx917 device using the serial load command. The core to which the application is loaded is determined by the contents of the image's RPS header.

Command Line Syntax

$ commander serial load <RPS filename> [--serialport <port name> --showprogress --fixedspeed]

Command Line Input Example

$ commander serial load app.rps --serialport COM4

This command line loads the application image 'app.rps' to the device, using serial port COM4.

Command Line Output Example

Using serial port 'COM4' for file transfers.
Initializing M4 firmware upgrade...
Sending file(s):
  app.rps
M4 firmware was successfully uploaded.
DONE

Lock Debug Access to M4/NWP Core#

Simplicity Commander can lock debug access via the JTAG interface to both the M4 and the NWP(TA) core of SiWx917 devices.

Providing the --token option, a token can be created upon locking, which can be used for unlocking debug access to the device later. Creating this token requires a private ECDSA key provided via the --key option, used for signing the token.

For the sake of redundancy, in case the process of saving the token file should fail, the complete token raw data is always printed to the console.

Optionally, 7 bytes (exactly) of user data can be provided using the --userdata option, to be stored in the token file. These bytes are provided as a hex string.

Note: After the serial lock command has been run, the device needs to be power cycled for the debug access changes to take effect.

Command Line Syntax

$ commander serial lock <'M4'|'TA'> [--token <filename> --key <filename> --userdata <hex string> --serialport <port name>]

Command Line Input Example

$ commander serial lock TA --token unlock.token --key private-key.pem --userdata AABBCCDDC0FFEE --serialport COM4

This command line locks the JTAG debug access to the NWP core of the device, and saves the debug access unlock token to the file 'unlock.token'. The bytes AABBCCDDC0FFEE are stored in the user data section of the token, and the token is signed by the 'private-key.pem' ECDSA key.

Command Line Output Example

Using serial port 'COM4' for file transfers.
Initializing debug lock...
Nonce generated by the device: 7A3FFEEFBB48EFC7EB7617E90E7FDDEE
Debug access locked.
Parsing signing key 'private-key.pem"...
Debuglock token raw data:
7a3ffeefbb48efc7eb7617e90e7fddee74aabbccddc0ffee304502210094cf2c372ad5f3a9fd2b46b2b0c25a7d6d853e3aab10
93bcdd9746b35648b3c602203c3961aed180bf08d5bf2b2d703b7470ed923b18f5d7ea1ba10b545d65318aaa00
Debuglock token written to 'unlock.token'.
Debug access will be locked after the device is reset.
DONE

Unlock Debug Access to M4/NWP Core With Existing Token#

If the unlock token from the last time the device was locked is available, debug access to the M4/NWP(TA) core over the JTAG interface can be unlocked by using the serial unlock command.

Note: After the serial unlock command has been run, the device needs to be power cycled for the debug access changes to take effect.

Command Line Syntax

$ commander serial unlock <'M4'|'TA'> --token <filename> [--serialport <port name>]

Command Line Input Example

$ commander serial unlock TA --token unlock.token --serialport COM4

This command line unlocks debug access to the NWP core, by sending the token 'unlock.token' to the device.

Command Line Output Example

Using serial port 'COM4' for file transfers.
Verifying debuglock token 'unlock.token'...
Initializing debug unlock...
Sending file(s):
  unlock.token
Debug access will be unlocked after device is reset.
DONE

Unlock Debug Access to M4/NWP Core Without Existing Token#

Simplicity Commander can unlock the debug access to the M4/NWP(TA) core without the token from when the device was last locked. This is effectively done by locking the device (thus generating a new token), immediately followed by unlocking the device using this new, intermediate token. The --key option is required in this configuration, as the intermediate token needs to be signed using a private ECDSA key. The --userdata option is optional.

Note: After the serial unlock command has been run, the device needs to be power cycled for the debug access changes to take effect.

Command Line Syntax

$ commander serial unlock <'M4'|'TA'> --key <filename> [--userdata <hex string> --serialport <port name>]

Command Line Input Example

$ commander serial unlock TA --key private-key.pem --serialport COM4

This command line unlocks debug access to the NWP core by creating a temporary token file that is signed by the ECDSA key 'private-key.pem'.

Command Line Output Example

Using serial port 'COM4' for file transfers.
Initializing debug unlock...
Nonce generated by the device: 7A3FFEEFBB48EFC7EB7617E90E7FDDEE
Parsing signing key 'private-key.pem"...
Debuglock token raw data:
7a3ffeefbb48efc7eb7617e90e7fddee74aabbccddc0ffee304502210094cf2c372ad5f3a9fd2b46b2b0c25a7d6d853e3aab1093bcdd9746b35648b3c602203c3961aed180bf08d5bf2b2d703b7470ed923b18f5d7ea1ba10b545d65318aaa00
Debuglock token written to 'unlock.token'.
Sending file(s):
  unlock.token
Debug access will be unlocked after the device is reset.
DONE

Extract Device Part Number#

Simplicity Commander can be used to extract the device part number stored on an SiWx917.

Command Line Syntax

$ commander serial getopn

Command Line Input Example

$ commander serial getopn

This command line collects the device part number stored on the device.

Command Line Output Example

SiWG917M111MGTBA
DONE