Guralp Systems Limited
MAN-EAM-0003 - Acquisition Modules and Platinum Firmware - Technical Manual

Chapter 5. Platinum Firmware Upgrades

Platinum firmware is regularly updated to provide extra features, improve performance and, occasionally, to correct errors. The upgrade process is normally fast, simple and can be carried out remotely using either the web or command-line interface (but see the important notes, below).

Note: This procedure does not upgrade the firmware of connected or embedded digitisers, which should be upgraded using the web interface or the dm24-upgrade command as documented in section 8.2.3.

The upgrade process makes use of the rsync protocol which uses an elegant and efficient algorithm to, effectively, transfer only the differences between revisions; even within individual files. This significantly reduces the time required compared to traditional upgrade methods.

5.1 Important notes regarding build 10,000

5.1.1 Significant changes at build 10,000

All systems that run Platinum, excluding the CMG-NAM, are based around ARM microprocessors. Platinum relies on the Linux operating system and a number of utility programs which are made freely available by the ARM development community. In 2010, this community agreed a new specification for the way that programs interact with the operating system and each other. This specification is know as the Application Binary Interface, or ABI. The new ABI was called the “EABI” and the original one was retrospectively renamed the “OABI”, for old ABI. The two paradigms cannot coexist and all new community development will be carried out using the newer EABI.

For this reason, starting with build 10,000, Platinum development also moved to the EABI.

Using the EABI requires the use of a different compiler and, to simplify development, a similar compiler change has been made for CMG-NAM and CMG-NAM64 development.

The decision to use the EABI and the new compiler has one significant consequence – an upgrade from a build before 10,000 to a current build is vulnerable to interruptions in a way that no other upgrade is. This has implications for systems installed in remote locations.

5.1.2 Systems installed in remote locations

Programs using the EABI cannot interoperate (on the same processor) with programs using the OABI. There are also problems when mixing programs built using the two different compilers. For this reason, it is important that an upgrade from build 3801 to build 10,000 or later is not interrupted.

The upgrade mechanism has, until now, been extremely tolerant of interruptions and it has been normally sufficient to simply restart an interrupted upgrade process. This will also be true for future upgrades, once build 10,000 or higher has first been installed.

For upgrades from build 3801 to build 10,000 or later, however, it is highly recommended that an upgrade to an acquisition module only be carried out in a situation with a stable power supply, a reliable internet connection and where you have physical access to the unit.

5.1.3 Procedures for upgrades spanning build 10,000

5.1.3.1 CMG-EAMs

An extra step must be taken when upgrading from build 3801 to the latest build and special attention must be paid to the amount of free disk space available. Please see this article on our web site for complete information and detailed instructions:

www.guralp.com/sw/eam-eabi-upgrade

5.1.3.2 CMG-NAMs and CMG-NAM64s

After upgrading from build 3801 to the latest build, you may see several FATAL: kernel too old messages. In order to resolve this issue, please log in to the command line as root and run the command:

/sbin/manual-post-upgrade

If, despite all precautions, the upgrade is interrupted at a crucial time, attempt first to restart the upgrade. If this fails, please follow the recovery instructions available from our web site at:

www.guralp.com/sw/nam-nam64-platinum-firmware-recovery

5.1.3.3 CMG-DCMs

When upgrading a CMG-DCM, the upgrade process should be carried out twice. The second run will resolve problems with broken symlinks. During the first upgrade run, you may see several errors about “Directory not empty and references to broken files. These are normal and the second upgrade invocation is designed to resolve these problems and leave the system in a consistent state.

5.2 Determining the current firmware level

To determine the current firmware version from the web interface, select:

and click on the “Linux system” tab. The screen displays the current version information:

In the example above, the version is 12642.

The same information can be obtained at the command line by using gconfig and selecting “Version and serial number information”. If you just want quick access to the software build number, this is contained in the file /etc/build.version, which can be read with the command:

eam2243 ~ # cat /etc/build.version
# Overall build version
BUILD_LABEL="platinum-stable"
BUILD_VERSION="12642"
eam2243 ~ #

The version, in this case, can be seen to be 12642.

5.3 Upgrade Methods

This section describes three different methods of upgrading the firmware.

In order to be upgraded, the unit needs access to the latest version of the firmware. If an internet connection is available, Güralp Systems Ltd's software repository can be used. This method is described in section 5.3.1.

If a number of units share a common network but that network is not connected to the internet, you can make you own copy of the software repository on a PC or laptop, which can be connected the network either permanently or temporarily, and use that as the upgrade source. This method is described in section 5.3.2.

If one or more units are to be upgraded but Internet access is not available, the new firmware can be copied to a USB storage device, such as a memory stick, and the upgrade performed from that. This method is described in section 5.3.3.

5.3.1 Upgrading via the internet

