qmi-firmware-update: improve examples

Added example of how to manually update 9x15 and 9x30 devices.

1 files changed, 103 insertions, 66 deletions

diff --git a/src/qmi-firmware-update/qfu-main.c b/src/qmi-firmware-update/qfu-main.c
index 876e1cf..ac9c056 100644
--- a/src/qmi-firmware-update/qfu-main.c
+++ b/src/qmi-firmware-update/qfu-main.c
@@ -348,7 +348,8 @@ print_help_examples (void)
     g_print ("\n"
              "********************************************************************************\n"
              "\n"
-             " Example 1: Updating a Sierra Wireless MC7354.\n"
+             " Example: Updating a Sierra Wireless MC7354.\n"
+             "  (or other 9x15 or 9x20 devices, like the MC7304, MC7330, MC7455... ).\n"
              "\n"
              " The MC7354 is a 9x15 device which requires the firmware updater to specify the\n"
              " firmware version string, the config version string and the carrier string, so\n"
@@ -369,42 +370,43 @@ print_help_examples (void)
              " which already has the matching firmware version. The two images may be given\n"
              " combined into a single image (.spk) file.\n"
              "\n"
-             " 1a) An update operation specifying the vid:pid of the device (fails if multiple\n"
-             "     devices with the same vid:pid are found):\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       -d 1199:68c0 \\\n"
-             "       SWI9X15C_05.05.58.00.cwe \\\n"
-             "       SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
+             " a) An update operation specifying the vid:pid of the device (fails if multiple\n"
+             "    devices with the same vid:pid are found):\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          -d 1199:68c0 \\\n"
+             "          SWI9X15C_05.05.58.00.cwe \\\n"
+             "          SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
              "\n"
-             " 1b) An update operation specifying an explicit QMI cdc-wdm device:\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       --cdc-wdm /dev/cdc-wdm0 \\\n"
-             "       SWI9X15C_05.05.58.00.cwe \\\n"
-             "       SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
+             " b) An update operation specifying an explicit QMI cdc-wdm device:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          --cdc-wdm /dev/cdc-wdm0 \\\n"
+             "          SWI9X15C_05.05.58.00.cwe \\\n"
+             "          SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
              "\n"
-             " 1c) An update operation specifying explicit firmware, config and carrier strings:\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       -d 1199:68c0 \\\n"
-             "       --firmware-version 05.05.58.00 \\\n"
-             "       --config-version 005.025_002 \\\n"
-             "       --carrier Generic \\\n"
-             "       SWI9X15C_05.05.58.00.cwe \\\n"
-             "       SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
+             " c) An update operation specifying explicit firmware, config and carrier strings:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          -d 1199:68c0 \\\n"
+             "          --firmware-version 05.05.58.00 \\\n"
+             "          --config-version 005.025_002 \\\n"
+             "          --carrier Generic \\\n"
+             "          SWI9X15C_05.05.58.00.cwe \\\n"
+             "          SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
              "\n"
-             " 1d) An update operation with a combined image containing both system and carrier\n"
-             "     specific images::\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       -d 1199:68c0 \\\n"
-             "       9999999_9902574_SWI9X15C_05.05.66.00_00_GENNA-UMTS_005.028_000-field.spk\n");
+             " d) An update operation with a combined image containing both system and carrier\n"
+             "    specific images::\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          -d 1199:68c0 \\\n"
+             "          9999999_9902574_SWI9X15C_05.05.66.00_00_GENNA-UMTS_005.028_000-field.spk\n");
 
     g_print ("\n"
              "********************************************************************************\n"
              "\n"
-             " Example 2: Updating a Sierra Wireless MC7700.\n"
+             " Example: Updating a Sierra Wireless MC7700.\n"
+             "  (or other 9200 devices, like the MC7710).\n"
              "\n"
              " The MC7700 is a 9200 device which doesn't require the explicit firmware, config\n"
              " and carrier strings. Unlike the MC7354, which would reboot itself into QDL\n"
@@ -412,57 +414,92 @@ print_help_examples (void)
              " a specific \"boot and hold\" command to be sent (either via QMI or AT) to request\n"
              " the reset in QDL download mode.\n"
              "\n"
-             " 2a) An update operation specifying the vid:pid of the device (fails if multiple\n"
-             "     devices with the same vid:pid are found):\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       -d 1199:68a2 \\\n"
-             "       9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n"
+             " a) An update operation specifying the vid:pid of the device (fails if multiple\n"
+             "    devices with the same vid:pid are found):\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          -d 1199:68a2 \\\n"
+             "          9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n"
              "\n"
-             " 2b) An update operation specifying an explicit QMI cdc-wdm device:\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       --update \\\n"
-             "       --cdc-wdm /dev/cdc-wdm0 \\\n"
-             "       9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n");
+             " b) An update operation specifying an explicit QMI cdc-wdm device:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          --update \\\n"
+             "          --cdc-wdm /dev/cdc-wdm0 \\\n"
+             "          9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n");
 
     g_print ("\n"
              "********************************************************************************\n"
              "\n"
-             " Example 3: Manual process to update a Sierra Wireless MC7700.\n"
+             " Example: Manual process to update a Sierra Wireless MC7354.\n"
+             "  (or other 9x15 or 9x20 devices, like the MC7304, MC7330, MC7455... ).\n"
              "\n"
-             " Instead of letting the " PROGRAM_NAME " manage the full firmware update\n"
-             " operation (include the module reboots into the different modes), the user can\n"
-             " trigger the actions manually as follows:\n"
+             " The upgrade of devices from the 9x15 and 9x30 families is triggered via a\n"
+             " 'firmware preference' setting. If the device accepts the setting, the user\n"
+             " can request a device power cycle, which will boot in QDL download mode:\n"
              "\n"
-             " 3a) Request device to go into QDL download mode:\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       -d 1199:68a2 \\\n"
-             "       --reset\n"
+             " a) Set firmware preference setting:\n"
+             "    $ sudo qmicli \\\n"
+             "          -d /dev/cdc-wdm0 \\\n"
+             "          --dms-set-firmware-preference=\"05.05.58.00,005.025_002,Generic\" \\\n"
              "\n"
-             " 3b) Run updater operation while in QDL download mode:\n"
-             " $ sudo " PROGRAM_NAME " \\\n"
-             "       -d 1199:68a2 \\\n"
-             "       --update-qdl \\\n"
-             "       9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n");
+             " b) Request power cycle \\\n"
+             "    $ sudo qmicli \\\n"
+             "          -d /dev/cdc-wdm0 \\\n"
+             "          --dms-set-operating-mode=offline \\\n"
+             "    $ sudo qmicli \\\n"
+             "          -d /dev/cdc-wdm0 \\\n"
+             "          --dms-set-operating-mode=reset \\\n"
+             "\n"
+             " c) Run updater operation while in QDL download mode:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          -t /dev/ttyUSB0 \\\n"
+             "          --update-qdl \\\n"
+             "          SWI9X15C_05.05.58.00.cwe \\\n"
+             "          SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
+             "\n"
+             " d) Now wait for the device to fully reboot, may take up to several minutes.\n");
+
+    g_print ("\n"
+             "********************************************************************************\n"
+             "\n"
+             " Example: Manual process to update a Sierra Wireless MC7700.\n"
+             "  (or other 9200 devices, like the MC7710).\n"
+             "\n"
+             " Instead of setting a 'firmware preference', the devices from the 9200 family\n"
+             " can just be rebooted in QDL mode:\n"
+             "\n"
+             " a) Request device to go into QDL download mode:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          -d 1199:68a2 \\\n"
+             "          --reset\n"
+             "\n"
+             " b) Run updater operation while in QDL download mode:\n"
+             "    $ sudo " PROGRAM_NAME " \\\n"
+             "          -d 1199:68a2 \\\n"
+             "          --update-qdl \\\n"
+             "          9999999_9999999_9200_03.05.14.00_00_generic_000.000_001_SPKG_MC.cwe\n"
+             "\n"
+             " c) Now wait for the device to fully reboot, may take up to several minutes.\n");
+
 
     g_print ("\n"
              "********************************************************************************\n"
              "\n"
-             " Example 4: Verify firmware images.\n"
+             " Example: Verify firmware images.\n"
              "\n"
-             " 3a) Verify several images at once:\n"
-             " $ " PROGRAM_NAME " \\\n"
-             "       --verify \\\n"
-             "       SWI9X15C_05.05.58.00.cwe \\\n"
-             "       SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
+             " a) Verify several images at once:\n"
+             "    $ " PROGRAM_NAME " \\\n"
+             "          --verify \\\n"
+             "          SWI9X15C_05.05.58.00.cwe \\\n"
+             "          SWI9X15C_05.05.58.00_Generic_005.025_002.nvu\n"
              "\n"
-             " 3b) Verify all .cwe, .nvu and .spk images inside a directory:\n"
-             " $ find . -regex \".*\\.\\(nvu\\|spk\\|cwe\\)\" -exec " PROGRAM_NAME " -v -z {} \\;\n"
+             " b) Verify all .cwe, .nvu and .spk images inside a directory:\n"
+             "    $ find . -regex \".*\\.\\(nvu\\|spk\\|cwe\\)\" -exec " PROGRAM_NAME " -v -z {} \\;\n"
              "\n"
-             " 3c) Image files may be given within .exe files; extract them with 7-Zip:\n"
-             " $ 7z x SWI9200M_3.5-Release13-SWI9200X_03.05.29.03.exe\n"
-             " $ ls *.{cwe,nvu,spk} 2>/dev/null\n"
-             "   9999999_9999999_9200_03.05.29.03_00_generic_000.000_001_SPKG_MC.cwe\n"
+             " c) Image files may be given within .exe files; extract them with 7-Zip:\n"
+             "    $ 7z x SWI9200M_3.5-Release13-SWI9200X_03.05.29.03.exe\n"
+             "    $ ls *.{cwe,nvu,spk} 2>/dev/null\n"
+             "      9999999_9999999_9200_03.05.29.03_00_generic_000.000_001_SPKG_MC.cwe\n"
              "\n");
 }