swiflash - command line tool (linux host)

Nov 12, 2018 - Author: Sierra Wireless - Version 5.1 - 14338 Views

swiflash - command line

swiflash is a platform-specific tool used to flash images into WP/AR products through the USB port. This is a recovery tool that can be used even if the device is not booting anymore (due to corrupted configuration files in the root FS, badly customized Linux kernel or Legato framework, etc.). 


Ubuntu/Debian Distributions

For Ubuntu/Debian distributions, enter the following commands:

wget https://downloads.sierrawireless.com/tools/swiflash/swiflash_latest.deb -O /tmp/swiflash_latest.deb
sudo apt-get install /tmp/swiflash_latest.deb

Note: The installed package includes a udev rule that swiflash requires to run correctly (see udev Rule description below for details).

Alternate Distributions

For alternate (non-Ubuntu/Debian) distributions:

  1. Download the swiflash tool archive from this link.
  2. Extract the archive to the location of your choice (e.g. unzip swiflash.zip -d $HOME/legato/swiflash).
  3. Potentially add this location to your user's path (e.g. echo 'export PATH=$HOME/legato/swiflash:$PATH' >> $HOME/.bashrc).
  4. Install the udev rule that swiflash requires to run correctly (see udev Rule description below for details).
    Enter the following commands (where <install_dir> is the location where swiflash was installed):
  5. sudo cp <install_dir>/99-sierrawireless-modem.rules /etc/udev/rules.d
    sudo service udev restart
  6. If your device is already connected via USB, power-cycle it.

udev Rule

As noted above, swiflash requires a udev rule to be installed on the system in order to run correctly. This rule:
  • provides read access to Legato device USB ports
  • blacklists Legato device from Modem Manager service (to prevent the Modem Manager to disturb the download process)
The rule is automatically installed from the Debian package, or can be also installed manually (e.g. when installation is done from a zip archive) as described in the Alternate Distributions procedure above.

swiflash verifies the rule is present before running. (Note — This check can be disabled by using the --force option.)

Running swiflash

swiflash uses the module's USB DM port (download port) to flash an image to the module.

Important — If the USB DM port is not available, the module is in an unrecoverable state and must be switched to bootloader mode before the image can be flashed. Follow the Troubleshooting — Force Module to Bootloader Mode instructions (next section) before running swiflash. 

To use swiflash to flash an image to the module:

  1. Make sure the device is connected via a USB cable.
  2. Run the swiflash command using the appropriate Command Options described below.
    (Note — If you used the hardware switch to enter bootloader mode earlier, switch it back to the ON (High) position after the download begins.)

Command options

Run swiflash --help for complete usage details. The following are two typical usage formats:

swiflash [OPTION] -m "<module>" -i <image>
swiflash [OPTION] -m "<module>" -r


-i <image> Uses the provided image file (cwe or spk file) to flash the device

-r Restore the Linux root filesystem in its original state by erasing the USER1 partition (all filesystem updates will be lost)

Note: This option is not supported on the following modules: ar758x

-m "<module>" Specifies the target module type.
Allowed values are: ar86, ar7, ar758x, wp85, wp750x, wp76xx, wp77xx, fx30_wp85

-f,--force Bypass preliminary checks for dialout group and ModemManager service, and launch the download anyway (as noted in the udev Rule section above)

 -p <port> Specify the USB port to be used for download (enabling multiple downloads to be performed simultaneously).
Use any path from the /dev/serial/by-path or /dev/serial/by-id folders.
Multiple paths may point to the same device — pick one from the list.
Note: Up to 12 simultaneous downloads are supported.
-h,--help Display this message

Troubleshooting — Force Module to Bootloader Mode (if necessary)

Usually, swiflash can be used without any hardware manipulation, as soon as the USB DM port (download port) is available.

However, if the module is in an unrecoverable state (no DM port), the module must be switched to bootloader mode before the flashing operation.

To switch the module to bootloader mode:

  1. Use either of the following methods:
    • Hardware switch:
      1. Toggle the TP1 pin to LOW or OFF position
        Please refer to your product PTS to know where this pin is connected
        (on mangOH boards, this is switch number 7)
      2. Reboot the module.
    • Software (AT command) switch:
      1. Prepare to enter AT commands. To access AT commands from the module's Linux shell (UART or SSH), use the microcom -E /dev/ttyAT command.
      2. Use the AT!BOOTHOLD AT command (this will perform a module reset).
  2. Plug the device USB cable.
  3. Check that a /dev/ttyUSBX serial port is mounted on your system—this will be the DM port, necessary to handle the download.
Then you will be able to execute the swiflash command (see below).

Note: if you used the hardware switch to enter bootloader mode, you'll have to switch back to HIGH or ON position once the download is started.

Example commands

Reset user partition on a Legato device:

swiflash -m "wp85" -r

Download reference device image on a Legato device:

swiflash -m "wp85" -i $WP85_DEVICE_IMAGE/image.spk
where image.spk is the image to be used, according to your customer configuration

Related items

Legato Application Development Kit - Linux

Installation procedures for Linux host to develop Legato Applications.

swicwe - command line tool (linux host)

Create one single firmware image from several unitary components for WP/AR modules

©2018 Sierra Wireless. All rights reserved.
You have been successfully unsubscribed to this product. To access your subscription click here.