In order to upgrade over the Internet from Güralp Systems Ltd's software repository, the unit must have its networking properly configured. In particular, a DNS (Domain Name Service) server and a default gateway (or default route) must both be configured. It is advisable to check these before proceeding or in the event of problems preventing a successful upgrade.

To check for correct configuration of both of these items, issue the command:

ping -c3 rsync.guralp.com

This will send three “echo request” packets to the GSL upgrade server and listen for responses. If both the DNS server and the correct gateway (default router) are configured, the output will look like this:

eam2010 ~ # ping -c3 rsync.guralp.com
PING rsync.guralp.com (80.68.92.160): 56 data bytes
64 bytes from 80.68.92.160: seq=0 ttl=55 time=58.280 ms
64 bytes from 80.68.92.160: seq=1 ttl=55 time=66.845 ms
64 bytes from 80.68.92.160: seq=2 ttl=55 time=56.413 ms
--- rsync.guralp.com ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 56.413/60.512/66.845 ms
eam2010 ~ #

If the DNS server is correctly configured but the gateway is not correctly configured, the output will look like this:

eam2010 ~ # ping -c3 rsync.guralp.com
PING rsync.guralp.com (80.68.92.160): 56 data bytes
ping: sendto: Network is unreachable
eam2010 ~ #

If you are using DHCP, it is advisable to correct this problem by reconfiguring the DHCP server to supply the correct route. If you are using static addressing, enter the address of the Internet gateway router in the “Default route (gateway)” field of the network interface configuration form. See section 7.1.2 for more details.

If the DNS server is not configured correctly (or at all), the output will look like this:

eam2010 ~ # ping -c3 rsync.guralp.com
ping: bad address 'rsync.guralp.com'
eam2010 ~ #

If you are using DHCP, it is advisable to correct this problem by reconfiguring the DHCP server to supply the correct name-server details. If you are using static addressing, enter the address of a suitable DNS server in the “Nameserver” field of the network interface configuration form (only available in expert mode). See section 7.1.2 for more details.

Note: If your internet connection is via a firewall, you must ensure that port 873 (rsync) is open for TCP connections initiated by the acquisition module. The following paragraphs explain how to check this.

To check that your internet connection is correctly configured, enter the command:

rsync rsync.guralp.com::

The output should look like this:

eam2010 ~ # rsync rsync.guralp.com::
platinum-crosslib Libraries required for cross-compiling on the Platinum platform
platinum-stable Stable filesystems for the Platinum platform
platinum-builder Open source parts of Platinum firmware build tree (large)
eam2010 ~ #

Any other output indicates a problem with your firewall – consult your network administrator or see the trouble-shooting advice in section 16.4.

Once the network has been checked, you can proceed to upgrade the unit by following the instructions in section 5.4.

5.3.2 Upgrading from a local mirror

Setting up a mirror involves three steps:

Note: Due to Windows file-system restrictions, it is only possible to build a mirror server on a PC or laptop running Linux.

5.3.2.1 Downloading the mirror content

The mirror can occupy a significant amount of disk-space, depending on which architectures you need to support. See the sections for each architecture (below) for the current space requirements. You should pick a file-system with ample space in which to store your own copy. In order to simplify the download, we recommend that you start with an empty directory each time. If you wish to make a fresh copy after a new firmware release, it is much easier to create this in an empty directory than to "update" an existing mirror. You can keep multiple, simultaneous versions of the firmware if you wish and tell each acquisition device which version to use when upgrading.

The server on which you create the mirror should have access to the Internet during the download step but does not need Internet access while it is acting as an upgrade server. It does, of course, need to be accessible by your networked acquisition devices. It is possible to create the mirror content on a removable mass storage device attached to an Internet-connected computer and then move the device to a different computer when performing the upgrades. The removable mass storage device must use a Linux-compatible file-system, such as ext3. FAT- and NTFS-formatted devices will not work properly for this purpose.

Create the mirror directory and use the cd command to make it your current directory. As root, enter one or more of the following command sequences to download the mirror content. Each sequence downloads the files for a particular architecture. If you know, for example, that you will never want to upgrade a CMG-NAM64, you can omit the commands for this architecture.

Note: Be careful not to omit the final ‘.’ or the space before it in the rsync commands below.

CMG-DCMs

This architecture currently requires around 50MB of mass storage device space for the mirror. The commands to download the content are:

GSLSRC=rsync.guralp.com/platinum-stable/CMG-DCM-mk2x
rsync -EgHloprtv --exclude resolv.conf rsync://$GSLSRC .

CMG-EAMs

There are currently two sets of firmware available for the CMG-EAM: a frozen image of build 3801 (for users who do not yet wish to upgrade to post 10,000 builds) and the latest build.

