CLI Updater - SG Wireless Document Hub

CLI Updater

Command Line Update Utility

Windows

After installing the Windows version of the updater tool, the CLI tool pycom-fwtool-cli.exe can be found here:

32-Bit Windows: C:\Program Files\Pycom\Pycom Firmware Update\
64-Bit Windows: C:\Program Files (x86)\Pycom\Pycom Firmware Update\

macOS

In order to get access to the CLI tool on macOS, you will need to right click on the Mac version of the updater tool and click Show Package Contents, then navigate to Contents/Resources, here you will find the pycom-fwtool-cli.

Linux

In the Ubuntu 14.04 LTS (and newer) version of the updater tool, pycom-fwtool-cli is installed in /usr/local/bin. In the Generic Linux package, the tool is extracted into folder ./pyupgrade

Usage

usage: pycom-fwtool-cli [-h] [-v] [-d] [-q] [-p PORT] [-s SPEED] [-c] [-x]
                        [--ftdi] [--pic] [-r]
                        {list,chip_id,wmac,smac,sigfox,exit,flash,copy,write,write_remote,wifi,pybytes,cb,nvs,ota,lpwan,erase_fs,erase_all}
                        ...

Update your Pycom device with the specified firmware image file For more
details please see https://docs.pycom.io/chapter/advance/cli.html

positional arguments:
  {list,chip_id,wmac,smac,sigfox,exit,flash,copy,write,write_remote,wifi,pybytes,cb,nvs,ota,lpwan,erase_fs,erase_all}
    list                Get list of available COM ports
    chip_id             Show ESP32 chip_id
    wmac                Show WiFi MAC
    smac                Show LPWAN MAC
    sigfox              Show sigfox details
    exit                Exit firmware update mode
    flash               Write firmware image to flash
    copy                Read/Write flash memory partition
    write               Write to flash memory
    wifi                Get/Set default WIFI parameters
    pybytes             Read/Write pybytes configuration
    cb                  Read/Write config block
    nvs                 Read/Write non volatile storage
    ota                 Read/Write ota block
    lpwan               Get/Set LPWAN parameters [ EU868 US915 AS923 AU915]
    erase_fs            Erase flash file system area
    erase_all           Erase entire flash!

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         show verbose output from esptool
  -d, --debug           show debuggin output from fwtool
  -q, --quiet           suppress success messages
  -p PORT, --port PORT  the serial port to use
  -s SPEED, --speed SPEED
                        baudrate
  -c, --continuation    continue previous connection
  -x, --noexit          do not exit firmware update mode
  --ftdi                force running in ftdi mode
  --pic                 force running in pic mode
  -r, --reset           use Espressif reset mode

How to use the Parameters

The CLI tool uses a combination of global and command specific parameters. The order of parameters is important to avoid ambiguity.

pycom-fwtool-cli [global parameters] [command] [command parameters]

While pycom-fwtool-cli -h shows help for global parameters and a list of available commands, command specific parameters can be viewed using pycom-fwtool-cli [command] -h

The parameter -r, --reset has been added as a courtesy for users of 3rd party ESP32 products. This functionality is not supported by the Expansion Board 2.0 and may cause this tool to crash or hang in certain circumstances.

Global Parameters

