homechevron_rightDocschevron_rightNotecardchevron_rightNotecard Walkthroughchevron_rightUpdating Notecard Firmware

Updating Notecard Firmware

Blues frequently releases updated firmware for Notecard, introducing new features and enhancements. The following instructions outline various methods for updating Notecard firmware.

Are you trying to implement OTA firmware updates on a host MCU? Please see our guide on Host Firmware Updates.

warning

Make sure you read and understand the Blues Firmware Release Policies and Procedures before updating Notecard firmware.

Methods for Updating Notecard Firmware

DFU with In-Browser Terminal CellCell+WiFiLoRaWiFi

If your Notecard device is running Developer Firmware v5.3.1 or later, you may update Notecard firmware manually using the In-Browser Terminal and no other tools.

This method is preferred over using STM32CubeProgrammer because:

  1. It does not put the Notecard at risk of erasing the entire flash memory.
  2. It does not require installation of STM32CubeProgrammer.

Firmware Update Process

Connect your Notecard device to your computer via USB and then connect to your Notecard in the In-Browser Terminal.

Once connected, the easiest way to upgrade Notecard firmware is to use the firmware install latest command, which automatically installs the most recent Notecard firmware release.

> 
firmware install latest

If you instead wish to install a specific version of the Notecard firmware, you can enter the firmware list command to list all available versions of Notecard firmware.

> 
firmware list
~ 8 Firmware
~  Date                   Version          Notes                                 
~  2021-11-17 (2yr ago)   notecard-2.1.1   LTS (Long Term Support) Release       
~  2022-02-19 (1yr ago)   notecard-2.2.1   LTS (Long Term Support) Release       
~  2022-06-13 (1yr ago)   notecard-2.3.1   LTS (Long Term Support) Release       
~  2022-12-06 (7mo ago)   notecard-4.1.1   LTS4xx Initial Release                
~  2023-01-27 (6mo ago)   notecard-2.4.1   LTS2xx Maintenance Release            
~  2023-02-27 (5mo ago)   notecard-4.2.1   LTS4xx Q1 2023 maintenance release    
~  2023-05-05 (2mo ago)   notecard-4.4.1   LTS4xx Q2 2023 maintenance release    
~  2023-05-11 (2mo ago)   notecard-5.1.1   2023 Q1 Developer Release  
~  2023-09-01 (1wk ago)   notecard-5.3.1   2023 Q3 Developer Release

Next, use firmware install <version-name>, where <version-name> is the name of the firmware binary from the Version column above.

> 
firmware install <version-name>
warning

If you update Notecard firmware to a version less than v5.3.1, any subsequent firmware updates would have to be performed with either STM32CubeProgrammer or Notehub.

Upon completion of the firmware update, Notecard will restart. Verify Notecard's firmware has been updated when the In-Browser Terminal reconnects, or by issuing the card.version command:

> 
{"req":"card.version"}

DFU with Notecard CLI CellCell+WiFiLoRaWiFi

If your Notecard device is running Developer Firmware v5.3.1 or later, you may update Notecard firmware manually using the Notecard CLI and no other tools.

This method is preferred over using STM32CubeProgrammer because:

  1. It does not put the Notecard at risk of erasing the entire flash memory.
  2. It does not require installation of STM32CubeProgrammer.

Prerequisites

  1. Installation of the latest version of the Notecard CLI.
  2. A fresh Notecard binary file (downloaded from the list of Notecard Firmware Releases).

Firmware Update Process

Connect your Notecard device to your computer via USB. Using a terminal or command prompt, navigate to the folder containing the Notecard firmware binary you want to load, and enter the following command:

$ 
notecard -fast -sideload notecard-<version-build>.bin

The notecard-<version-build>.bin represents the name of the firmware image you downloaded and want to install on the Notecard. You may need to prepend notecard with the absolute path name if it is not in your PATH.

warning

If you update Notecard firmware to a version less than v5.3.1, any subsequent firmware updates would have to be performed with either STM32CubeProgrammer or Notehub.

Wait while the firmware downloads and installs:

sending DFU binary to notecard
side-loading 8192 bytes (100% 925167 remaining)
side-loading 8192 bytes (99% 916975 remaining)
side-loading 8192 bytes (98% 908783 remaining)
side-loading 8192 bytes (97% 900591 remaining)
...
note

If you see a repeated message about the Notecard being disconnected, simply exit the process by pressing ctrl-c.

retrying after error: error opening serial port: serial device not available {io}

Within a few seconds the Notecard should restart. Verify the Notecard's firmware has been updated with the following command:

$ 
notecard -info
Blues Wireless Notecard
               DeviceUID: dev:864475040000000
           Serial Number: 
            Notehub Host: a.notefile.net
        Firmware Version: notecard-5.3.1
                     SKU: NOTE-NBGL-500