If you do not wish to upgrade beyond build 3801 yet, the files for build 3801 require around 53MB of storage space for the mirror. Use the following commands:

GSLSRC=rsync.guralp.com/platinum-stable/CMG-DCM-mk4
rsync -EgHloprtv --exclude resolv.conf rsync://$GSLSRC .

If the systems being upgraded are already at build 10,000 or later, you only require the latest build, which occupies around 70MB of space. Use the following commands:

GSLSRC=rsync.guralp.com/platinum-stable/CMG-DCM-mk4-eabi
rsync -EgHloprtv --exclude resolv.conf rsync://$GSLSRC .

If you are upgrading systems from earlier than build 3801 to the current build, you will need both sets of firmware, requiring around 123MB of storage. Use the following commands (note the additional punctuation):

GSLSRC='rsync.guralp.com/platinum-stable/CMG-DCM-mk4*'
rsync -EgHloprtv --exclude resolv.conf rsync://”$GSLSRC” .

CMG-NAMs

This architecture currently requires around 94MB of mass storage device space for the mirror.

GSLSRC=rsync.guralp.com/platinum-stable/CMG-NAM
rsync -EgHloprtv --exclude resolv.conf rsync://$GSLSRC .

CMG-NAM64s

This architecture currently requires around 125MB of mass storage device space for the mirror.

GSLSRC=rsync.guralp.com/platinum-stable/CMG-NAM64
rsync -EgHloprtv --exclude resolv.conf rsync://$GSLSRC .

5.3.2.2 Setting up a local rsync server

Your local rsync server is configured by creating the file /etc/rsyncd.conf. If the serving host already runs an rsync server, you should modify this file (by adding an extra module) in order to allow access from the acquisition devices to the mirror directory: we assume that you have the knowledge to do this without further assistance. This section covers setting up a new, dedicated rsync server.

You will need to choose a TCP port number which will not conflict with another service on your network. The port number should be greater than 1024 in order to avoid additional complexity. Consult your network administrator for an available port or simply try 61616 and, if you get an error saying that the port is in use when you attempt to start the server, choose a different random number in the range 49152 - 65535. 61616 will be used in the following example and should be replaced with the port number you have chosen or been allocated. If there are firewalls between your server and the acquisition devices, you will need to open channels through them for this port.

You will also need to choose a module name for the server. This can be any descriptive string but, for simplicity, it is best to stick to numbers, lower-case letters and hyphens (-). The name platinum-local-mirror has been used in the following example and should be replaced with the module name you have chosen.

Create the file /etc/rsyncd.conf with the following contents:

port = 61616
[platinum-local-mirror]
path = /path/to/your/local/mirror/directory
comment = GSL-EAM firmware
numeric ids = yes
log file = /path/to/writeable/log/file
timeout = 600
hosts allow = *

Consult the manual page for rsyncd.conf(5) for details of further options that you can use in this file, including optional security improvements. This is available on-line at https://download.samba.org/pub/rsync/rsyncd.conf.html.

Once the /etc/rsyncd.conf file is ready, you can start the rsync server with the command

sudo rsync --daemon

If you want to run the rsync server permanently, it is possible to start it via inetd, xinetd or an rc script. Consult the manual page for rsyncd.conf(5) for further details.

5.3.2.3 Configuring the upgrade system to use the new server

The standard upgrade source must be over-ridden: on each system to be upgraded. Create the file /etc/conf.d/upgrade.local with the following contents:

RSYNC_HOST="address.of.my.server”
RSYNC_PORT="61616"
RSYNC_MODULE="platinum-local-mirror"

replacing:

Note the quotation marks around the variables.

The acquisition devices can now be updated from the mirror by following the instructions in section 5.4. Note that the configuration files /etc/conf.d/upgrade.local on each acquisition devices will not be disturbed by the upgrade process and, so, only need to be created once.

5.3.3 Upgrading from a USB storage device

For situations where it is either impossible or undesirable to upgrade over a network, Güralp Systems Ltd can supply the latest Platinum firmware on a USB memory stick, along with an appropriate adaptor cable, part number CAS-DCM-0038.

The adapter cable is required when upgrading the firmware of most acquisition module units but not when upgrading a CMG-NAM.

You will need both physical access and command-line access to the device being upgraded. Command-line access may be via ssh or a serial connection.

To upgrade the firmware from a USB storage device:

Note: Certain upgrades (depending on the initial version number) make it difficult or impossible to reboot the system via the web interface. In these cases, the system can be rebooted from the command line (with the reboot command) or by power-cycling.

5.3.4 U3 USB mounting problems

U3 was a method of launching Windows applications from special USB flash drives. A U3 flash drive presents itself to the host system as a USB hub with a CD drive and standard USB mass storage device attached.