`-h / --help`    : shows above help (you can also get detailed help for each sub-command
`-v / --verbose` : show verbose output from esptool.
`-d / --debug`   : show debug output from fwtool.
`-q / --quiet`   : suppress most output, used for scripting
`-p / --port`    : specifies the serial port to be used. Can also be set via **environment variable ESPPORT**
`-s / --speed`   : specifies the serial speed to be used. Can also be set via **environment variable ESPBAUD**
`-c / --continuation` : continue previous connection in FTDI mode. This allows running multiple commands sequentially without having to reset the module. This option is ignored in PIC mode as the module can be reset via the serial connection.
`-x / --noexit`  : This will prevent the PIC from leaving firmware update mode.
`--ftdi`         : This will force the CLI updater to run in FTDI mode.
`--pic`          : This will force the CLI updater to run in PIC mode.
`-r, --reset`    : This will force the CLI updater to use Espressif's workaround to switch into Firmware update mode. This reset method is intended for 3rd party hardware only and is not supported by the Expansion Board 2.0

Commands

list

Get list of available serial ports.

usage: pycom-fwtool-cli list [-h]

optional arguments:
  -h, --help  show this help message and exit

Example: On macOS:

$ pycom-fwtool-cli  list
/dev/cu.usbmodemPy343431  [Pytrack] [USB VID:PID=04D8:F013 SER=Py343434 LOCATION=20-2]
/dev/cu.Bluetooth-Incoming-Port  [n/a] [n/a]

On Windows:

COM6  [Pytrack] [USB VID:PID=04D8:F013 SER=Py343434 LOCATION=20-2]

This is the only command that does not require any additional parameters.

All other commands require that the serial port is specified either through the -p / --port option or through environment variableESPPORT You can optionally specify the speed either through -s / --speed or via environment variable ESPBAUD. The default speed is 921600. The maximum speed for read operations on PIC based expansion boards & shields is 230400. The speed will be reduced automatically if necessary.

Special note for Expansion Board 2.0

You will need to have a jumper wire connected between G23 and GND to use any of the commands below. You will also need to press the reset button either before running each command or at least before running the first command. To avoid having to press the reset button again after each command, you can use the -c / --continuation option. The first command connecting to the device MUST NOT use the -c / --continuation option. This is to make sure a program called _stub_ is uploaded onto the device. This _stub_ cannot be uploaded more than once, so you need to tell the cli tool that the _stub_ is already running, which is done through using the -c / --continuation option.

chip_id

Shows the unique ID of the ESP32 on the connected module.

usage: pycom-fwtool-cli  -p PORT exit [-h]

optional arguments:
  -h, --help  show this help message and exit

wmac

Shows the WiFi MAC of the connected module.

usage: pycom-fwtool-cli  -p PORT wmac [-h]

optional arguments:
  -h, --help  show this help message and exit

smac

Shows the LPWAN MAC of the connected module.

usage: pycom-fwtool-cli  -p PORT smac [-h]

optional arguments:
  -h, --help  show this help message and exit

sigfox

Show sigfox details

usage: pycom-fwtool-cli  -p PORT sigfox [-h]

optional arguments:
  -h, --help  show this help message and exit

exit

If a Pysense/Pytrack/Expansion 3 has previously been left in firmware update mode by using the -x option, this command can be used to exit the firmware update mode.

usage: pycom-fwtool-cli  -p PORT exit [-h]

optional arguments:
  -h, --help  show this help message and exit

flash

Writes firmware image to flash, must be as a .tar(.gz) file as provided by SG Wireless. These files can be found on GitHub.

usage: pycom-fwtool-cli  -p PORT flash [-h] [-t TAR]

optional arguments:
  -h, --help         show this help message and exit
  -t TAR, --tar TAR  perform the upgrade from a tar[.gz] file

copy

Read/Write flash memory partition from/to local file

usage: pycom-fwtool-cli  -p PORT [-h] [-p PARTITION] [-f FILE] [-r] [-b]

optional arguments:
  -h, --help            show this help message and exit
  -p PARTITION, --partition PARTITION
                        The partition to read/write (all, fs, nvs, factory,
                        secureboot, bootloader, partitions, otadata, fs1,
                        ota_0, config)
  -f FILE, --file FILE  name of the binary file (default: -.bin)
  -r, --restore         restore partition from binary file
  -b, --backup          backup partition to binary file (default)

write

Write to a specific location in flash memory.

usage: pycom-fwtool-cli  -p PORT write [-h] [-a ADDRESS] [--contents CONTENTS]

optional arguments:
  -h, --help            show this help message and exit
  -a ADDRESS, --address ADDRESS
                        address to write to
  --contents CONTENTS   contents of the memory to write (base64)

wifi

Get/Set default WiFi parameters.

usage: pycom-fwtool-cli wifi [-h] [--ssid SSID] [--pwd PWD] [--wob [WOB]]

optional arguments:
  -h, --help   show this help message and exit
  --ssid SSID  Set Wifi SSID
  --pwd PWD    Set Wifi PWD
  --wob [WOB]  Set Wifi on boot

CTRL

Read/Write CTRL configuration.

usage: pycom-fwtool-cli pybytes [-h] [--token TOKEN] [--mqtt MQTT] [--uid UID]
                                [--nwprefs NWPREFS] [--extraprefs EXTRAPREFS]

optional arguments:
  -h, --help            show this help message and exit
  --token TOKEN         Set Device Token
  --mqtt MQTT           Set mqttServiceAddress
  --uid UID             Set userId
  --nwprefs NWPREFS     Set network preferences
  --extraprefs EXTRAPREFS
                        Set extra preferences

Note: The local pybytes_config.json file is overwritten when making any modifications using this command (requires CTRL firmware 1.17.5.b6 or higher and Firmware updater 1.14.3).

cb

Read/Write config block (LPMAC, Sigfox PAC & ID, etc.). You can find the structure of this block here

usage: pycom-fwtool-cli  -p PORT cb [-h] [-f FILE] [-b] [-r]

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  name of the backup file
  -b, --backup          backup cb partition to file
  -r, --restore         restore cb partition from file

If neither -b or -r is provided, the command will default to backup. If no file name is provided, <WMAC>.cb is used.

To backup your config block: $pycom-fwtool-cli -p PORT cb

To restore your config block: $pycom-fwtool-cli -p PORT cb -r -f backup.cb

nvs

Read/Write non-volatile storage.

usage: pycom-fwtool-cli  -p PORT nvs [-h] [-f FILE] [-b] [-r]

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  name of the backup file
  -b, --backup          backup cb partition to file
  -r, --restore         restore cb partition from file

If neither -b or -r is provided, the command will default to backup. If no file name is provided, <WMAC>.nvs is used.

To backup your NVS: $ pycom-fwtool-cli -p PORT nvs

To restore your NVS: $ pycom-fwtool-cli -p PORT nvs -r -f backup.nvs

ota

Read/Write ota block, this contains data relating to OTA updates such as the hash of the OTA firmware.

usage: pycom-fwtool-cli  ota [-h] [-f FILE] [-b] [-r]

optional arguments:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  name of the backup file
  -b, --backup          backup cb partition to file
  -r, --restore         restore cb partition from file

If neither -b nor -r is provided, the command will default to backup. If no file name is provided, <WMAC>.ota is used.

To backup your OTA block: $pycom-fwtool-cli -p PORT ota

To restore your OTA block: $pycom-fwtool-cli -p PORT ota -r -f backup.ota

lpwan

Get/Set LPWAN parameters saved to non-volatile storage. Please see here for more details.

usage: pycom-fwtool-cli  -p PORT lpwan [-h] [--region REGION]

optional arguments:
  -h, --help       show this help message and exit
  --region REGION  Set default LORA region
  --erase_region   Erase default LORA region
  --lora_region    Output only LORA region

erase_fs

Erase flash file system area. This is useful if some code running on the device is preventing access to the REPL.

usage: pycom-fwtool-cli  -p PORT erase_fs [-h]

optional arguments:
  -h, --help  show this help message and exit

erase_all

Erase entire flash, only use this if you are sure you know what you are doing. This will remove your devices lpwan mac addresses etc.

usage: pycom-fwtool-cli erase_all [-h]

optional arguments:
  -h, --help  show this help message and exit