Howto migrate an I2SE EVAcharge SE with Debian-based Firmware to a Yocto-based Firmware

Introduction

I2SE (or now chargebyte) used to ship these devices with a simple Debian-based example firmware installed in the eMMC. These devices used the imx-bootlets project as bootloader. The eMMC consists only of the bootloader partition and one big root filesystem.

Later in time, I2SE used the RAUC project for there firmware updates. For this, they switched to a A/B system setup and changed the partitioning of the eMMC accordingly. The bootloader was also switched to U-Boot to support the switching between the A and B system. This concept was also kept when switching to Yocto-based BSPs.

Upgrading from an older Debian-based firmware to an Yocto-based firmware is not trivial when it should be done in the field. The reason is that you have to change the partitioning on-the-fly.

The following instructions demonstrates that such an update is technically possible and give you the files as example at hand.

Disclaimer: While the author of this document tested the whole procedure, there is no guarantee that it works flawlessly or applies to all real-world setups. There is a risk that you brick your devices and that it is not reachable again over network. Depending on what went wrong in this case, a technician might be required at the charger to physically replace the board.

Concept

The main problem is that you cannot re-partition the eMMC while it is in use by the Linux kernel. The solution is to use a tiny RAM-based Linux system which solely operates during the hot phase of the migration. The main idea used here is, that the “old” system is prepared, then runs the migration and finally boots into the fully updated system running Yocto.

During the preparation phase of the old system, at least three files have to be downloaded to the old root filesystem:

• the new root filesystem: It is out of scope of this document how this file is generated. Is must contain a valid ext4 filesystem including the /boot folder with zImage and device tree blobs as expected by U-Boot later. The filesystem must also be in a sane state, this is important since during the process it will be expanded to the full partition size (and this will fail otherwise). Is is assumed that this file will be generated using chargebyte’s Yocto BSP. The file must be compressed using gz – this is required since it must fit into the old root filesystem. The exact maximum size depends on the other files in the old root filesystem. During the re-partitioning the original root filesystem is shrunken to around 2 GB.
• the new U-Boot bootloader: This is the bootloader which is installed during the migration phase and bring the system later up again.
• the migration Linux system: As mentioned, this is a tiny RAM-based Linux system. The example used here was created using OpenWrt. The rough idea is here, that an initramfs is embedded in a small kernel which brings enough functionality to re-partition the eMMC, writes out the root filesystem to the final destination(s) and install the new boot loader. The migration script is already included so that the process can run without any interaction to other systems. After the complete eMMC is updated, the system is finally rebooted and starts the new system from eMMC. If everything worked well, then the EVAcharge SE is up again with a fresh Yocto-based firmware.

The install procedure provides two hooks for your customizations: one hook is available before the actual migration was started, e.g. to save some configuration data, one hook is available after the eMMC was updated.

The RAM-based Linux configures the network interface for DHCP. Also an SSH server is started – without any password set. That means that during the migration any user on the network could log into the system as user root.

Hands-On

It is out of scope of this document, how the files are transferred to the old system. You need at least:

• The new rootfs: e.g. core-image-minimal-evachargese-20241010083828.rootfs.ext4.gz
  This file must be placed in the top-level directory of the old root filesystem, i.e. just below /. The filename must end in .rootfs.ext4.gz
• The new bootloader: e.g. evachargese_u-boot.sb
  This file must also be placed in the top-level directory of the old root filesystem, i.e. just below /. The filename must end in .sb

You have to place these two files first in the correct location before installing the migration firmware. Otherwise, the migration firmware would already boot-up in case of sudden power-losses and finds nothing to use.

The migration firmware: mmcblk0p1.img
This file must be written to the old bootloader partition. In contains the described RAM-based Linux system. Use e.g. the following command: dd of=/dev/mmcblk0p1 if=mmcblk0p1.img

Optional files can be placed in the root filesystem:

• install-pre-hook.sh: As mentioned, this file can be used to do some custom actions before the migration is actually started. Is must be executable and must reside also in the top-level directory of the old root filesystem. When this script is started, then the new firmware and the bootloader are already copied over to the new /srv partition which is also already mounted on /srv. The old system is mounted on /mnt. You can save e.g. other configuration files also to /srv.
• install-post-hook.sh: Similar here, the file must be executable and reside on top-level root filesystem. In contrast to the pre-hook, there nothing is mounted anymore – you have to take care yourself.

For your information, here is the actual migration shell script used by the firmware:

#!/bin/sh

# Assumptions:
# The image of the new target rootfs is gz compressed and
# stored in the root directory (/) of the old rootfs (/dev/mmcblk0p2)
# with a filename ending in '*.rootfs.ext4.gz'.
# The boot loader U-Boot is stored at the same location
# with filename ending in '*.sb'

# exit on errors
set -e

# fs check is required before resize
e2fsck -y -f /dev/mmcblk0p2

# shrink current filesystem so that it fits smaller than final two rootfs
resize2fs -f /dev/mmcblk0p2 2032M || true

