Upgrading mLinux

Upgrading mLinux using an image install

The command /usr/sbin/mlinux-firmware-upgrade may be used to upgrade the firmware. The upgrade file should be placed in /var/volatile or one of its subdirectories. The command must be run as the root user.

There are two types of upgrade files. One type is created by the build named *upgrade*.bin and found in the deploy image directory of the build see:

https://www.multitech.net/developer/software/mlinux/mlinux-building-images/building-a-custom-linux-image/

Example image upgrade files:

build/tmp/deploy/images/mtcdt/mlinux-factory-image-mtcdt-upgrade.bin
build/tmp/deploy/images/mtcap/mlinux-mtcap-image-mtcap-upgrade-withboot.bin

Be sure to use the correct image upgrade file for the appropriate hardware platform. For MTCDTIP2, use the mtcap image upgrade file.

Files with withboot in the name include the bootstrap and U-Boot partitions. Unless you are upgrading from mLinux™ 3 to mLinux 4, it is usually not necessary to update bootstrap or U-Boot.

Note: For images installed with mLinux 5.2x or higher, user passwords are removed and Commissioning mode starts after reboot. Refer to Commissioning for mLinux Devices for more details.

Updating packages during a reboot (for mLinux 4.0 or higher)

The second type of upgrade file does not do a complete firmware update. It updates packages using the opkg command. A package update only affects packages that are changed. Unlike an image update, most files are maintained.

The purpose of updating packages during a reboot is to provide greater resources (memory and temporary file space) for the upgrade. Very small upgrades to commands can be applied without rebooting using the opkg command and the feeds. See: http://www.multitech.net/mlinux/feeds

If you have initscripts 2.0-r155.43 (mLinux 4.0.0 or greater), it is possible to upgrade packages using mlinux-firmware-upgrade.

These files are found at http://www.multitech.net/mlinux/upgrades/ when available. Choose your device (mtcdt or mtcap). The version pertains to the specific firmware update or where a fix applies.

Since these are not image updates, they may take longer to apply. They leave the configuration alone, except for the packages being updated. For example, the login password(s) will not change. NOTE: Make sure that newly installed packages are correctly configured.

Creating an update package that uses opkg

This method uses opkg and local files.

See an update package example: http://multitech.net/mlinux/upgrades/example/

Carefully review the  initial list of packages and verify that they match the final list. Packages may be split or merged. In these cases a package may need to be removed or added, not
just updated. Packages may require other packages. So dependencies also need to be in the update package tree. An easy way to determine what packages are required is to use the mLinux feeds, http://www.multitech.net/mlinux/feeds/ with opkg. The file /etc/opkg/mlinux-feed.conf may need to be configured for the desired level of mLinux in the update.

The update package is a tar file containing IPK files and a shell script to initiate the update.

Tree

The final tree in this example looks as follows:
.
├── build.sh
├── install_list.txt.md5
├── install.sh
├── install.sh.md5
├── install.template
├── local.conf.md5
├── log.txt
├── model
├── remove_list.txt.md5
└── update-4.0.0

├── install_list.txt
├── install_list.txt.md5
├── local.conf
├── local.conf.md5
├── remove_list.txt
├── remove_list.txt.md5
└── repo