DFU with STM32CubeProgrammer CellCell+WiFiLoRaWiFi

You can manually update Notecard firmware by directly connecting to a Notecard over USB and using STM32CubeProgrammer .

warning

Blues does not recommend using STM32CubeProgrammer to update Notecard firmware due to the risk of erasing the entire flash memory. If possible, instead use the DFU with In-Browser Terminal, DFU with Notecard CLI, or OTA DFU with Notehub instructions.

Prerequisites

  1. Serial terminal emulator software (e.g. the In-Browser Terminal, CoolTerm , or TinyTerm ).
  2. A fresh Notecard binary file (downloaded from the list of Notecard Firmware Releases).
  3. STM32CubeProgrammer (download the latest version for your OS).

STM32CubeProgrammer Installation Notes

Installing STM32CubeProgrammer requires OS-specific instructions.

warning

The minimum version of STM32CubeProgrammer we support is 2.11.0.

Version 2.16.0 is not recommended, because it fails to flash Notecard correctly. If needed, follow these instructions to recover a bricked Notecard.

If you're on a version of Windows older than Windows 10, you'll first need to install the STM32 Virtual COM Port Driver .

Download and extract the zip package and run the installer (ignoring the security issues from Windows).

Download and extract the zip package (noting that the version number of 2.15.0 used in these instructions will likely change in the future).

Using your terminal app of choice, navigate to the extracted directory and launch the installer in CLI mode. For example:

$ 
sudo ./SetupSTM32CubeProgrammer-2.15.0.app/Contents/MacOs/SetupSTM32CubeProgrammer-2_15_0_macos

Prior to installation, make sure you have the following packages installed:

  • libusb-1.0-0-dev
  • unzip

If you are using a USB port to connect to the STM32 device, install the libusb1.0 package by typing the following command:

$ 
sudo apt-get install libusb-1.0.0-dev
note

Please note libusb1.0.12 version or higher is required to run STM32CubeProgrammer.

Extract the zip package downloaded earlier from ST , and execute it. Note the version number may change.

$ 
unzip en.stm32cubeprg-lin_v2-11-0_v2.11.0 && cd en.stm32cubeprg-lin_v2-11-0_v2.11.0 && ./SetupSTM32CubeProgrammer-2.11.0.linux

Copy the rules files into /etc/udev/rules.d/. This is needed use ST-LINK probe or USB DFU.