# re-partition first round - create future /srv partition already at its final location
cat <<EOF | sfdisk /dev/mmcblk0
label: dos
label-id: 0x5452574f
device: /dev/mmcblk0
unit: sectors

/dev/mmcblk0p1 : start=        2048, size=       16384, type=53, bootable
/dev/mmcblk0p2 : start=       20480, size=     4161536, type=83
/dev/mmcblk0p3 : start=     4212736, size=     2097152, type=83
EOF

# format /srv
mkfs.ext4 -F -F /dev/mmcblk0p3

# mount old rootfs and /srv
mount /dev/mmcblk0p2 /mnt
mkdir -p /srv
mount /dev/mmcblk0p3 /srv

# save file we still need from old rootfs
cp /mnt/*.sb /srv
cp /mnt/*.rootfs.ext4.gz /srv

# run pre-install hook if present
[ -x /mnt/install-pre-hook.sh ] && . /mnt/install-pre-hook.sh

# umount again - partition number will change
umount /mnt /srv

# re-partition 2nd time - final partition layout
cat <<EOF | sfdisk /dev/mmcblk0
label: dos
label-id: 0x6d686569
device: /dev/mmcblk0
unit: sectors

/dev/mmcblk0p1 : start=        2048, size=       14336, type=53
/dev/mmcblk0p2 : start=       16384, size=     2097152, type=83
/dev/mmcblk0p3 : start=     2113536, size=     2097152, type=83
/dev/mmcblk0p4 : start=     4210688, size=     2627584, type=5
/dev/mmcblk0p5 : start=     4212736, size=     2097152, type=83
/dev/mmcblk0p6 : start=     6311936, size=      262144, type=83
/dev/mmcblk0p7 : start=     6576128, size=      262144, type=83
EOF

# mount /srv again
mount /dev/mmcblk0p5 /srv

if [ -z "$SKIP_ROOTFS2" ]; then
    # write rootfs partition 2
    zcat /srv/*.rootfs.ext4.gz | dd of=/dev/mmcblk0p3 bs=4M
    resize2fs /dev/mmcblk0p3
fi

# write rootfs partition 1
zcat /srv/*.rootfs.ext4.gz | dd of=/dev/mmcblk0p2 bs=4M
resize2fs /dev/mmcblk0p2

# cleanup U-Boot environment
dd if=/dev/zero of=/dev/mmcblk0 bs=1k count=128 seek=128
dd if=/dev/zero of=/dev/mmcblk0 bs=1k count=128 seek=256

# write U-Boot
sdimage -f /srv/*.sb -d /dev/mmcblk0

# cleanup & reboot
umount /srv
sync

# run pre-install hook if present
[ -x /mnt/install-post-hook.sh ] && . /mnt/install-post-hook.sh

reboot

As you can see, if something goes wrong, the script terminates and the system is remains in this state – it is reachable via SSH until the next power cycle. After a power cycle, it depends whether the new bootloader was already installed or whether the migration firmware is still in place.

There is also a small weakness of the whole procedure: a power outage during the bootloader installation will most probably brick the system. This is why it is done last. In case a power outage happens before, then the whole re-flashing procedure is simply restarted from scratch.

More History - Yet Another Partitioning Scheme

As found out later, there exists an even older partitioning scheme consisting of 4 partitions: a FAT partition, the bootstream partition, the root filesystem and yet another ext4 partition.

Also these devices can be migrated to the new Yocto approach. Here the advantage is that the rootfs partition must not be reduced in size during the conversion. However, the bootstream partition is in the way and thus moved so that the system should survive a potential power outage during the migration process.

The migration script was adapted accordingly, the latest version can be found on Github, see below. But while the tiny migration Linux system is in core the same, the partition image is slightly different due to other offsets in the bootstream headers.

So you have to use the following migration firmware: mmcblk0p2.img

The installation and remaining features are the same, just replace the content of the second partition with the provided file.

Important Notes

• The U-Boot bootloader has a special area, the U-Boot environment. During the migration this area is blanked out, so that there is no garbage hanging around. This means that when U-Boot is started for the first time, is uses its built-in default environment.
• When the first boot of the new root filesystem happens, then the default chargebyte BSP formats the partitions which are mounted later on /var/log and /srv. That means that these partitions are not useful to store data between the migration – unless your hook scripts takes special of this.
• Both hook scripts are sourced into the currently running script. This is so that they can e.g. environment variables to pass information from the pre-hook to the post-hook. But this also means that you can exit the whole migration script, or that failed commands cancel it.
• The partitioning scheme used here is not exactly the same what chargebyte uses in its device when shipped from factory. The only difference is that the bootloader partition here is 7 MB large, while chargebyte only uses a 3 MB partition. The reason why we use a 7 MB partition here is that we want to keep the migration firmware in-place as long as possible to reduce the risk of broken devices in the field. This small difference should not be relevant in real life - and thus it is fully-compatible to chargebyte's BSP.
• Unless the pre-hook is used to set the environment variable SKIP_ROOTFS2, both root filesystems are written. Writing a single partition already takes its time - writing both partitions doubles the overall time.

Sources

Last update: 2025-01-10, mhei