BrainStem Firmware Management
Firmware Upgrade Precautions
Reliable power should be used when updating firmware and the update process should be allowed to complete without interruption. An interrupted firmware upgrade process will leave the BrainStem unusable and will require using the firmware recovery process.
Each BrainStem module uses an Acroname developed firmware which contains a boot loader, the BrainStem OS, the reflex virtual machine, access to the BrainStem protocol, and access to functionality specific to each module. Each module's firmware is unique to the module type and the specific module serial number.
The firmware is continuously maintained for bug fixes and feature enhancements. Updates to the firmware can be downloaded from Acroname using the tools detailed below. For large volume customers, offline firmware files can be made available under license.
Firmware Update Tools
BrainStem module firmware can be changed using either the aUpdater graphical user interface (GUI) or through the command line interface (CLI) using aUpdateTool. Both tools are packaged in the BrainStem Support Package available from Acroname Download Page. Download the BrainStem Support package, and extract it to a convenient location on your computer. The base folder of this download will be referred to as "./" through this and other tutorials.
The aUpdater GUI tool provides the simplest method for low volume and manual updates and firmware management. In most cases, this tool requires an internet connection in order to retrieve firmware files, known as ".bird" files. aUpdater can also be used to install firmware files previously downloaded for the same module.
The aUpdateTool CLI tool provides a scriptable and lower level interface to managing BrainStem firmware. This tool also requires an internet connection in most cases, though it can also be used with previously downloaded and offline firmware files.
There are two methods for downloading firmware to the BrainStem modules: live-loading and recovery.
- The live-loading method uses the standard link interface to download new firmware to the module. This method is generally easiest and fastest.
- The recovery method uses a UART interface to force new firmware onto a module. This method is slightly more difficult and slower than live-loading, but is capable to recovering a BrainStem module which has corrupted firmware.
Live-loading Firmware with GUI
The GUI aUpdater application can auto discover all attached BrainStem modules on a specified link. Once discovered, firmware may be managed on each connected BrainStem as follows:
- Open the application from ./acroname/aBinary/aUpdater
- Click the "Add" button
- Select a Link Type to use to discover connected BrainStem modules
- If more than one module is found, a selection dialog will be presented. Select a module to add to the management list.
- If more than one module is in your management list, select a module to manage.
- Click the "Manage" button
- To get the newest available firmware from the Acroname repository, click the "Download" button
- A list of previously downloaded firmware files will be presented. Select the desired version to install
- Click the "Employ" button
- Confirm the firmware download by clicking the "Update" button
- The firmware download will take approximately 20 seconds
While the firmware is downloading to the module, the GUI app will present a progress bar. At the same time, the module's power LED (red) will be steadily ON; the heartbeat LED (green) will be usually ON, while turning OFF briefly in conjunction with the user LED (blue) briefly turning ON. When the firmware download is completed successfully, the module will reset, its heartbeat LED (green) will flash rapidly, and finally the module will re-establish its link with a slowly flashing heartbeat LED (green). It is now safe to remove power from the module or otherwise reset it. Upon reconnecting power or resetting, the module's power LED (red) should be steady and there will be a brief, rapid flash of the heartbeat LED (green).
Screenshot of aUpdater running on Windows 7
Live-loading Firmware with CLI
BrainStem firmware can be changed using the aUpdateTool CLI utility. This method is often used in remote installations and large scale automation systems, including with offline firmware files. Using your computer's operating systems terminal interface, move to the directory containing the BrainStem Support package ("./").
The aUpdateTool has many different parameters. As with all Acroname tools, these parameters may be passed as arguments to the application, or may be specified in a configuration file. Parameters available for the aUpdaterTool may be found by running:
$ ./acroname/aBinary/aUpdateTool -h
The parameters for aUpdateTool are:
[Required] Specifies the module number to be updated. For 40-pin modules, this will be 6 unless the user modifies it.
[Required] Specifies the target module's serial number.
- linktype < usb | serial | ip >
Defined the primary link to the target module. Each link type has many different parameters available in order to fully specify the link as outlined below:
-usb_id: defines the serial number of the USBStem (default 0x00000000). On Windows-based systems, this can be found from the Device Manager. On linux- and Mac-based systems, with similar system information tools or from the terminal using:
$ ls /dev/brainstem* /dev/brainstem.ABCD1235
The USBStem's serial number is an eight digit hexadecimal number at the end of the device name.
E.g.: -linktype usb -usb_id 0xABCD12345
-baudrate: defines the serial baudrate to use (default 9600)
-portname: defines the COM port to use for serial connection (default is system dependent)
E.g.: -linktype serial -baudrate 115200 -portname tty.usbserial-A4004IF0
E.g.: -linktype serial -baudrate 115200 -portname COM4
-ip_port: specifies the port on the IP address to connect to (default 8000)
-ip_address: specifies the target module's IP address (default to host address)
E.g. -linktype ip -ip_address 10.0.0.12 -ip_port 8002
-model <name> Defines the BrainStem model. This parameter is required when performing firmware recovery. E.g. -model USBStem
[Advanced] specifies the desired build number. The parameter is usually only used in production environments where a specific firmware version is needed. It is also usually used in conjunction with the -offline parameter. When used with the -offline parameter, the build number must match an offline firmware file located in the ./acroname/aObject/updater directory. When used without the -offline parameter, the build number must match a version published by Acroname. Contact Acroname for support with this parameter and available firmware versions. When -build is not specified, the most current version firmware available in the Acroname repository is used.
-offline < true | false >
[Advanced] specifies to use an offline firmware file located in the ./acroname/aObject/updater/offline directory. Must be used in conjunction with the -build parameter. This parameter is usually only used in production environments.
An example of updating a USBStem is:
$ ./acroname/aBinary/aUpdateTool -linktype usb -usb_id 0xABCD1234 -module 6 -serial_num 0xABCD1234
An example of offline updating a USBStem is:
$ ./acroname/aBinary/aUpdateTool -linktype usb -usb_id 0xABCD1234 -module 6 -serial_num 0xABCD1234 -offline true -build 130326
Firmware Recovery Process
In very rare cases, the BrainStem modules may become unresponsive or "bricked". This usually occurs when a firmware update is interrupted. A bricked BrainStem, when powered, may have no LEDs ON, or may only show the power LED (red) but will not be able to link to a computer.
Recovering a bricked BrainStem is done with a bootstrap recovery process through the UART0 serial port. Connect the BrainStem to a development board, breakout board or other suitably design PCB which has the UART0 interface exposed (e.g. Acroname parts S46-STEM-DEV-1 or S58-STEM-DEV-3). The S46-STEM-DEV-1 will be used as an example.
Recovery bootstrap process connections
Bootstrap pin detail location
BrainStem Bootstrap Procedure
- Place a jumper wire on the BrainStem module as shown in the following figure.
- Insert a serial adapter (e.g. a USB to serial adapter such as Acroname part S27-USB-SERIAL) into UART0 connector on the development board.
- Apply power to the development board.
- Press the Reset button on the development board.
Now the module will be in bootstrap mode and is ready to be recovered. Executing the recovery should be completed within approximately 30 seconds using either aUpdater or aUpdateTool.
Firmware Recovery with GUI
In order for the aUpdate GUI tool to be used for recovering BrainStem modules, several parameters need to be defined in order to specify the serial connection to the module’s UART0. This parameter definition is done by creating a text file in the same directory as the aUpdater application named “recover.config”. Parameters in this configuration file are separated by new lines. Any text editor may be used to create this file.
The required parameters in the file are:
linktype = serial
specifies to connect to the module with a serial connection
specifies the baudrate to use for firmware download (115200 is recommended)
portname = <port>
specifies the COM port to use for firmware download (e.g. COM4 or tty.usbserial-A4004IF0)
linktype = serial
baudrate = 115200
portname = tty.usbserial-A4004IF0
To recover a BrainStem with the aUpdater GUI:
- Create the configuration file
- Open aUpdater application
- Hold the “Shift” key; the “Add” button will change to a “Recover” button
- Click “Recover”
- Select the module type
- Click start
After the firmware download has completed, the BrainStem module will reboot and perform its first-time boot process. The power LED (red) will be solid and the heartbeat LED (green) will flash rapidly to indicate a successful firmware recover and first-time boot. Press the reset button to reboot the BrainStem into its normal mode.
Firmware Recovery with CLI
The aUpdateTool can be used to recover the firmware with a similar command as firmware download via a serial link, as described above, without needing the serial number or module number.
The required parameters are:
-linktype (and its related sub-parameters)
The -linktype is almost always serial, which requires the -portname parameter and optionally uses the -baudrate parameter.
$ ./acroname/aBinary/aUpdateTool -model "USBStem" -linktype serial -portname tty.usbserial-A4004IF0 -baudrate 115200
Upon successful download of the firmware, press the reset button again. The BrainStem will perform a first-time boot process. The power LED (red) will be solid and the heartbeat LED (green) will flash rapidly to indicate a successful firmware recover and first-time boot. Press the reset button again to reboot the BrainStem into it's normal mode.
Firmware recovery can only be done with an active Internet connection and can only be done using the most current firmware version available. I.e. the aUpdateTool parameters -build and -offline parameters are not valid.