$ 
sudo cp ~/STMicroelectronics/STM32Cube/STM32CubeProgrammer/Drivers/rules/* /etc/udev/rules.d

Firmware Update Process

Connect your Notecard device to your computer via USB. Verify that your terminal emulator (e.g. In-Browser Terminal, CoolTerm, or TinyTerm) is able to connect to the device by sending the card.version request:

> 
{"req": "card.version"}

The response should look similar to this:

{
 "version": "notecard-5.3.1.16292",
 "device": "dev:864622040385086",
 "name": "Blues Wireless Notecard",
 "sku": "NOTE-NBNA500",
 "board": "1.11",
 "cell": true,
 "gps": true,
 "api": 5,
 "body": {
  "org": "Blues Wireless",
  "product": "Notecard",
  "target": "r5",
  "version": "notecard-5.3.1",
  "ver_major": 5,
  "ver_minor": 3,
  "ver_patch": 1,
  "ver_build": 16292,
  "built": "Sep 17 2023 20:28:51"
 }
}

Important: Launch the built-in bootloader firmware by sending the bootloader command via your terminal emulator:

> 
bootloader
note

In Windows Device Manager, this causes Notecard to disappear as a "Ports (COM LPT)/USB Serial Device (VID 0x30A4, PID 0x0001)" and to reappear as a "Universal Serial Bus devices/STM32 BOOTLOADER (VID 0x0438, PID 0xDF11)".

With your device in bootloader mode, your final step is to upload flash the new firmware on your device using STM32CubeProgrammer. The specific steps you need to complete depends on the type of Notecard you are updating.

Using the STM32CubeProgrammer CellCell+WiFiWiFi

Complete the following steps if you’re updating firmware on Notecard Cellular, Notecard Cell+WiFi, or Notecard WiFi.

Open the STM32CubeProgrammer application.

Select "USB" from the dropdown menu provided in the upper-right corner:

connecting to device over usb

Select the port corresponding to your Notecard in the "Port" dropdown menu (likely "USB1"). You may need to click the button next to the port dropdown to refresh the list.

Click the "Connect" button and the log should update and display Data read successfully.

Next, access the "Erasing & Programming" screen by clicking the menu button with the arrow pointing down:

erasing and programming firmware

Follow the other configuration options in the image above:

  • Select the appropriate firmware .bin file.
  • Check the "Verify programming" box.
  • Check the "Run after programming" box.
  • Finally, click the "Start Programming" button.
warning

Never enable the "Full chip erase" option as you will wipe the Notecard in a way that renders it permanently unusable.

After a few seconds of commands displayed in the log, you should see multiple dialog warnings/notifications to click through and confirm.

In lieu of using the STM32CubeProgrammer GUI, you may use the STM32_Programmer_CLI that is installed alongside the GUI.

Make sure STM32_Programmer_CLI (macOS, Linux) or STM32_Programmer_CLI.exe (Windows) is in your PATH (or provide its absolute path in the command below). The program should have been installed in the same directory as STM32CubeProgrammer / STM32CubeProgrammer.exe.

Run the following command, substituting the path to your desired .bin firmware file, keeping in mind the serial port specified may be different depending on your OS:

$ 
STM32_Programmer_CLI --connect port=USB1 --write [path/to/binary.bin] 0x08000000 --verify --go 0x08000000

Results

Once the update process is complete, your Notecard will reset and reconnect. You can verify the firmware process was successful by executing another card.version request and inspecting the version parameter.

> 
{"req": "card.version"}

Using the STM32CubeProgrammer (LoRa) LoRa

Complete the following steps if you’re updating firmware on Notecard LoRa.

Open the STM32CubeProgrammer application.

Select "UART" from the dropdown menu provided in the upper-right corner:

connecting to device over uart

Select the port corresponding to your Notecard in the "Port" dropdown menu (likely something similar to "tty.usbserial-xxxxxx"). You may need to click the button next to the port dropdown to refresh the list.

Selecting a port in STM32CubeProgrammer

Click the "Connect" button and the Log at the bottom of the screen should update and display Data read successfully.

Next, access the "Erasing & Programming" screen by clicking the menu button with the arrow pointing down:

Erasing and programming firmware for Notecard LoRa

Follow the other configuration options in the image above:

  • Select the appropriate firmware .bin file.
  • Check the "Verify programming" box.
  • Check the "Run after programming" box.
  • Finally, click the "Start Programming" button.
warning

Never enable the "Full chip erase" option as you will wipe the Notecard in a way that renders it permanently unusable.

After a few seconds of commands displayed in the log, you should see multiple dialog warnings/notifications to click through and confirm.

In lieu of using the STM32CubeProgrammer GUI, you may use the STM32_Programmer_CLI that is installed alongside the GUI.

Make sure STM32_Programmer_CLI (macOS, Linux) or STM32_Programmer_CLI.exe (Windows) is in your PATH (or provide its absolute path in the command below). The program should have been installed in the same directory as STM32CubeProgrammer / STM32CubeProgrammer.exe.

Run the following command, substituting the path to your desired .bin firmware file and the port of your device. On macOS and Linux you can use ls /dev/tty.* to find the appropriate port. On Windows you can use the STM32CubeProgrammer GUI or the mode command to find the port to use.

$ 
STM32_Programmer_CLI --connect port=/dev/tty.usbserial-xxxxx --write [path/to/binary.bin] 0x08000000 --verify --go 0x08000000

Results

Once the update process is complete, your Notecard will reset and reconnect. You can verify the firmware process was successful by executing another card.version request and inspecting the version parameter.

> 
{"req": "card.version"}

OTA DFU with Notehub CellCell+WiFiWiFi

Notehub lets you manage the firmware running on your Notecards, making it easy to select from available firmware and deploy it to one or more devices.

Along with using the Notehub UI to manage firmware releases, specific reserved environment variables and the Notehub API both provide methods for managing Notecard and host MCU firmware updates.

warning

Notecard LoRa does not support management firmware updates via Notehub.

Deploy Firmware

  1. Select Devices from the left navigation bar and select a device from the list of devices in the Notecard Firmware tab.

    Device selected from list

  2. Select Update from the available options.

    Update option

  3. Select the firmware you wish to apply from the list of available firmware, and click Apply.

    Select Notecard firmware

  4. Confirm you wish to update the Notecard firmware.

    Notecard firmware update confirmation

  5. Now that you have selected your firmware, you will see it in the Requested Version field.

    Notecard firmware requested

  6. The next time the Notecard syncs with Notehub, it will begin the download and installation process. No further action is needed on your part as the Notecard will update itself after it downloads the binary. You can view the current status of the update any time in the DFU Status field, by navigating to the device details and clicking on the Notecard Firmware tab, or by using the Notehub API to get the status of the DFU.

    Notecard firmware requested

note
  1. If using a Notecard Cellular, please be aware that OTA DFU will use data from your cellular data plan.
  2. OTA DFU is not supported on a Notecard device when the hub.set "mode" argument is "minimum" or "off".

Additional Resources