Updating Firmware via CLI

BrainStem firmware can be modified using the Updater CLI utility. This method is often very useful in remote installations and large scale automation systems as it is easily invoked with a simple script. Using your computer’s operating systems terminal interface, navigate to the “Bin” folder located in the Brainstem Dev Kit download. Downloads for all of Acroname’s products can be found at Download Center under the Support tab.

Parameters and commands available for the Updater may be found by running the utility without any commands or arguments (When running Updater on a Mac or Linux you will need to use “./”. Windows does not require this).

Note: The following examples will be preformed from a Mac.

$> ./Updater

If you would like additional help information, including examples you can use the -H command.

$> ./Updater -H

Updater (Version: 2.10.1 Sep 28 2023)
(Copyright (C) 1994-2023, Acroname Inc.)

Application Usage:
Updater <-B | -D | -G | -U > [-Hh | --help] [-b build_num]
    [-d serial_num]
    [-t transport] [-r router_serial]
    [-s serial_port] [-o baud_rate]

  BrainStem Update and Maintenance Application
    -H -h or --help for full usage information.

  Parameters to commands:
     -b <build number>        - Build version of the firmware to transfer.
                                [Default: latest version available].
     -d <device>              - Device serial number of the device to access.
     -t <transport type>      - communications method [USB,TCP,RECOVER].
     -r <router serial>       - indirect connection through router device
     -s <serial port>         - name of serial port to use for recovery
     -o <baud rate>           - baud rate for serial port (2400, 4800, 9600,
                                19200, 38400, 57600, 115200, 230400)
  Commands:
     -B                       - list the Builds available for given device.

     -D                       - Discover devices that are currently connected.

     -G                       - Get build file from the Acroname server and
                                store on local machine for download to device.
                                Must specify a specific device ["-d" option].
                                Default is to obtain the latest build for the
                                given device, override with "-b" option.

     -U                       - Update the firmware on device specified.
                                Must specify a specific device ["-d" option].
                                Default is to download the latest build for the
                                given device, override with "-b" option or
                                specify specific BIRD file using "-f" option.
     -H or -h                 - Display extended usage information.

 Sample usage:

-D                             Discover all devices connected by either USB or TCPIP.
                               Records the device information into the settings for that device.

-D -t USB                      Discover all the devices connected by USB. Records the
                               device information into the settings for that device.

-D -t USB -d 0F5849A           Discover settings of the specific device (serial number 0x40F5849A)

-G -d 40F5849A                 Get the latest firmware for the given device.
                               Downloads the firmware file into the updater specific device directory.

-U -d 40F5849A                 Update the firmware on the specific device.
                               Without other options, this command will try to locate
                               the latest firmware version to be used for updating the device.

-G -d 40F5849A -b 99528558     Get the specified build's firmware for the given device.
                               Downloads the firmware file into the updater's specific
                               device directory with the build number as the filename.

-G -U -d 40F5849A              Get the latest firmware for the given device.
                               Downloads the firmware file into the updater specific
                               device directory. After download, update the firmware
                               using the latest release.

-U -t RECOVER -s /dev/serial   Update the firmware as described above, but uses the serial interface
                               in communicating with the device to install the latest firmware.

 Sample usage for network discovery and updates:

-D -r D272031D                 Discover all devices connected to the I2C BrainStem network
                               of the given routing device D272031D.

-G -U -d 2181F0EE -r D272031D
                               Get and Update to the latest firmware for device 2181F0EE
                               indirectly through routing device D272031D.

As you can see there are a lot of options for customizing the Updater utility to meet your needs; however, there are just a few basic command that will fit the needs of most users.

Next we will look at a few examples of how to use the updater.

Example: Updating to the Latest Firmware

In this example we will go through the steps required to update our BrainStem module. We will be using a 40pin USBStem module throughout this excersize; however, the other modules work in a similar way.

Make sure your device is connected and has power. Refer to the Getting Started page for additional information.

Checking for connected devices:

This command will check for USB devices connected to your machine.

$> ./Updater -D

Looking at the output below you can see that two devices were discovered, one USBHub3+ and one USBHub3c. In this example we will be using the USBHub3c information. This information will be handy in the next step as we will need the serial number of our device in order to update it.

Updater (Version: 2.10.1 Sep 28 2023)
Searching for BrainStem devices
Discovered Devices: (USB)
    Device    Module   Router  Model          Firmware Version (Build)
    3C43352C  06       06      USBHub3c       2.10.2 (1234567890)
    F7D9AFB6  06       06      USBHub3p       2.10.2 (4101717688)

Getting the latest firmware from Acroname’s servers:

Using the serial number for the relevant device above, we will construct the following command. The “-G” will pull the most recent firmware from Acroname’s server for the given device serial number (“-d”).

$> ./Updater -G -d 0x3C43352C

Updater (Version: 2.10.1 Sep 28 2023)
Retrieving firmware for device with serial number 3C43352C
No build specified
Using Latest build
Retrieving build 1256480617
Validating build 1256480617 with server
Build 1256480617 is valid

Loading the latest firmware:

Now that we have successfully pulled the most up to date firmware we now need to apply it to the device. The following code will apply the most up to date firmware to the given device.

$> ./Updater -U -d 0x3C43352C