Reformatting the drive will remove some of the software (the hidden "SYSTEM" folder), but not all of it. The virtual CD-ROM drive cannot be removed by reformatting because it is presented to the host system as a physical device attached to a USB hub.

U3 Tool is an open-source management tool (for Windows and Linux) that allows the locked U3 partition to be removed.

The U3 tool is available from http://resourcelessness/projects/u3-tool/files/.

5.3.4.1 MS Windows

Open a command prompt and change the directory to that where the U3 tool was installed. To see all options, enter the command:

u3-toolmaker

To repartition the device, enter the command:

u3-toolmaker -p 0 E

replacing E with the device's drive letter

5.3.4.2 Linux 2.6.20+

To see all options, enter the command:

u3-tool

To repartition the device enter the command:

./u3_tool -U /dev/sg3

Replace /dev/sg3 with the SCSI generic device associated with your device. The correct device can be deduced from the output from the command dmesg.

5.3.4.3 Linux 2.4

To unlock the “secured data partition” using Linux's USB subsystem:

# modprobe -r usb-storage
# ./u3_tool -u scan
# modprobe usb-storage

After unlocking, the device can be used normally.

5.4 Upgrade Types

There are three different types of upgrade, each of which is described below. When upgrading via the web interface, the desired type is selected by pressing the appropriate button. When upgrading directly from the command line or from a USB storage device, the required type is selected by the use or omission of command-line arguments.

5.4.1 Standard upgrade

The standard upgrade brings the firmware to the latest revision while respecting and preserving all configuration settings.

Note: All files on any connected hard drive or USB drive are left untouched, as are any files in the directories /home, /root, /var and /usr/local. In addition, any file with an extension of .local will be preserved: this is the mechanism by which most configuration settings are safeguarded.

To perform a standard upgrade from the web interface, select:

The following screen will be displayed:

Press the button and watch the screen for any error messages.

To perform the same upgrade from the command line, simply enter the command:

eam999 ~ # upgrade

with no arguments. Watch the screen for any error messages and then reboot to complete the process.

Note: Certain upgrades (depending on the initial version number) make it difficult or impossible to reboot the system via the web interface. In these cases, the system can be rebooted from the command line (with the reboot command) or by power-cycling.

5.4.2 Upgrade and restore defaults

The standard upgrade respects and preserves user configuration settings. In some circumstances it may be necessary to overwrite these settings and return all configuration settings to their factory defaults. The unit is not completely restored to factory condition: this allows for the possibility of implementing customisations and user-developed scripts which persist across upgrades.

Note: All files on any connected hard drive or USB drive are left untouched, as are any files in the directories /home, /root, /var and /usr/local. Files with the extension .local are deleted.

To restore defaults while upgrading from the web interface, select:

and then click

The following screen will be displayed:

The first button, , does exactly the same as the similar button on the previous screen. The button performs the action described in this section.

To perform this action from the command line, invoke the upgrade script with the argument --restore-defaults:

eam999 ~ # upgrade --restore-defaults

Watch the screen for any error messages and then reboot the unit to complete the process.

Note: Certain upgrades (depending on the initial version number) make it difficult or impossible to reboot the system via the web interface. In these cases, the system can be rebooted from the command line (with the reboot command) or by power-cycling.

5.4.3 Upgrade and force factory defaults

The third upgrade option effectively wipes everything (other than files on any connected hard drive or USB drive) while installing the new firmware revision, leaving the unit as it would be delivered. Avoid using this option if you have made any customisations to your unit or installed any scripts. If in doubt, please consult Güralp Systems Ltd technical support for advice before proceeding. Conversely, if you have made changes which you believe have adversely affected the unit but are having trouble undoing them, this option lets you start with a clean slate.

To invoke this option from the web interface, select “Firmware” from the “Tools” menu and then click the button. From the resulting screen, press the button. Watch the screen for any error messages and then reboot the unit to complete the process.

Note: Certain upgrades (depending on the initial version number) make it difficult or impossible to reboot the system via the web interface. In these cases, the system can be rebooted from the command line (with the reboot command) or by power-cycling.

To perform this action from the command line, invoke the upgrade script with the argument --force-factory-settings:

eam999 ~ # upgrade --force-factory-settings

Watch the screen for any error messages and then reboot the unit to complete the process.

5.5 Upgrade logs

The upgrade process stores all progress and error messages in the file /var/log/upgrade.log. If you suspect that there has been a problem with an upgrade or you wish to have full details of what has changed, you can inspect this file by issuing the command

eam999 ~ # less /var/log/upgrade.log

You can scroll forward through the file simply by pressing the key. For more control, you can move forward and backwards, line by line, with the and keys or, page by page, with the and keys.

The key should be used to return to the command line.

If you wish to obtain a copy of this log file, it can be copied from the system to an external computer either via the serial port (see section 11.3.1.4) or over the network (see section 11.3.1.2).