├── arm926ejste
│      ├── bluez5_5.47-m3.0_arm926ejste.ipk
│      ├── bluez5-noinst-tools_5.47-m3.0_arm926ejste.ipk
│      ├── bluez5-obex_5.47-m3.0_arm926ejste.ipk
│      ├── bluez5-pand_5.47-m3.0_arm926ejste.ipk
│      ├── bluez5-rfcomm_5.47-m3.0_arm926ejste.ipk
│      ├── bluez5-testtools_5.47-m3.0_arm926ejste.ipk
│      ├── libasound-module-bluez_5.47-m3.0_arm926ejste.ipk
│      ├── libmts-io0_1.0.8-r0.0_arm926ejste.ipk
│      ├── lora-network-server_2.0.19-r4.0_arm926ejste.ipk
│      ├── Packages
│      ├── Packages.gz
│      ├── Packages.stamps
│      ├── python-pybluez_0.22-r0.0_arm926ejste.ipk
│      └── python-terminal_2.7.12-r1.0_arm926ejste.ipk
├── mtcap
│      ├── mlinux-version_4.0.1_ea6ba1..2713b2-r2.0_mtcap.ipk
│      ├── mts-id-eeprom_0.3.8-r1.0.0_mtcap.ipk
│      ├── Packages
│      ├── Packages.gz
│      └── Packages.stamps
├── mtcdt
│      ├── mlinux-version_4.0.1_ea6ba1..2713b2-r2.0_mtcdt.ipk
│      ├── mts-id-eeprom_0.3.8-r1.0.0_mtcdt.ipk
│      ├── Packages
│      ├── Packages.gz
│      └── Packages.stamps
└── Packages

Generated Files

The files ending in ipk must be gathered from either a build, or the mLinux feeds found from the downloads page under Conduit®: mLinux Model. The files ending in md5 are created by build.sh. The files that start with Packages* are created by the Yocto package-index operation. install.sh is created from install.template by the build.sh script.

Purpose of files in package

  • install_list.txt is a list of packages to be installed.
  • delete_list.txt is a list of packages to be deleted. No IPK files need to be supplied in order to remove a package.
  • package list contains the names of packages to be added or removed. An example from the install_list.txt file would be:
           python-terminal

Python-terminal is not normally installed in mLinux, but is available from the feeds. Likewise the file delete_list.txt contains gpsd-udev. This package is required by gpsd, but is used to find GPS’s over the USB bus, which is not needed by the device (unless you plug a GPS into a USB port).

OPKG Configuration

local.conf is the opkg configuration file. It tells opkg the location of update packages.

Example local.conf:

# Set mtcap instead of mtcdt for mtcap
arch all 1
arch any 6
arch noarch 11
arch arm 16
arch armv4 21
arch armv4t 26
arch armv5 31
arch armv5t 36
arch armv5e 41
arch armv5te 46
arch arm926ejste 51
arch arm926ejse 56
arch mtcdt 61
arch mtcap 61

src/gz mlinux-mtcdt file://FLASHDIR/repo/mtcdt
src/gz mlinux-mtcap file://FLASHDIR/repo/mtcap
src/gz mlinux-arm926ejste file://FLASHDIR/repo/arm926ejste

In this case, FLASHDIR is replaced at install time by the install.sh script, and either the line containing mlinux-mtcdt or mlinux-mtcap is removed depending on the device hardware.

Creating opkg Required Files

To create a set of packages, have a Yocto 2.2 build system in order. Place the desired packages under build/tmp/deploy/ipk/ in all, mtcdt, mtcap, arm926ejste, as appropriate. Remove any unneeded ipk files from build/tmp/deploy/ipk.

Example:

$ cd build/tmp/deploy/ipk
$ ls
arm926ejste mtcap mtcdt Packages
$ rm -rf *
$ # Now copy the files from the upgrade tree
$ cp -a ~/update-example/my-upgrade/repo/* .
$ bitbake package-index
…

NOTE: Tasks Summary: Attempted 161 tasks of which 159 didn't need to be rerun and all succeeded.
Summary: There was 1 WARNING message shown.

Building the package index will create or update files named Packages*

repo/arm926ejste/Packages
repo/arm926ejste/Packages.gz

The Packages.gz file is used by opkg to test the packages for corruption and to provide a description. Packages provides the same file, uncompressed, for reference.

After that, the files need to be copied back:

cd build/tmp/deploy/ipk
cp -a * ~/update-example/my-upgrade/repo/

Installer script

The file install.sh is the installer script. To make life easier, this file is derived from a template file, which is updated by the build.sh script.

Example instructions in the install.template script:

#!/bin/bash
# This script works with a tar archive
# called upgrade.bin and is intended for
# use with mlinux-firmware-upgrade
NAME=install.sh
echo "$NAME starting in directory $(pwd)"
cd flash-upgrade/update-4.0.0
id=$(id -u)
if ((id != 0)) ; then
     echo 'You must be root (admin in AEP) to install packages.'
     exit 1
fi

cat /proc/mounts
ls /
ls -l /tmp
localcnf=local.conf
if ! [[ -f ${localcnf} ]] ; then
     echo "Cannot find ${localcnf}"
     echo "This file must be in the current directory."
     exit 1
fi
dir=$(pwd)
sed -i "s?FLASHDIR?${dir}?" ${localcnf}
machine=$(mts-io-sysfs show product-id | sed 's/-.*//')
if [[ $machine == MTCAP ]] ; then
     # remove mtcdt
     sed -i '/mtcdt/d' ${localcnf}
else
     # remove mtcap
     sed -i '/mtcap/d' ${localcnf}
fi
cat ${localcnf}
pkglist_file="install_list.txt"
cat ${pkglist_file} |
(if ! md5sum -c ${pkglist_file}.md5 ; then
     echo "md5sum bad on ${pkglist_file}"
     umount_all error
fi)
cat ${localcnf}
pkglistrm_file="remove_list.txt"
cat ${pkglistrm_file} |
(if ! md5sum -c ${pkglistrm_file}.md5 ; then
     echo "md5sum bad on ${pkglistrm_file}"
     umount_all error
fi)
echo "Update package list ... /usr/bin/opkg -f ${localcnf} update"
/usr/bin/opkg -t /var/volatile/ -f "${localcnf}" update
/usr/bin/opkg -t /var/volatile/ -f "${localcnf}" upgrade
if [[ -r ${pkglistrm_file} ]] ; then
     OIFS="${IFS}"
     IFS=$'\n'
     for p in $(cat ${pkglistrm_file}) ; do
          echo /usr/bin/opkg --force-depends -t /var/volatile/ -f "${localcnf}" install $p
          /usr/bin/opkg opkg --force-depends -t /var/volatile/ -f "${localcnf}" remove $p
     done
     IFS="${OIFS}"
fi
if [[ -r ${pkglist_file} ]] ; then
     OIFS="${IFS}"
     IFS=$'\n'
     for p in $(cat ${pkglist_file}) ; do
          echo /usr/bin/opkg -t /var/volatile/ -f "${localcnf}" install $p
          /usr/bin/opkg -t /var/volatile/ -f "${localcnf}" install $p
     done
     IFS="${OIFS}"
fi
version=$(grep mLinux /etc/mlinux-version | sed 's/mLinux //')
sed -ri "s/mLinux [0-9][^ ]* /mLinux ${version} /" /etc/issue
sed -ri "s/Version: [0-9][^ ]*/Version: ${version} /" /etc/issue

Build Script

To generate the package, there is a script for that purpose, called build.sh:

#!/bin/bash
dir=$(ls -d update-*)
sed "s/UPGRADE_DIR/${dir}/" install.template >install.sh
echo "Upgrade directory is ${dir}"
cat install.sh | md5sum >install.sh.md5
cd update-*
cat local.conf | md5sum >local.conf.md5
cat install_list.txt | md5sum >install_list.txt.md5
cat remove_list.txt | md5sum >remove_list.txt.md5
cd ..
set -x
chmod +x install.sh
tar --owner=0 --group=0 -cJf ~/${dir}.bin model install.sh* update-*

The script assumes a directory starting with update- in the current directory. The directory name is used to create the tar file called ${dir}.bin. This file is then copied to /var/volatile, and mlinux-firmware-upgrade ${dir}.bin is executed as root to update the packages. The file http://www.multitech.net/mlinux/upgrades/example/log.txt shows what to expect during the package installs, removals, and upgrades.