Updater (Version: 2.10.1 Sep 28 2023)
Updating from Birdfile: /Users/cgoss/.acroname/updater/3C43352C/1256480617.bird
Transferring loader to device
Transferring loader block 1 of 3, 65540 bytes
Transferring loader block 2 of 3, 50068 bytes
Transferring loader block 3 of 3, 12288 bytes
Transferred 3 blocks, 127896 total bytes
Starting Load on Device
Transferring firmware block 1 of 20, 65540 bytes
Transferring firmware block 2 of 20, 65540 bytes
Transferring firmware block 3 of 20, 65540 bytes
Transferring firmware block 4 of 20, 65540 bytes
Transferring firmware block 5 of 20, 65540 bytes
Transferring firmware block 6 of 20, 65540 bytes
Transferring firmware block 7 of 20, 65540 bytes
Transferring firmware block 8 of 20, 49268 bytes
Transferring firmware block 9 of 20, 57348 bytes
Transferring firmware block 10 of 20, 65540 bytes
Transferring firmware block 11 of 20, 65540 bytes
Transferring firmware block 12 of 20, 65540 bytes
Transferring firmware block 13 of 20, 65540 bytes
Transferring firmware block 14 of 20, 65540 bytes
Transferring firmware block 15 of 20, 65540 bytes
Transferring firmware block 16 of 20, 49268 bytes
Transferring firmware block 17 of 20, 3924 bytes
Transferring firmware block 18 of 20, 3924 bytes
Transferring firmware block 19 of 20, 4104 bytes
Transferring firmware block 20 of 20, 8 bytes
Transferred 20 blocks, 1019864 total bytes
Update time: 57.5460 sec

At this point the firmware has been downloaded to the device and the device has reset and is running with the new firmware.

Example: Reverting to a Previous Version

In our next example we are going to assume that we have just updated to the 2.1.5 firmware; however, for some reason we are not satisfied with how the device is behaving and we want to return back to 2.1.4. With the Updater utility this is easy to do.

Before we begin lets make sure your device is connected and has power. Refer to the Getting Started page for additional information.

Locating the previous firmware:

Using the ‘-B’ command we can request the available builds for a given device. Since firmware is specific to each device we must also supply the device’s serial number with the ‘-d’ parameter.

$> ./Updater -B -d 0x3C43352C

Below you will see what was printed on my machine [1]. All we need to do is take note of the specific build number that is associated with the version we would like to revert to.

Updater (Version: 2.10.1 Sep 28 2023)
Build List for device [3C43352C]:

Build          	Version
910961995      	2.10.0
3592403412     	2.10.1
1256480617     	2.10.2
287855797      	2.9.16
273238664      	2.9.17
3802420316     	2.9.18
804960244      	2.9.19
3723629684     	2.9.20
526817175      	2.9.21
3401723282     	2.9.22
619738343      	2.9.24
2286324745     	2.9.25
3108222154     	2.9.26
2422939150     	2.9.27
227123222      	2.9.28
2425394894     	2.9.29

Applying a specific build to a device:

As previously explained we are hypothetically having issues with our device after updating and we want to revert to a previous version. Now that we have located the previous build number lets apply it by adding the “-b” parameter to the last command in the example before.

$> ./Updater -G -U -d 0x3C43352C -b 227123222

You should see something similar to the below output.

Updater (Version: 2.10.1 Sep 28 2023)
Retrieving firmware for device with serial number 3C43352C
Retrieving firmware build 227123222
Retrieving build 227123222
Validating build 227123222 with server
Build 227123222 is valid
Updating firmware with build: 227123222
Transferring loader to device
Transferring loader block 1 of 3, 65540 bytes
Transferring loader block 2 of 3, 50068 bytes
Transferring loader block 3 of 3, 12288 bytes
Transferred 3 blocks, 127896 total bytes
Starting Load on Device
Transferring firmware block 1 of 20, 65540 bytes
Transferring firmware block 2 of 20, 65540 bytes
Transferring firmware block 3 of 20, 65540 bytes
Transferring firmware block 4 of 20, 65540 bytes
Transferring firmware block 5 of 20, 65540 bytes
Transferring firmware block 6 of 20, 65540 bytes
Transferring firmware block 7 of 20, 65540 bytes
Transferring firmware block 8 of 20, 49268 bytes
Transferring firmware block 9 of 20, 57348 bytes
Transferring firmware block 10 of 20, 65540 bytes
Transferring firmware block 11 of 20, 65540 bytes
Transferring firmware block 12 of 20, 65540 bytes
Transferring firmware block 13 of 20, 65540 bytes
Transferring firmware block 14 of 20, 65540 bytes
Transferring firmware block 15 of 20, 65540 bytes
Transferring firmware block 16 of 20, 49268 bytes
Transferring firmware block 17 of 20, 3924 bytes
Transferring firmware block 18 of 20, 3924 bytes
Transferring firmware block 19 of 20, 4104 bytes
Transferring firmware block 20 of 20, 8 bytes
Transferred 20 blocks, 1019864 total bytes
Update time: 57.5460 sec

Confirm that you have successfully restored the old firmware:

Just to be safe lets confirm that we have successfully restored the old firmware. This can be done by issuing the discover command.

$> ./Updater -D

As you can see the device is now running the 2.9.28 firmware.

Updater (Version: 2.10.1 Sep 28 2023)
Searching for BrainStem devices
Discovered Devices: (USB)
    Device    Module   Router  Model          Firmware Version (Build)
    3C43352C  06       06      USBHub3c       2.9.28 (227123222)
    F7D9AFB6  06       06      USBHub3p       2.10.2 (4101717688)

[1]

This output was spliced in to reflect the changes in Updaters output. Therefor, the build numbers will not align with the rest of the example.