Manufacturing Commands#
Note: Since Simplicity Commander version 1.16.3, the
manufacturingkeyword has been changed tomfg917. Themanufacturingalias is (as of version 1.17.3) still available, but it is considered deprecated and may therefore be removed without notice in any future release of Simplicity Commander.
Simplicity Commander provides tools for provisioning SiWx91x devices with initial configuration and keys for signing/encryption. The tools are suitable for use in a manufacturing setting and can be used to write and read data to and from regions related to both M4 and NWP(TA) cores.
For writing/erasing manufacturing data, or running the key provisioning processes (including its initialization), Simplicity Commander depends on custom RAM code being loaded to the device. Loading this code can be skipped by providing the --skipload flag. This option must only be provided if you are completely certain that the RAM code is already loaded and running on your device, and the use of the --skipload flag is therefore generally discouraged.
In case an external flash configuration is used, the flash pinset index can be set using the --pinset option.
For configuring radio-/network co-processor (RCP/NCP) devices, Simplicity Commander communicates via a proprietary serial protocol to an interface device, which in turn communicates with the RCP/NCP device via serial peripheral interface (SPI) or secure digital input output (SDIO) commands. In this case, Simplicity Commander requires that you also provide the --serialinterface option along with the --device option. In case you are running multiple mfg917 commands in sequence and without resetting the target device in between, you may also provide the --skipinit option to skip initializing the target device's SPI/SDIO interface.
Note:
mfg917commands are currently only supported on SiWx917 devices.
List Available Memory Regions#
Simplicity Commander can be used to read/write/erase certain memory regions, including but not limited to:
M4 and NWP (TA) master boot records (MBR)
Efuse
Boot descriptors
Keys
User data
To see the available memory regions on your device as well as their ability for producing JSON output, provide the --list option with either of the commands read, write, or erase.
Command Line Syntax
$ commander mfg917 read|write|erase --listCommand Line Input Example
$ commander mfg917 read --listThis command line lists all available memory regions that can be read using the manufacturing commands.
Command Line Output Example
Region name JSON supported Description
bfc No Bootloader firmware controller
certs No Certificates
efuse Yes Efuse
efusecopy Yes Efuse copy
efuseipmu Yes Efuse intelligent power management unit
keydesctable No Key descriptor table
m4efusemapversioncf No M4 Efuse map version (common flash)
m4efusemapversiondf No M4 Efuse map verion (dual flash)
m4fmccf No M4 core flash memory controller (common flash)
m4fmcdf No M4 core flash memory controller (dual flash)
m4ipmucf Yes M4 core intelligent power management unit (common flash)
m4ipmudf Yes M4 core intelligent power management unit (dual flash)
m4mbrcf Yes M4 core master boot record (common flash)
m4mbrdf Yes M4 core master boot record (dual flash)
m4ptinfocf No M4 production information (common flash)
m4ptinfodf No M4 production information (dual flash)
pufactkey No PUF activation key
rompatch No ROM patches
signature No Signature
statickeys No Static keys
storeconf No Store configuration
tafmc No NWP flash memory controller
tafwimg No NWP firmware image
taipmu Yes NWP core intelligent power management unit
tambr Yes NWP core master boot record
userdata No User data
DONERead Memory Region Data From Device#
The read data can be output to the terminal or saved to a raw binary file. For supported regions, the output data can also be stored in a human-readable JSON file. If JSON output is supported and desired, provide an output filename with '.json' extension. If you want to read the region data from a certain offset relative to the start address of that region, you can provide that offset using the --position option.
Command Line Syntax
$ commander mfg917 read <region> [--out <filename> --position <offset>]Command Line Input Example
$ commander mfg917 read tambr --out device-mbr.jsonThis command line reads the tambr region of the device and stores the data output to the file 'device-mbr.json' in JSON format.
Command Line Output Example
Reading data from region: tambr
Reading 496 bytes from 0x04000000
Writing JSON...
Manufacturing data saved to file 'device-mbr.json'
DONERead Specific Fields From Memory Region#
If you are interested in reading only certain data fields from a JSON-supported region, singular values can be extracted by providing the --property option along with which field and/or sub-field to read from. The --property option can be provided multiple times, and the fields/sub-fields are given on the format field:sub-field. If you provide only the field name for a data field that also contains named sub-fields, all the sub-fields will be included in the output.
If JSON output is supported and desired, provide an output filename with '.json' extension to store the selected fields in a JSON file.
Command Line Syntax
$ commander mfg917 read <region> [--out <filename> --property <field name[:sub-field name]>]Command Line Input Example
$ commander mfg917 read tambr --property m4_clk_configs --property flash_size --property psram_misc_configs:spi_modeThis command line reads the selected fields from the tambr region of the device.
Command Line Output Example
Reading data from region: tambr
Reading 496 bytes from 0x04000000
flash_size = 64
m4_clk_configs:clk_source = 0
m4_clk_configs:div_factor = 0
psram_misc_configs:spi_mode = 2
DONERead Address Range From Device#
Arbitrary address ranges (except any addresses inside the Efuse/OTP area) can be read from the device by omitting the region name and instead providing the --range option. The --range option accepts input as either <startaddress:endaddress> or as <startaddress:+length>. Hexadecimal values can be provided using the '0x' prefix.
Command Line Syntax
$ commander mfg917 read --range <startaddress>:[<endaddress> OR +<length>]Command Line Input Example
$ commander mfg917 read --range 0x04000002:+13This command line reads 13 bytes from the target device from start address 0x04000002 and prints the data to the console.
Command Line Output Example
Reading data from range 0x04000002:0x0400000F...
{address: 0 1 2 3 4 5 6 7 8 9 A B C D E F}
04000000: -- -- 00 00 38 02 00 00 A8 72 EB 28 31 7A 03 --
DONEWrite Memory Region Data to Device#
Manufacturing data that is to be written to a memory region of the device must be provided in either binary format (.s37 and .hex also supported), or, for eligible memory regions, as a JSON file.
Note: Proceed with caution when writing manufacturing data to your device; writing unsupported/erroneous data/configurations may result in your device being rendered unrecoverable!
If the provided data is a binary file, the data is written to the device verbatim.
If a JSON file is provided, the region data is instead updated; the memory region is first read from the device, and the fields present in the JSON file are then used to update the corresponding region data. Lastly, the updated region data is written back to the device. If applicable, Simplicity Commander will by default also update the region's CRCs/integrity checks when changes have been made. This can be omitted by providing the --nocrc option.
If you want to write the data starting from a certain offset relative to the start address of that region, you can provide that offset using the --position option. This is only supported if you are writing binary data; not if you are providing a JSON file.
The --dryrun flag can be added to output the new region data to the terminal instead of writing it to the device.
This command provides no safeguards as to what data is written to the device; it is generally not recommended to write TA (NWP) MBR data to the device using this command; use the mfg917 provision command for that instead.
Command Line Syntax
$ commander mfg917 write <region> --data <filename> [--pinset <index> --position <offset> --skipload --nocrc --dryrun]Command Line Input Example
$ commander mfg917 write tambr --data mbr-updates.jsonThis command line writes an updated tambr to the device by first reading the tambr region of the device, applying the changes from the fields provided in the 'mbr-updates.json' JSON file, and finally writing this updated tambr data back to the device.
Command Line Output Example
Reading 496 bytes from 0x00400000...
Reading JSON...
Writing data to region: tambr
<process output shortened for documentation>
Data loaded successfully
Region 'tambr' was successfully written to device.
DONEWrite Data to Address#
Simplicity Commander supports writing data to arbitrary memory addresses (except addresses inside Efuse/OTP areas and MBR regions) by omitting the region name and instead providing the --address option. If you are providing an .s37 or .hex-formatted data file, the --address option is ignored and Commander will instead infer the address from the address encoded in the data file.
Command Line Syntax
$ commander mfg917 write --data <filename> [--address <address>]Command Line Input Example
$ commander mfg917 write --data data.bin --address 0x043F7000This command line will write the contents of 'data.bin' to address 0x043F7000.
Command Line Output Example
Parsing file data.bin...
Writing data to range 0x047CF000:0x047CF020
<process output shortened for documentation>
Data was successfully written to device.
DONEErase Memory Region Data From Device#
Simplicity Commander can be used to erase the data in a memory region, using the mfg917 erase command.
If you want to erase the region data starting from a certain offset relative to the start address of that region, you can provide that offset using the --position option.
Command Line Syntax
$ commander mfg917 erase <region> [--position <offset> --pinset <index> --skipload]Command Line Input Example
$ commander mfg917 erase efusecopyThis command line erases the contents in the efusecopy region of the device.
Command Line Output Example
Writing data to region: efusecopy
<process output shortened for documentation>
Data loaded successfully
Region 'efusecopy' was successfully erased.
DONEErase Address Range From Device#
Simplicity Commander supports erasing arbitrary memory ranges (except addresses inside Efuse/OTP areas and MBR regions) by omitting the region name and instead providing the --range option.
The --range option accepts input as either <startaddress:endaddress> or as <startaddress:+length>. Hexadecimal values can be provided using the '0x' prefix.
Command Line Syntax
$ commander mfg917 erase --range <startaddress>:[<endaddress> OR +<length>]Command Line Input Example
$ commander mfg917 erase --range 0x047CF000:+32This command line starts erases a 32 byte range starting from address 0x047CF000.
Command Line Output Example
Erasing data in range 0x047CF000:0x047CF020...
<process output shortened for documentation>
Range was successfully erased.
DONEDump Configuration Data of Device#
Simplicity Commander supports dumping all data regions containing configuration data to a zip archive, using the mfg917 dump command.
Note: For zip file compression functionality, the
mfg917 dumpcommand requires Microsoft PowerShell version 5.0 or above on Windows, and thezipandunzipsystem utilities on Linux/Mac
Command Line Syntax
$ commander mfg917 dump <zip archive filename>Command Line Input Example
$ commander mfg917 dump device_data.zipThis command line reads and dumps all data regions containing configuration data into the 'device_data.zip' archive file.
Command Line Output Example
Reading 40960 bytes from 0x0400f000
Reading 184320 bytes from 0x047cf000
Reading 1024 bytes from 0x40012000
Reading 1024 bytes from 0x040003e0
Reading 58 bytes from 0x40012181
Reading 88 bytes from 0x04000300
Reading 496 bytes from 0x04000000
Reading 1024 bytes from 0x041c0000
Reading 496 bytes from 0x04000000
Reading 58 bytes from 0x041b0258
Reading 496 bytes from 0x04000000
Reading 496 bytes from 0x041b0000
Reading 496 bytes from 0x04000000
Reading 3 bytes from 0x041b0292
Reading 1192 bytes from 0x04002000
Reading 200 bytes from 0x04000238
Reading 72 bytes from 0x040001f0
Reading 4096 bytes from 0x04005000
Reading 3072 bytes from 0x04010400
Reading 1024 bytes from 0x04010000
Reading 58 bytes from 0x04000561
Reading 496 bytes from 0x04000000
Zip archive created at "path/to/device_data.zip".
DONEInitialize PUF And Generate Activation Code#
To enable security features (encryption/MIC integrity check/signing) on your SiWx917 device, the device's PUF first needs to be initialized and an activation code must be generated on the device. This can be done via the mfg917 init command.
Providing an NWP (TA) MBR (as a binary file) using the --mbr option is optional, and its purpose is to provide information about the destination address of the activation code. If required, updates to the NWP MBR can be applied by providing a JSON file with the --data option. If the --mbr option is omitted, the default activation code address is used. Providing --mbr 'default' will use the default NWP MBR for your device, based on the provided device part number using the --device option.
Note: After the
mfg917 initcommand has been run, the device needs to be power cycled for any changes to take effect.
Command Line Syntax
$ commander mfg917 init [--mbr <filename|'default'> --data <filename> --pinset <index> --skipload]Command Line Input Example
$ commander mfg917 init --mbr default --device SiWG917M111LGTBAThis command line initializes the device's PUF and generates an activation code, using a default NWP MBR for the device part number 'SiWG917M111LGTBA'.
Command Line Output Example
Using default MBR for SiWG917M111LGTBA...
<process output shortened for documentation>
Activation code generated successfully
DONEProvision Security Keys to the Device#
Provisioning device keys is done using the mfg917 provision command, by providing a key configuration JSON file containing the keys you want to store on your device with the --keys option. Supported keys for storing on the device are M4/NWP (TA) public keys and M4/NWP OTA keys. In addition, a private attestation key is required for the provisioning sequence.
If you don't want to provision any keys during the provisioning sequence, the --keys option may be omitted.
If required, updates to the NWP MBR can be applied before writing it to the device by providing a JSON file with the --data option.
Note: After the
mfg917 provisioncommand has been run, the device needs to be power cycled for any changes to take effect.
Command Line Syntax
$ commander mfg917 provision --mbr <filename|'default'> [--keys <filename> --data <filename> --pinset <index> --skipload]Command Line Input Example
$ commander mfg917 provision --keys keys.jsonThis command line provisions the keys contained in the JSON file 'keys.json' to the device.
Command Line Output Example
Reading MBR from the connected device...
Found valid activation code address in MBR: 0x00002000
Intrinsic keys generated successfully.
Programming NWP OTA Key...
Key successfully stored
Programming M4 OTA Key...
Key successfully stored
Programming NWP Public Key...
Key successfully stored
Programming M4 Public Key...
Key successfully stored
Programming attestation Key...
Key successfully stored
Programming NWP MBR...
Data loaded successfully
Programming key descriptor table...
Data loaded successfully
DONEProvision OTP Security Keys to the Device#
Provisioning one-time programmable (OTP) keys is done using the mfg917 provisionotpkeys command. Symmetric (AES) and public (ECDSA) keys can be provided via the --symmetrickey and --publickey options, respectively. These keys can be used later for enabling MIC and signature-based write protection of the device configuration (see Protection Device Configuration).
The symmetric key must be provided as a .bin file, or as a hex-encoded string in a .txt file. The public key must be provided as a DER-formatted binary file (.der), or as a .pem file. Alternatively, both options accept a key configuration JSON file, as long as the relevant OTP keys are available in the JSON file.
Note: Writing OTP keys is a permanent action and cannot be reverted.
Command Line Syntax
$ commander mfg917 provisionotpkeys [--symmetrickey <filename> --publickey <filename> --noprompt]Command Line Input Example
$ commander mfg917 provisionotpkeys --symmetrickey aeskey.bin --publickey key.pemThis command line reads the symmetric key 'aeskey.bin' and the public key 'key.pem' and writes them into the OTP of the device.
Command Line Output Example
Reading OTP symmetric key from file 'aeskey.bin'...
Reading OTP public key from file 'key.pem'...
The provided data can be applied to the current Efuse.
Determining which OTP words need updating...
Writing 112 bytes to OTP...
Data was successfully written to the device's OTP.
DONEList Available Device Profiles#
Simplicity Commander can be used to store and apply frequently used device configuration JSON files, referred to as 'profiles'. A list of the available profiles can be produced using the mfg917 provision --listprofiles command. Along with this list, the location of user-defined profiles is also shown, including instructions on how to add such custom profiles.
Command Line Syntax
$ commander mfg917 --listprofilesCommand Line Input Example
$ commander mfg917 --listprofilesThis command line displays the available profiles on your system, along with the location of custom user-defined profiles.
Command Line Output Example
Profile name Affected regions
giga tambr
macronix tambr
xmc tambr
enable-secure-boot tambr
Custom profiles can be added by placing them in the directory at
'/Users/username/Library/Preferences/SiliconLabs/commander/ProfileStore/Si91x/'.
The name of the files must be in the format '<profile name>_<region>.json'.
DONEProvision Device Profile to the Device#
Applying a device profile is done through the mfg917 provision command, using the --profile option.
Note: As of version 1.17.3, only TA (NWP) MBR data can be applied as part of a profile.
These profiles may be useful for quickly changing between e.g. secure and non-secure device configurations, or for applying a set of changes across multiple devices in e.g. a production environment.
Profiles can be provided along with both --mbr and --data options; the changes denoted by the profile will be applied as the last step before writing the data to the device.
Command Line Syntax
$ commander mfg917 provision --profile <name> [--mbr <filename|'default'> --data <filename>]Command Line Input Example
$ commander mfg917 provision --profile enable-secure-bootThis command line applies the 'enable-secure-boot' profile to the device's TA (NWP) MBR and provisions it to the device.
Command Line Output Example
Using MBR from the connected device...
Applying profile 'enable-secure-boot' to tambr...
Reading JSON...
Loading RAM code (321776 bytes)...
Starting RAM code...
Programming ROM patch...
Data loaded successfully
Programming NWP MBR...
Data loaded successfully
Programming M4 MBR...
Data loaded successfully
Programming IPMU data...
Data loaded successfully
Programming M4 Efuse map version...
Data loaded successfully
DONEProtect Device Configuration#
Simplicity Commander can be used to write-protect the device configuration using the mfg917 protectconfig command. This protection is permanent and is applied over a user-specified length, starting from address 0x04000000 (the start of the NWP (TA) configuration region). Note that only certain protection lengths are supported, ranging from 1024-65536 bytes. Commander will provide suggestions of the nearest allowed lengths if the provided length is not supported.
Two types of protection are available: message integrity check (MIC)-based protection and signature-based protection. MIC-based protection requires a 16 byte AES key as a .bin file or as a hex-encoded string in a .txt file, provided with the --symmetrickey option. Signature-based protection requires a private ECDSA key, either as a DER-formatted binary file (.der), or as a .pem file, provided with the --privatekey option. Alternatively, both options accept a key configuration JSON file, as long as the relevant OTP keys are available in the JSON file.
When enabling signature-based protection, the public key counterpart of the provided private key must be present on the device. If there is no such public key stored in the device, Commander will extract the public key from the provided private key and store it on the device before proceeding.
Note: Enabling configuration protection is permanent and cannot be reverted. Any subsequent attempts at writing new configurations to a protected device will fail and/or may render your device unrecoverable.
Command Line Syntax
$ commander mfg917 protectconfig <protection> --protectlength <length> [--privatekey <filename> --sha <SHA-xxx>] [--symmetrickey <filename>] [--noprompt]Command Line Input Example
$ commander mfg917 protectconfig mic --protectlength 49152 --symmetrickey key.binThis command line will enable MIC based protection of 49152 bytes of the device configuration, using 'key.bin' as the key for the MIC computation.
Command Line Output Example
OTP Efuse might not be up to date with the MBR configuration. Copying MBR configuration data into Efuse...
Storing the provided symmetric key in the OTP Efuse...
Computing MIC...
Using default IV...
The provided data can be applied to the current Efuse.
Determining which OTP words need updating...
Writing 68 bytes to OTP...
Data was successfully written to the device's OTP.
DONECommand Line Input Example
$ commander mfg917 protectconfig signature --protectlength 16384 --privatekey key.pemThis command line enables signature-based protection of the first 16384 bytes of the device configuration, using the private ECDSA key 'key.pem' for generating the signature. The signature is placed at the end of the protected region.
Command Line Output Example
OTP Efuse might not be up to date with the MBR configuration. Copying MBR configuration data into Efuse...
Computing signature...
The provided data can be applied to the current Efuse.
Determining which OTP words need updating...
Writing 128 bytes to OTP...
Data was successfully written to the device's OTP.
DONEGet Information About Device Configuration#
Key information about the device configuration can be extracted using the mfg917 info command. Simplicity Commander will read certain regions of your device (including the NWP (TA) MBR and the Efuse regions), parse the information, and present key information like the device's MAC address, flash size, and current security parameters.
Command Line Syntax
$ commander mfg917 infoCommand Line Input Example
$ commander mfg917 infoThis command line extracts information about the current configuration of the target device.
Command Line Output Example
Reading 1024 bytes from 0x040003e0
OPN : SiWG917M111MGTBA
WiFi MAC address : 6C5CB1C43F90
BLE MAC address : 6C5CB1C43F92
Flash size : 8MB
NWP firmware version : 1711.2.10.1.3.0.7
MBR variant : 0x1F (1.8 MB)
Manufacturing SW version : 2.4 (36)
Application region start address : 0x081f0000
Application code start address : 0x08202000
Application region end address : 0x0840ffff
Flash configuration : Common flash
Mode : SOC
Integrity protection active : None
NWP roll-back prevention : Disabled
NWP digital signature validation : Disabled
NWP firmware encryption : Disabled
NWP secure boot : Disabled
Application roll-back prevention : Disabled
Application digital signature validation : Disabled
Application code encryption : Disabled
Application secure boot : Disabled
DONE