Pycom Documentation
  • Introduction
  • Pycom Products
  • Getting Started
    • Introduction
    • Hardware Setup
      • LoPy
      • LoPy 4
      • SiPy
      • GPy
      • FiPy
      • WiPy
    • Software
      • Drivers
      • Updating Firmware
      • Pymakr
    • Programming the modules
      • Introduction to MicroPython
      • MicroPython Examples
      • Your first Pymakr project
      • REPL
        • Serial USB (UART)
        • Telnet REPL
      • FTP
      • Safe boot
    • Device Registration
      • Sigfox
      • Cellular
      • LoRaWAN
        • The Things Network
        • Objenious
  • Pymakr Plugin
    • Installation
      • Atom
      • Visual Studio Code
    • Tools/Features
    • Settings
  • Pytrack, Pysense, Pyscan
    • Introduction
    • Installing Software
      • Updating Firmware
      • Installing Drivers - Windows 7
      • Installing Libraries
    • API Reference
      • Pytrack
      • Pysense
      • Pyscan
      • Sleep
  • Tutorials & Examples
    • Introduction
    • All Pycom Device Examples
      • REPL
      • WLAN
      • Bluetooth
      • HTTPS
      • MQTT
      • AWS
      • ADC
      • I2C
      • Onewire Driver
      • Threading
      • RGB LED
      • Timers
      • PIR Sensor
      • Modbus
      • OTA update
      • RMT
      • Socket
      • Touch
    • LoRa Examples
      • LoRa-MAC (Raw LoRa)
      • LoRaWAN with OTAA
      • LoRaWAN with ABP
      • LoRa-MAC Nano-Gateway
      • LoPy to LoPy
      • LoRaWAN Nano-Gateway
      • RN2483 to LoPy
      • LoRa Mesh
      • PyMesh Border Router
    • Sigfox Examples
    • LTE Examples
      • CAT-M1
      • NB-IoT
      • Module IMEI
      • Modem Firmware Update
    • Pytrack Examples
    • Pysense Examples
    • Pyscan Examples
  • Firmware & API Reference
    • Introduction
    • Pycom Modules
      • machine
        • ADC
        • DAC
        • I2C
        • Pin
        • PWM
        • RTC
        • SPI
        • UART
        • WDT
        • Timer
        • SD
        • CAN
        • RMT
      • network
        • WLAN
        • Server
        • Bluetooth
          • GATT
          • GATTCConnection
          • GATTCService
          • GATTCCharacteristic
          • GATTSService
          • GATTSCharacteristic
        • LoRa
          • Pymesh
        • Sigfox
        • LTE
      • AES
      • pycom
    • MicroPython Modules
      • micropython
      • uctypes
      • sys
      • uos
      • array
      • cmath
      • math
      • gc
      • ubinascii
      • ujson
      • ure
      • usocket
      • select
      • utime
      • uhashlib
      • ussl
      • ucrypto
      • ustruct
        • uzlib
      • _thread
      • Builtin
    • Notes
  • Product Info, Datasheets
    • Introduction
    • Development Modules
      • WiPy 2.0
      • WiPy 3.0
      • LoPy
      • LoPy 4
      • SiPy
      • GPy
      • FiPy
    • OEM Modules
      • W01
      • L01
      • L04
      • G01
      • L01 OEM Baseboard Reference
      • Universal OEM Baseboard Reference
    • Expansion Boards and Shields
      • Expansion Board 3.0
      • Pytrack
      • Pysense
      • Pyscan
      • Expansion Board 2.0
      • Deep Sleep Shield
        • Deep Sleep API
    • Notes
  • Pybytes
    • Introduction
    • Getting Started with Pybytes
    • Add a device to Pybytes
      • Connect to Pybytes: Quick Add
      • Connect to Pybytes: Flash Pybytes library manually
      • Add Sigfox device
        • DevKit contract
        • Custom contract
    • Visualise data from your device
    • Integrations
      • Amazon IoT
  • Documentation Notes
    • Introduction
    • Syntax
    • REPL vs Scripts
    • Mesh Networks
  • Advanced Topics
    • Firmware Downgrade
    • CLI Updater
    • SecureBoot and Encryption
    • License
  • Have a question?
    • Ask on the Forum
Powered by GitBook
On this page
  • Command Line Update Utility
  • Usage
  • How to use the Parameters
  • Global Parameters
  • Commands
  1. Advanced Topics

CLI Updater

PreviousFirmware DowngradeNextSecureBoot and Encryption

Last updated 6 years ago

Command Line Update Utility

Windows

After installing the 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 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 (and newer) version of the updater tool, pycom-fwtool-cli is installed in /usr/local/bin. In the 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 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 variable ESPPORT 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

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: <wmac>-<part>.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

pybytes

Read/Write pybytes 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 Pybytes firmware 1.17.5.b6 or higher and Firmware updater 1.14.3).

cb

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

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

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

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

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

Windows version
Mac version
Ubuntu 14.04 LTS
Generic Linux
GitHub
here.
here